# OAuth API

> The OAuth 2.1 authorization server (PKCE S256) and its discovery documents. Every oauth endpoint with its scope, parameters, body and an example answer.

Source: https://docs.dissolve.email/reference/oauth

Base URL `https://api.dissolve.email`. These endpoints take no bearer token.

| Endpoint | Summary |
|---|---|
| `POST /oauth/register` | [Register a client](#register-a-client) |
| `GET /oauth/authorize` | [Start authorization](#start-authorization) |
| `POST /oauth/token` | [Exchange a code or refresh a token](#exchange-a-code-or-refresh-a-token) |
| `POST /oauth/revoke` | [Revoke a token](#revoke-a-token) |
| `GET /.well-known/oauth-authorization-server` | [Authorization server metadata](#authorization-server-metadata) |
| `GET /.well-known/oauth-protected-resource` | [Protected resource metadata](#protected-resource-metadata) |

### Register a client

`POST /oauth/register`

Dynamic client registration (RFC 7591) for public clients: no secret, PKCE required. Ten registrations a minute and 20 a day per address. A dynamically registered app is shown as unverified on the consent page.

**Body** (`application/json`)

| Name | Type | Required | Description |
|---|---|---|---|
| `redirect_uris` | string[] | yes | Where the person comes back to: https, or http to localhost. |
| `client_name` | string | no | Shown on the consent page. |
| `client_uri` | string | no | The app's home page. |
| `logo_uri` | string | no | The app's logo. |
| `token_endpoint_auth_method` | string | no | Only public clients register here. One of `none`. Default `none`. |
| `grant_types` | string[] | no | Defaults to both. One of `authorization_code`, `refresh_token`. |

```bash cURL
curl -X POST "https://api.dissolve.email/oauth/register" \
  -H "Content-Type: application/json" \
  -d '{"client_name":"My agent","redirect_uris":["http://localhost:8976/callback"]}'
```

```python Python
import os, requests

response = requests.post("https://api.dissolve.email/oauth/register", json={
  "client_name": "My agent",
  "redirect_uris": [
    "http://localhost:8976/callback"
  ]
})
print(response.json())
```

**Response** `201`

```json
{
  "client_id": "dyn_4hT9kQ2mXv7pLr1ZcN8bW3sY",
  "client_id_issued_at": 1795600000,
  "client_name": "My agent",
  "redirect_uris": [
    "http://localhost:8976/callback"
  ],
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ],
  "response_types": [
    "code"
  ],
  "token_endpoint_auth_method": "none"
}
```

### Start authorization

`GET /oauth/authorize`

Sends the person to the consent page on app.dissolve.email. After they approve, the browser returns to `redirect_uri` with `code`, `state` and `iss`. The code lasts 60 seconds and works once.

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `response_type` | string | yes | Always code. One of `code`. |
| `client_id` | string | yes | Your client id. |
| `redirect_uri` | string | no | One of the client's registered addresses (optional when it has only one). |
| `scope` | string | no | Space-separated scopes. Unknown scopes are dropped. |
| `state` | string | no | Returned unchanged; check it. |
| `code_challenge` | string | yes | BASE64URL(SHA-256(code_verifier)), 43 characters. |
| `code_challenge_method` | string | yes | Always S256. One of `S256`. |
| `resource` | string | no | The resource the token is for: https://api.dissolve.email/v1 or https://mcp.dissolve.email/mcp-oauth. |

```bash cURL
curl "https://api.dissolve.email/oauth/authorize"
```

```python Python
import os, requests

response = requests.get("https://api.dissolve.email/oauth/authorize")
response.raise_for_status()
```

**Response** `303`: a redirect.

### Exchange a code or refresh a token

`POST /oauth/token`

With `grant_type=authorization_code`, trades the code and the PKCE verifier for tokens; with `refresh_token`, trades a refresh token for new ones (each refresh token works once). Access tokens (`dna_at_`) last an hour, refresh tokens (`dna_rt_`) 30 days from their last use. Confidential clients authenticate with HTTP Basic or `client_secret`.

**Body** (`application/x-www-form-urlencoded`)

| Name | Type | Required | Description |
|---|---|---|---|
| `grant_type` | string | yes | Which exchange. One of `authorization_code`, `refresh_token`. |
| `client_id` | string | yes | Your client id. |
| `code` | string | no | The code from the redirect (authorization_code). |
| `redirect_uri` | string | no | The same redirect_uri as the authorization request. |
| `code_verifier` | string | no | The PKCE verifier (authorization_code). |
| `refresh_token` | string | no | The refresh token (refresh_token). |
| `client_secret` | string | no | Confidential clients only. |

```bash cURL
curl -X POST "https://api.dissolve.email/oauth/token" \
  -d grant_type=authorization_code \
  -d client_id=dyn_4hT9kQ2mXv7pLr1ZcN8bW3sY \
  -d code=dna_ac_... \
  -d redirect_uri=http://localhost:8976/callback \
  -d code_verifier=...
```

```python Python
import os, requests

response = requests.post("https://api.dissolve.email/oauth/token", data={
  "grant_type": "authorization_code",
  "client_id": "dyn_4hT9kQ2mXv7pLr1ZcN8bW3sY",
  "code": "dna_ac_...",
  "redirect_uri": "http://localhost:8976/callback",
  "code_verifier": "..."
})
print(response.json())
```

**Response** `200`

```json
{
  "access_token": "dna_at_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dna_rt_...",
  "scope": "profile inboxes:read messages:read"
}
```

### Revoke a token

`POST /oauth/revoke`

Revokes an access or refresh token (RFC 7009) and the connection behind it. Answers 200 whether or not the token was known.

**Body** (`application/x-www-form-urlencoded`)

| Name | Type | Required | Description |
|---|---|---|---|
| `token` | string | yes | The access or refresh token. |
| `client_id` | string | yes | Your client id. |

```bash cURL
curl -X POST "https://api.dissolve.email/oauth/revoke" \
  -d token=dna_rt_... \
  -d client_id=dyn_4hT9kQ2mXv7pLr1ZcN8bW3sY
```

```python Python
import os, requests

response = requests.post("https://api.dissolve.email/oauth/revoke", data={
  "token": "dna_rt_...",
  "client_id": "dyn_4hT9kQ2mXv7pLr1ZcN8bW3sY"
})
response.raise_for_status()
```

**Response** `200`: the bytes, or an empty body.

### Authorization server metadata

`GET /.well-known/oauth-authorization-server`

RFC 8414: the endpoints, PKCE S256, the grant types and every scope. Clients discover the server from here.

```bash cURL
curl "https://api.dissolve.email/.well-known/oauth-authorization-server"
```

```python Python
import os, requests

response = requests.get("https://api.dissolve.email/.well-known/oauth-authorization-server")
print(response.json())
```

**Response** `200`

```json
{
  "issuer": "https://api.dissolve.email",
  "authorization_endpoint": "https://api.dissolve.email/oauth/authorize",
  "token_endpoint": "https://api.dissolve.email/oauth/token",
  "registration_endpoint": "https://api.dissolve.email/oauth/register",
  "revocation_endpoint": "https://api.dissolve.email/oauth/revoke",
  "code_challenge_methods_supported": [
    "S256"
  ]
}
```

### Protected resource metadata

`GET /.well-known/oauth-protected-resource`

RFC 9728 for /v1: the resource, its authorization server and scopes. A 401 from /v1 points here in `WWW-Authenticate`.

```bash cURL
curl "https://api.dissolve.email/.well-known/oauth-protected-resource"
```

```python Python
import os, requests

response = requests.get("https://api.dissolve.email/.well-known/oauth-protected-resource")
print(response.json())
```

**Response** `200`

```json
{
  "resource": "https://api.dissolve.email/v1",
  "authorization_servers": [
    "https://api.dissolve.email"
  ],
  "bearer_methods_supported": [
    "header"
  ]
}
```
