Unified Access OAuth

Use OAuth 2.0 PKCE when applications need delegated access to Unified Access endpoints without long-lived provider keys.

Before you begin

• Create an OAuth client in Settings → Unified Access → OAuth Clients.
• Register every allowed redirect URI exactly as the client will use it.
• Generate a PKCE verifier and S256 code challenge per authorization request.

Supported flow

Keeptrusts supports the authorization-code flow with PKCE:

1. GET /v1/oauth/authorize
2. POST /v1/oauth/token
3. GET /v1/oauth/userinfo
4. POST /v1/oauth/revoke

Authorization request

Required query parameters:

• response_type=code
• client_id
• redirect_uri
• code_challenge
• code_challenge_method=S256
• state
• scope (optional but recommended)

Plain PKCE (code_challenge_method=plain) is rejected.

Token exchange

Exchange the code with POST /v1/oauth/token using:

• grant_type=authorization_code
• code
• redirect_uri
• client_id
• code_verifier

Authorization codes are single use. The redirect URI must match the original authorization request exactly.

Refresh tokens

Refresh with grant_type=refresh_token and the current refresh token. Keeptrusts rotates refresh tokens on each successful exchange, so always persist the latest token pair returned by the server.

Revocation

Use POST /v1/oauth/revoke to invalidate the active access or refresh token when the integration is removed or compromised.

Troubleshooting

Symptom	Likely cause	Fix
400 invalid_request	Missing S256 challenge method	Send code_challenge_method=S256
400 invalid_grant	Verifier mismatch or reused code	Regenerate PKCE values and restart the flow
400 invalid_redirect_uri	Redirect mismatch	Register and send the exact same URI
401 on userinfo	Expired or revoked token	Refresh or re-authorize