Skip to main content

​
Outcome

The user is logged in and your backend holds a valid access_token for subsequent Endaoment API calls.

​
When

First step of the standard journey. Trigger when the user chooses to connect or sign in to Endaoment from your app.

​
Auth

PhaseMechanism
Authorize redirectOAuth client ID + PKCE (code_challenge, state)
Token exchangeAuthorization: Basic base64(clientId:clientSecret)
Store clientId and clientSecret in server-side environment variables only.

​
Endpoints

StepMethodURL
Start loginGET{AUTH_URL}/auth
Exchange codePOST{AUTH_URL}/token
Verify caller (optional)GET/v1/auth/whoami
See also: Start OAuth authorization, Get access token, Revoke access token, End user session, and Get authenticated caller in API reference.

​
Required inputs

Authorize redirect query params:
ParamValue
response_typecode
client_idYour OAuth client ID
redirect_uriRegistered callback URL
scopeopenid accounts transactions profile email address (add offline_access for refresh tokens)
promptconsent when requesting offline_access (required for refresh tokens)
code_challengePKCE challenge (S256)
code_challenge_methodS256
stateRandom value you can verify on callback
Token exchange body (application/x-www-form-urlencoded):
FieldValue
grant_typeauthorization_code
codeCode from callback
redirect_uriSame URI used in authorize step
code_verifierOriginal PKCE verifier

​
Example: exchange code for token

curl -X POST "https://auth.dev.endaoment.org/token" \
  -H "Authorization: Basic $(printf '%s:%s' "$CLIENT_ID" "$CLIENT_SECRET" | base64)" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE_FROM_CALLBACK" \
  -d "redirect_uri=http://localhost:5454/callback" \
  -d "code_verifier=STORED_CODE_VERIFIER"

​
Response you need

Persist at minimum:
FieldUse
access_tokenBearer token for API calls
expires_inToken lifetime
refresh_tokenOptional long-lived refresh (requires offline_access scope and prompt=consent on authorize)

​
Common mistakes

  • Mismatched redirect_uri between authorize and token steps
  • Losing code_verifier between login start and callback
  • Requesting offline_access without prompt=consent (refresh token silently omitted)
  • Putting clientSecret or access tokens in frontend code

​
Full sample

PKCE generation and callback handling: GitHub quickstart backend. Shared patterns: Integration Patterns. Next: Open a Fund