Skip to main content
OAuth 2.0 (Open Authorization) is the standard protocol for delegated access. Rather than sharing credentials, it lets users grant third-party apps limited access to their accounts. For a thorough primer, see The Complete Guide to OAuth 2.0 by WorkOS. Consul supports users linking their Consul accounts to your app via OAuth directly within your UI. Instead of asking users for their API keys, you redirect them to Consul’s authorization page where they grant your app specific permissions. Once authorized, your app receives an access token scoped to that user’s account.
Consul OAuth Linking Flow

​
What This Enables

  • Embedded digital wallets. Give your users a digital wallet using Consul. Surface a user’s Consul balance and transaction history directly in your UI.
  • Checkout and payment acceptance flows. Send and reconcile funds from your users’ Consul balances natively in your app.
  • Fiat deposits from your platform. Trigger deposits into a user’s Consul balance from your platform without them leaving your app.

​
Prerequisites

NameWhat it isHow to get it
client_idIdentifies your application to Consul during the OAuth flowProvided by Consul when your app is registered
client_secretSecret used to exchange authorization codes for tokens. Never expose this client-side.Provided by Consul when your app is registered
redirect_uriThe URL Consul redirects users to after they grant access. Must match what was registered.You provide this to Consul during app registration
API keys and OAuth client credentials serve different purposes. An API key authenticates requests to your own Consul account. A client ID + client secret authenticate your app during the OAuth flow so it can act on behalf of other users’ accounts. When making API requests on behalf of a connected user, use the OAuth access token, not your API key.

​
Authorization Code Flow

Consul uses the OAuth 2.0 authorization code flow: 1. Redirect the user to Consul’s authorization endpoint: 
https://api.onconsul.com/v1/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &scope=read write
  &state=RANDOM_STATE_VALUE
The state parameter should be a random, unguessable string tied to the user’s session. Verify it when Consul redirects back to prevent CSRF attacks. 2. Exchange the authorization code for tokens: 
curl -X POST https://api.onconsul.com/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "AUTH_CODE_FROM_REDIRECT",
    "redirect_uri": "https://yourapp.com/callback",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'
The response includes an access_token, refresh_token, expires_in, and the granted scope. 3. Make API requests on behalf of the user: 
curl https://api.onconsul.com/v1/balance \
  -H "Authorization: Bearer OAUTH_ACCESS_TOKEN"

​
Refreshing Tokens

Access tokens expire. Use the refresh token to get a new one without requiring the user to re-authorize: 
curl -X POST https://api.onconsul.com/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "REFRESH_TOKEN",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'

​
Revoking Access

To disconnect a user’s account, revoke their token: 
curl -X POST https://api.onconsul.com/v1/oauth/revoke \
  -H "Content-Type: application/json" \
  -d '{"token": "ACCESS_OR_REFRESH_TOKEN"}'

​
Scopes

Request scopes as a space-separated string in the scope query parameter during authorization.
ScopeDescription
readRead account data, balances, recipients, transactions, and payout status
writeCreate and manage recipients, initiate payouts, and modify account settings
Request the minimum scopes your application needs. Users see the requested permissions on the consent screen before granting access.