OAuth2 Integration

OAuth2 allows your application to request permission from AgnicPay users to make X402 payments on their behalf. Users set their own spending limits and can revoke access anytime.

Why OAuth2?

User-controlled limits - Users set daily/monthly spending caps
Revocable access - Users can disconnect your app anytime
Network selection - Users choose which networks to allow
Long-lived tokens - Access tokens last 30-60 days with refresh

Authorization Flow

Step 1: Redirect to Authorization

Redirect users to our authorization endpoint:

https://api.agnic.ai/oauth/authorize?
  client_id=your-app-name
  &redirect_uri=https://yourapp.com/callback
  &state=random_csrf_token
  &scope=payments:sign+balance:read
  &response_type=code

Step 2: User Grants Permission

The user logs in, sets spending limits (per-transaction, daily, monthly), selects allowed networks, and approves your app.

Step 3: Receive Authorization Code

User is redirected back to your app with an authorization code:

https://yourapp.com/callback?code=abc123&state=random_csrf_token

Step 4: Exchange for Tokens

Exchange the code for access and refresh tokens:

curl -X POST https://api.agnic.ai/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "abc123",
    "redirect_uri": "https://yourapp.com/callback",
    "client_id": "your-app-name"
  }'

Token Response

{
  "access_token": "agnic_at_abc123...",
  "refresh_token": "agnic_rt_xyz789...",
  "token_type": "Bearer",
  "expires_in": 2592000,
  "scope": "payments:sign balance:read"
}

Token Expiration:

Access tokens: 30-60 days (varies by client type)
Refresh tokens: 90 days
N8N tokens: 1 year (for automation workflows)

Using the Access Token

# Check user's balance
curl https://api.agnic.ai/api/balance \
  -H "Authorization: Bearer agnic_at_abc123..."
 
# Make X402 payment (AI Gateway)
curl https://api.agnic.ai/v1/chat/completions \
  -H "Authorization: Bearer agnic_at_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
 
# Get transaction history
curl https://api.agnic.ai/api/transactions \
  -H "Authorization: Bearer agnic_at_abc123..."

Refreshing Tokens

When the access token expires, use the refresh token to get a new one:

curl -X POST https://api.agnic.ai/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "agnic_rt_xyz789..."
  }'

Authorization Parameters

Parameter	Required	Description
`client_id`	Yes	Your application identifier
`redirect_uri`	Yes	Where to send user after authorization
`state`	Yes	CSRF protection token (returned unchanged)
`scope`	No	Space-separated scopes (default: `payments:sign balance:read`)
`response_type`	Yes	Must be `code`
`code_challenge`	No	PKCE code challenge (recommended)
`code_challenge_method`	No	PKCE method (default: `S256`)
`prompt`	No	Controls consent behavior

Prompt Parameter

The prompt parameter follows the OpenID Connect standard:

Value	Behavior
(omitted)	Auto-approve if user previously consented
`none`	Silent auth only - error if consent needed
`consent`	Force consent screen even if previously consented
`login`	Force re-authentication before authorization

Returning users are auto-approved by default (like Google/GitHub). Use prompt=consent to force users to review permissions again.

CLI Client

The agnic CLI (v2.0.0+) uses OAuth2 Authorization Code + PKCE to authenticate via the browser — the same pattern as gh auth login, vercel login, and stripe login.

Client ID: agnic_cli

Flow:

CLI starts a localhost HTTP server on a random port
Browser opens to api.agnic.ai/oauth/authorize with PKCE challenge
User signs in and sets spending limits on the consent screen
Browser redirects to http://localhost:<port>/callback with auth code
CLI exchanges code + PKCE verifier for tokens (90-day expiry)

Security:

PKCE is required for CLI clients (server rejects without code_challenge)
Localhost redirect only (http://localhost:<port>/callback or http://127.0.0.1:<port>/callback)
HTTP is correct for loopback per RFC 8252 §7.3
Server binds to 127.0.0.1 only (no network exposure)
Random ephemeral port, state parameter verified, 5-minute timeout

agnic auth login
# Opens browser → sign in → set limits → authenticated!

Register Your Application

To use OAuth2, contact us to register your application and get your redirect URIs whitelisted.

PKCE (Recommended)

For public clients (mobile apps, SPAs), we recommend using PKCE:

// Generate code verifier
const codeVerifier = generateRandomString(64);
 
// Create code challenge
const codeChallenge = base64UrlEncode(sha256(codeVerifier));
 
// Include in authorization URL
const authUrl = `https://api.agnic.ai/oauth/authorize?
  client_id=your-app
  &redirect_uri=https://yourapp.com/callback
  &state=random_state
  &response_type=code
  &code_challenge=${codeChallenge}
  &code_challenge_method=S256`;
 
// Include verifier in token exchange
const tokenResponse = await fetch('https://api.agnic.ai/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'authorization_code',
    code: authCode,
    redirect_uri: 'https://yourapp.com/callback',
    client_id: 'your-app',
    code_verifier: codeVerifier
  })
});

OAuth2 Integration

OAuth2 Integration

Why OAuth2?

Authorization Flow

Step 1: Redirect to Authorization

Step 2: User Grants Permission

Step 3: Receive Authorization Code

Step 4: Exchange for Tokens

Token Response

Using the Access Token

Refreshing Tokens

Authorization Parameters

Prompt Parameter

CLI Client

Register Your Application

PKCE (Recommended)

Next Steps

Available Scopes

API Reference

On this page