aws.cognito.exchange_code_for_tokens

Exchange OAuth2 authorization code for tokens (callback)

Exchange an OAuth2 authorization code for ID, access, and refresh tokens.

Used after the user is redirected back from Cognito hosted UI (or an authorization endpoint) with ?code=... in the callback URL. This workflow POSTs to the Cognito token endpoint (/oauth2/token) and returns the tokens.

Supports public clients (no secret) and confidential clients (client_secret sent as Basic auth or in the body). Optional code_verifier for PKCE.

Inputs:

• cognito_domain: Full Cognito domain host, e.g. my-app.auth.us-east-1.amazoncognito.com (required).
• client_id: App client ID (required).
• redirect_uri: Redirect URI used in the authorization request (required).
• code: Authorization code from the callback query (required).
• client_secret: App client secret; if set, used for client_secret_basic (optional).
• code_verifier: PKCE code verifier if the authorization request used code_challenge (optional).

Outputs (terminal state_data):

• id_token: str - JWT ID token
• access_token: str - JWT access token
• refresh_token: str - refresh token (only for authorization_code grant)
• expires_in: int - access token validity in seconds
• token_type: str - "Bearer"

Plugin required: none (uses httpx to call Cognito token endpoint over HTTPS).

Overview

Property	Value
Workflow type	Atomic
Library	Base-aws
Version	1.0

Input Schema

Field	Type	Required	Default	Description
cognito_domain	string	Yes	—	Cognito domain host, e.g. my-app.auth.us-east-1.amazoncognito.com
client_id	string	Yes	—	App client ID
redirect_uri	string	Yes	—	Redirect URI used in the authorization request
code	string	Yes	—	Authorization code from the callback
client_secret	string	No	—	App client secret (for confidential clients)
code_verifier	string	No	—	PKCE code verifier if authorization used code_challenge

Output Schema

Field	Type	Required	Default	Description
id_token	string	Yes	—	JWT ID token
access_token	string	Yes	—	JWT access token
refresh_token	string	No	—	Refresh token (authorization_code grant only)
expires_in	integer	Yes	—	Access token validity in seconds
token_type	string	Yes	—	Token type, always Bearer
failure_reason	string	No	—	—
failure_type	string	No	—	—
failed_action	string	No	—	—
failed_at_state	string	No	—	—
failed_step	string	No	—	—
failed_layer	string	No	—	—
error	string	No	—	—
error_type	string	No	—	—

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	execute	—
completed	No	Yes	Yes	—	—
failed	No	Yes	No	—	—

State Diagram

Transitions

From	Action	To	Description
pending	execute	completed	—
* (any state)	fail	failed	—

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "aws.cognito.exchange_code_for_tokens",
  "initial_data": {
    "cognito_domain": "value",
    "client_id": "value",
    "redirect_uri": "value",
    "code": "value"
  }
}