OAuth Flow Integration

OAuth Flow Overview

The Reload API implements OAuth 2.0 with PKCE (Proof Key for Code Exchange) for enhanced security. This flow ensures that even if an authorization code is intercepted, it cannot be used without the code verifier.

Step-by-Step OAuth Flow

Step 1: Generate PKCE Parameters

Before initiating the OAuth flow, generate PKCE parameters for security:

Code Verifier: A cryptographically random string (43-128 characters) Code Challenge: A SHA256 hash of the code verifier, base64url encoded

Step 2: Redirect User to Authorization

Redirect the user to the Reload OAuth authorization URL with the following parameters:

response_type: Must be "code"
client_id: Your AI agent's client ID
redirect_uri: The callback URL in your application
scope: The permissions you're requesting (e.g., "identity usage_reporting payment")
state: A random string to prevent CSRF attacks
code_challenge: The PKCE code challenge
code_challenge_method: Must be "S256"
ai_agent_ids (optional): comma or space separated. Eg: ...&ai_agent_ids=68f555...,68d8cd...

Step 3: Handle Authorization Callback

After the user authorizes your application, they'll be redirected back to your callback URL with:

code: The authorization code
state: The state parameter you provided (verify this matches)

Step 4: Exchange Code for Token

Exchange the authorization code for an access token by making a POST request to the token endpoint with:

grant_type: "authorization_code"
client_id: Your client ID
client_secret: Your client secret
code: The authorization code from the callback
redirect_uri: The same redirect URI used in step 2
code_verifier: The PKCE code verifier from step 1

Step 5: Store and Use Access Token

Store the access token securely and include it in subsequent API requests using the X-Access-Token header.

OAuth Scopes

The following scopes are available:

identity: Access to user profile information
usage_reporting: Ability to report usage to Reload
payment: Ability to charge users for usage

Token Management

Access Token Persistence: OAuth access tokens do not expire and remain valid until revoked
Token Validation: You can validate token validity by calling the introspect API call
Token Revocation: Use the revoke token API endpoint to revoke the access tokens
Revocation Handling: Subscribe to the user.disconnected webhook event to be notified when users revoke access from the Reload platform
Secure Storage: Store tokens securely and never expose them in client-side code

Optional Agent Selection (What developers need to know)

You can optionally restrict the consent screen to a specific set of your AI Agents and let the user choose a subset to connect:

Pass ai_agent_ids in the OAuth URL (comma or space separated). Example: ...&ai_agent_ids=68f555...,68d8cd...
Only agents from your AI Agent Organization are considered; others are ignored. If provided, the consent screen evaluates only these agents; if not provided, all eligible agents from your org are evaluated.
The consent screen may include an optional, compact picker so the user can select a subset of the allowed agents. If the user doesn’t make a selection, all allowed agents will be connected.
On completion, the user’s grant (and token) will include the final set of connected agents as “allowed agents”. Your subsequent API calls are automatically restricted to this set.