> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.solvimon.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.solvimon.com/_mcp/server.

# Connect with OAuth

An MCP client signs in with your own Solvimon login instead of an API key in a configuration file. The client registers itself, you approve it on a consent screen in Desk, and it receives a token scoped to the platforms you picked.

---

## Why this matters

Connecting a client with an API key means pasting a long-lived credential into a configuration file on your machine. That key is as powerful as the account behind it, it does not expire, and nothing records which tool is using it.

OAuth replaces that. The client never sees a key. It gets a token that belongs to you, limited to the platforms you approved and the access it asked for, and you can see what you authorised. Setting it up is entering a URL and logging in, with no registration on Solvimon's side.

## How it works

Solvimon's identity host is an OAuth 2.0 authorization server. Clients discover it, register themselves, and run the authorization code flow with PKCE.

```mermaid
sequenceDiagram
    participant C as MCP client
    participant I as Solvimon identity
    participant D as Desk (consent)
    C->>I: GET /.well-known/oauth-authorization-server
    I-->>C: endpoints, scopes, PKCE methods
    C->>I: POST /v1/oauth2/register
    I-->>C: client_id
    C->>I: GET /v1/oauth2/authorize (+ code_challenge)
    I-->>D: redirect to the consent screen
    D->>D: you log in, pick platforms, approve
    D-->>C: redirect back with a one-time code
    C->>I: POST /v1/oauth2/token (code + code_verifier)
    I-->>C: access token
```

Solvimon registers **public clients** only: a desktop application cannot keep a secret, so there is no client secret anywhere in this flow. PKCE is what proves that the client redeeming the code is the one that started the flow.

### Discovery

Two documents sit at the root of the identity host:

| Document                                  | What it carries                                                                                                                                        |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/.well-known/oauth-authorization-server` | The issuer, the authorize, token and registration endpoints, the supported scopes, response types and grant types, and `S256` as the only PKCE method. |
| `/.well-known/jwks.json`                  | The public keys that verify the tokens Solvimon issues.                                                                                                |

**`Read the metadata`**

```bash Read the metadata
curl https://identity.solvimon.com/.well-known/oauth-authorization-server
```

`token_endpoint_auth_methods_supported` is `["none"]`, `grant_types_supported` is `["authorization_code", "refresh_token"]`, and `response_types_supported` is `["code"]`.

### Registration

A client that has never spoken to Solvimon registers itself with `POST /v1/oauth2/register`. The call needs no credentials, because a client that has never spoken to us has nothing to authenticate with:

**`Register a client`**

```bash Register a client
curl -X POST https://identity.solvimon.com/v1/oauth2/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Claude Code (my-laptop)",
    "redirect_uris": ["http://127.0.0.1:51703/callback"]
  }'
```

**`Response 201`**

```json Response 201
{
  "client_id": "...",
  "client_name": "Claude Code (my-laptop)",
  "redirect_uris": ["http://127.0.0.1:51703/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_method": "none"
}
```

Metadata Solvimon does not understand is ignored rather than refused, as the specification requires. A rejected redirect URI answers `invalid_redirect_uri`, and other bad metadata answers `invalid_client_metadata`.

### Scopes

| Scope            | Access                                          |
| ---------------- | ----------------------------------------------- |
| `solvimon:read`  | Read the resources the approving user can read. |
| `solvimon:write` | Create and change them.                         |

A client asks for one or both on the authorize call. Scopes Solvimon does not recognise are dropped rather than refused, and a request that ends up naming none is narrowed to `solvimon:read`. The consent screen shows what was granted, read back from the stored request, not what the client asked for.

### The consent screen

The authorize call sends the browser to Desk, where you sign in with your normal Solvimon account. The screen names the application, shows the access it is asking for, and lists the platforms you are a member of. You pick which of them the client may reach, then approve or deny.

> **Note**
>
> Approving an AI client means it can act on your behalf with the scope you granted. Desk shows a caution for clients it recognises as AI assistants: they can get things wrong, so grant write access only where you are comfortable with that.

A single-membership user has their platform preselected. Approving mints a one-time code that is valid for 60 seconds and redeems exactly once.

### The token exchange

The client posts the code and its PKCE verifier to `POST /v1/oauth2/token`. The response is a bearer token bound to the platforms you selected and the scope that was granted. A refresh token is issued alongside it, so the client does not have to send you back to the consent screen on every expiry.

## Via Desk

There is nothing to set up in Desk in advance. The consent screen appears on its own when a client starts the flow, and signing in is your normal Desk login.

## Edge cases

* **A refused authorization looks the same whichever way it failed.** An expired request, an unknown one, a browser that did not start the flow and the wrong user all answer one `403`. The reason is logged on Solvimon's side rather than shown, because distinguishing them in the browser tells an attacker which guess was closest. An authorization request lives five minutes, so expiry is the usual cause.
* **Recognition is not verification.** The client name on the consent screen is chosen by whoever registered the client. Desk shows a logo for clients it recognises by name, and nothing for one it does not, because a badge next to an unknown name would read as a guarantee. Read the name and the platforms carefully before approving.
* **An API key still works.** The `X-API-KEY` connection described in [Claude integration](/integrations/ai-assistants/claude) is unchanged. OAuth is the alternative, not a replacement, and is the better choice for a client on a personal machine.
* **Impersonation is restricted.** `X-ORIGINAL-USER` is honoured only for an API key of type `PROXY`, and only for the accounts that key may reach.

---

See also: [Claude integration](/integrations/ai-assistants/claude) for connecting a client, [Agent context](/mcp/agent-context) for the guidance an agent reads from your catalog, and [Developing for Solvimon](/platform-guides/for-developers/developing-for-solvimon).