Authenticate

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

Phase	Mechanism
Authorize redirect	OAuth client ID + PKCE (`code_challenge`, `state`)
Token exchange	`Authorization: Basic base64(clientId:clientSecret)`

Store clientId and clientSecret in server-side environment variables only.

Endpoints

Step	Method	URL
Start login	GET	`{AUTH_URL}/auth`
Exchange code	POST	`{AUTH_URL}/token`
Verify caller (optional)	GET	`/v1/auth/whoami`

Required inputs

Authorize redirect query params:

Param	Value
`response_type`	`code`
`client_id`	Your OAuth client ID
`redirect_uri`	Registered callback URL
`scope`	`openid accounts transactions profile email address` (add `offline_access` for refresh tokens)
`prompt`	`consent` when requesting `offline_access` (required for refresh tokens)
`code_challenge`	PKCE challenge (S256)
`code_challenge_method`	`S256`
`state`	Random value you can verify on callback

Token exchange body (application/x-www-form-urlencoded):

Field	Value
`grant_type`	`authorization_code`
`code`	Code from callback
`redirect_uri`	Same URI used in authorize step
`code_verifier`	Original 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:

Field	Use
`access_token`	Bearer token for API calls
`expires_in`	Token lifetime
`refresh_token`	Optional 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

About

Quickstart

Endpoints

Smart Contracts

Outcome

When

Auth

Endpoints

Required inputs

Example: exchange code for token

Response you need

Common mistakes

Full sample

​Outcome

​When

​Auth

​Endpoints

​Required inputs

​Example: exchange code for token

​Response you need

​Common mistakes

​Full sample

Outcome

When

Auth

Endpoints

Required inputs

Example: exchange code for token

Response you need

Common mistakes

Full sample