Skip to content
docs
Browse the docsOAuth

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.

EndpointSummary
POST /oauth/registerRegister a client
GET /oauth/authorizeStart authorization
POST /oauth/tokenExchange a code or refresh a token
POST /oauth/revokeRevoke a token
GET /.well-known/oauth-authorization-serverAuthorization server metadata
GET /.well-known/oauth-protected-resourceProtected 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)

NameTypeRequiredDescription
redirect_urisstring[]yesWhere the person comes back to: https, or http to localhost.
client_namestringnoShown on the consent page.
client_uristringnoThe app's home page.
logo_uristringnoThe app's logo.
token_endpoint_auth_methodstringnoOnly public clients register here. One of none. Default none.
grant_typesstring[]noDefaults 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"]}'

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

NameTypeRequiredDescription
response_typestringyesAlways code. One of code.
client_idstringyesYour client id.
redirect_uristringnoOne of the client's registered addresses (optional when it has only one).
scopestringnoSpace-separated scopes. Unknown scopes are dropped.
statestringnoReturned unchanged; check it.
code_challengestringyesBASE64URL(SHA-256(code_verifier)), 43 characters.
code_challenge_methodstringyesAlways S256. One of S256.
resourcestringnoThe resource the token is for: https://api.dissolve.email/v1 or https://mcp.dissolve.email/mcp-oauth.
curl "https://api.dissolve.email/oauth/authorize"

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)

NameTypeRequiredDescription
grant_typestringyesWhich exchange. One of authorization_code, refresh_token.
client_idstringyesYour client id.
codestringnoThe code from the redirect (authorization_code).
redirect_uristringnoThe same redirect_uri as the authorization request.
code_verifierstringnoThe PKCE verifier (authorization_code).
refresh_tokenstringnoThe refresh token (refresh_token).
client_secretstringnoConfidential 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=...

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)

NameTypeRequiredDescription
tokenstringyesThe access or refresh token.
client_idstringyesYour client id.
curl -X POST "https://api.dissolve.email/oauth/revoke" \
  -d token=dna_rt_... \
  -d client_id=dyn_4hT9kQ2mXv7pLr1ZcN8bW3sY

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.

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

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.

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

Response 200

JSON
{
  "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