OAuth2 API Endpoints

AWS Cognito exposes standard OAuth2 and OIDC endpoints for authentication, token exchange, and token verification. All endpoints are accessed over HTTPS.

Note: This document is in progress while Cognito integration is being completed. Confirm endpoint behavior against the live system.

Cognito Domain Structure

https://<partition>-<infrastructure>.auth.<region>.amazoncognito.com

The <partition>-<infrastructure> string is available as CloudFormation export <infrastructure>-<partition>-API-UserPoolDomain.

Core Endpoints

Authorization Endpoint — /oauth2/authorize

Initiates user sign-in. The browser is redirected here.

Parameter	Description
response_type	code (Authorization Code), token (Implicit)
client_id	App Client ID
redirect_uri	Registered callback URL
scope	Space-separated scopes: openid profile email ...
state	Anti-CSRF opaque value
code_challenge	(PKCE) Code challenge derived from verifier
code_challenge_method	(PKCE) S256

Token Endpoint — /oauth2/token

Exchange authorization code for tokens, or refresh using a refresh token.

Authorization Code Grant:

Parameter	Value
grant_type	authorization_code
code	Authorization code from /oauth2/authorize
client_id	App Client ID
redirect_uri	Same URI used in authorization request
code_verifier	(PKCE) Plain text secret

Refresh Token Grant:

Parameter	Value
grant_type	refresh_token
refresh_token	Refresh token
client_id	App Client ID

Authentication: Client ID + secret via Authorization: Basic <base64(client_id:secret)> header.

UserInfo Endpoint — /oauth2/userInfo

Returns authenticated user claims. Requires Authorization: Bearer <access_token>.

JWKS URI — /.well-known/jwks.json

Returns public keys for verifying JWT signatures. URL format:

https://cognito-idp.<region>.amazonaws.com/<user-pool-id>/.well-known/jwks.json

Cache these keys; refresh only when a token cannot be verified with the cached keyset.

Logout Endpoint — /logout

Ends the Cognito session and redirects the user.

Parameter	Description
client_id	App Client ID
logout_uri	Registered sign-out URL to redirect to post-logout

OIDC Discovery Endpoint — /.well-known/openid-configuration

Returns OIDC metadata including all endpoint URLs, supported scopes, and JWKS URI. Useful for automatic client library configuration:

https://<cognito-domain>/.well-known/openid-configuration

Revocation Endpoint — /oauth2/revoke

Revokes a refresh token.

Parameter	Description
token	Refresh token to revoke
client_id	App Client ID
client_secret	Client secret (if applicable)

M2M Authentication (Client Credentials Flow)

Backend services use the Token endpoint with client_credentials grant:

POST /oauth2/token
Authorization: Basic <base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=<scopes>

Successful Response:

{
  "access_token": "...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Amplify Configuration

Amplify requires only two values for Cognito integration:

• User Pool ID: <infrastructure>-<partition>-API-UserPoolId (CloudFormation export)
• App Client ID: <infrastructure>-<partition>-API-WebClientId (CloudFormation export)