Skip to main content

​
Overview

The authorization endpoint is used to initiate the OAuth 2.1 authorization flow. This endpoint presents the user with an authorization page where they can approve the agent’s access request. 
GET https://api.auth-agent.com/authorize

​
Query Parameters

​
client_id
string
required
The OAuth client identifier provided during client registration
​
redirect_uri
string
required
The URI where the user will be redirected after authorization. Must exactly match one of the registered redirect URIs for the client. Must use HTTPS except for localhost.
​
response_type
string
required
Must be code for authorization code flow
​
state
string
required
An opaque value used to maintain state between the request and callback. This prevents CSRF attacks. Should be a random, unguessable string.
​
code_challenge
string
required
PKCE code challenge derived from the code verifier using SHA-256
​
code_challenge_method
string
required
Must be S256 (SHA-256 hashing). Plain code challenges are not supported.
​
scope
string
Space-separated list of scopes requested. If not provided, defaults to openid email profile.Available scopes:
  • openid - OpenID Connect authentication
  • email - Access to user email address
  • profile - Access to user profile (name)

​
Response

​
Success (302 Redirect)

If validation succeeds, the user is presented with an authorization page. After the agent authenticates via back-channel and the user approves, they are redirected to the redirect_uri with the authorization code: 
{redirect_uri}?code={authorization_code}&state={state}

​
Redirect Parameters

ParameterTypeDescription
codestringAuthorization code to exchange for tokens (expires in 10 minutes)
statestringThe same state value provided in the authorization request

​
Error (400 Bad Request)

If validation fails, an HTML error page is displayed with the error details: 
{
  "error": "invalid_request",
  "error_description": "Missing client_id parameter"
}

​
Error Codes

Error CodeDescription
invalid_requestMissing or invalid required parameter
invalid_clientClient not found or inactive
unsupported_response_typeResponse type is not code

​
Flow Diagram

​
Example Request

// Generate PKCE parameters
const codeVerifier = generateCodeVerifier();
const codeChallenge = await generateCodeChallenge(codeVerifier);

// Store code verifier for later use in token exchange
sessionStorage.setItem('code_verifier', codeVerifier);

// Build authorization URL
const params = new URLSearchParams({
  client_id: 'client_abc123',
  redirect_uri: 'https://yourwebsite.com/api/auth/callback',
  response_type: 'code',
  code_challenge: codeChallenge,
  code_challenge_method: 'S256',
  scope: 'openid email profile',
  state: generateRandomState(),
});

// Redirect user to Auth Agent
window.location.href = `https://api.auth-agent.com/authorize?${params}`;

​
PKCE Implementation

// Generate code verifier (random string)
export function generateCodeVerifier(): string {
  const array = new Uint8Array(32);
  crypto.getRandomValues(array);
  return base64URLEncode(array);
}

// Generate code challenge (SHA-256 hash of verifier)
export async function generateCodeChallenge(verifier: string): Promise<string> {
  const encoder = new TextEncoder();
  const data = encoder.encode(verifier);
  const hash = await crypto.subtle.digest('SHA-256', data);
  return base64URLEncode(new Uint8Array(hash));
}

function base64URLEncode(buffer: Uint8Array): string {
  const base64 = btoa(String.fromCharCode(...buffer));
  return base64
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=/g, '');
}

​
Security Considerations

Always use HTTPS for redirect URIs in production. HTTP is only allowed for localhost during development.
State parameter is required to prevent CSRF attacks. Generate a random, unguessable value and verify it in your callback handler.
Code verifier must be stored securely (session, cookie, or memory) and used in the subsequent token exchange request.

​
Next Steps

After successfully receiving an authorization code:

Exchange Code for Tokens

POST /token - Exchange the authorization code for access tokens

Get User Info

GET /userinfo - Retrieve user information using the access token