OAuth

Exchange a device code, authorization code or refresh token for tokens

grant_type=urn:ietf:params:oauth:grant-type:device_code polls a device sign-in: authorization_pending until approved, slow_down when polled faster than interval (add 5 seconds), access_denied when canceled, expired_token after ten minutes. grant_type=refresh_token rotates the refresh token: each one works once, and presenting a used one revokes the whole sign-in. Pass scope to narrow the new access token. Access tokens last 3600 seconds; refresh tokens expire after 90 days without use. authorization_code (PKCE S256 required) serves the hosted MCP server; the tokens carry the scopes approved on the consent page, and a code presented twice revokes what it was exchanged for. Clients registered with a secret authenticate with client_secret (body or HTTP Basic); public clients send only client_id. A resource (RFC 8707) must be the one that was authorized.

post/oauth/token

Request

  • Base URL: https://api.groundmail.dev
  • URL: https://api.groundmail.dev/oauth/token
  • Auth: none required

Request body

grant_type'urn:ietf:params:oauth:grant-type:device_code' | 'refresh_token' | 'authorization_code' required
client_idstring
device_codestring
refresh_tokenstring
client_secretstring

Confidential clients only (client_secret_post); or send HTTP Basic

scopestring

With refresh_token, narrows the new access token (never widens it)

resourcestring

RFC 8707 resource indicator. Optional; when sent it must be the resource that was authorized (https://mcp.groundmail.dev/mcp, or its origin), else invalid_target

codestring
redirect_uristring
code_verifierstring

Response

Tokens

access_tokenstring required

Bearer token for the API (gm_oat_…)

token_type'Bearer' required
expires_ininteger required
refresh_tokenstring required

Single-use; store the new one each time

scopestring required

Example response

{
  "expires_in": 3600
}

Changes

No recorded changes to this operation across all 2 revisions of this API.