API reference
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.
Base URL https://api.dissolve.email. These endpoints take no bearer token.
| Endpoint | Summary |
|---|---|
POST /oauth/register | Register a client |
GET /oauth/authorize | Start authorization |
POST /oauth/token | Exchange a code or refresh a token |
POST /oauth/revoke | Revoke a token |
GET /.well-known/oauth-authorization-server | Authorization server metadata |
GET /.well-known/oauth-protected-resource | Protected resource metadata |
Register a client
/oauth/registerDynamic 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. |
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"]}'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
{
"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
/oauth/authorizeSends 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. |
curl "https://api.dissolve.email/oauth/authorize"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
/oauth/tokenWith 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. |
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=...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
{
"access_token": "dna_at_...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "dna_rt_...",
"scope": "profile inboxes:read messages:read"
}Revoke a token
/oauth/revokeRevokes 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. |
curl -X POST "https://api.dissolve.email/oauth/revoke" \
-d token=dna_rt_... \
-d client_id=dyn_4hT9kQ2mXv7pLr1ZcN8bW3sYimport 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
/.well-known/oauth-authorization-serverRFC 8414: the endpoints, PKCE S256, the grant types and every scope. Clients discover the server from here.
curl "https://api.dissolve.email/.well-known/oauth-authorization-server"import os, requests
response = requests.get("https://api.dissolve.email/.well-known/oauth-authorization-server")
print(response.json())Response 200
{
"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
/.well-known/oauth-protected-resourceRFC 9728 for /v1: the resource, its authorization server and scopes. A 401 from /v1 points here in WWW-Authenticate.
curl "https://api.dissolve.email/.well-known/oauth-protected-resource"import os, requests
response = requests.get("https://api.dissolve.email/.well-known/oauth-protected-resource")
print(response.json())Response 200
{
"resource": "https://api.dissolve.email/v1",
"authorization_servers": [
"https://api.dissolve.email"
],
"bearer_methods_supported": [
"header"
]
}Something wrong or missing on this page? Tell us at support@dissolve.email.View as Markdown