Authentication

Gummble runs a standards-compliant OAuth 2.1 Authorization Server at https://api.gummble.com. Any RFC-compliant client should work without Gummble-specific code.

Endpoints

Endpoint	RFC	Purpose
`GET /.well-known/oauth-authorization-server`	8414	Server metadata
`GET /.well-known/jwks.json`	7517	Public signing keys
`POST /oauth/register`	7591	Dynamic Client Registration (DCR)
`GET /oauth/authorize`	6749 §4.1.1 + 7636 + 8707	Authorization code
`POST /oauth/token`	6749 §3.2	Token exchange
`POST /oauth/revoke`	7009	Revocation

The PKCE dance

# 1. Discover
curl https://api.gummble.com/.well-known/oauth-authorization-server | jq

# 2. Register a client
curl -X POST https://api.gummble.com/oauth/register \
  -H 'content-type: application/json' \
  -d '{
    "client_name": "My App",
    "redirect_uris": ["http://127.0.0.1:8080/callback"],
    "application_type": "native",
    "token_endpoint_auth_method": "none"
  }'

# 3. Build the authorize URL
#    response_type=code & client_id & redirect_uri & state
#    & code_challenge(S256) & code_challenge_method=S256
#    & resource=https://mcp.gummble.com/mcp (RFC 8707)

# 4. Exchange code for tokens
curl -X POST https://api.gummble.com/oauth/token \
  -d "grant_type=authorization_code" \
  -d "code=..." \
  -d "client_id=..." \
  -d "redirect_uri=..." \
  -d "code_verifier=..." \
  -d "resource=https://mcp.gummble.com/mcp"

Token lifetimes

Token	Lifetime	Algorithm
Access (API)	1 day	HS256
Access (MCP)	15 minutes	RS256
Refresh	30 days, rotating	opaque

Refresh tokens are single-use with reuse detection. If the same refresh token is presented twice we invalidate the entire family and the user must re-authenticate. This is the OAuth 2.1 default.

Resource indicators (RFC 8707)

The resource parameter is required on /authorize and /token. Access tokens are audience-bound to that resource — a token minted for https://mcp.gummble.com/mcp is rejected by https://api.gummble.com and vice versa.

Scopes

Scope	Description
`mcp:read`	Read-only access via MCP
`mcp:tools`	Tool invocation via MCP

Granular scopes for direct REST API access are coming in the next minor release.

Refresh

curl -X POST https://api.gummble.com/oauth/token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=$RT" \
  -d "client_id=$CID" \
  -d "resource=https://mcp.gummble.com/mcp"