Skip to main content

​
OAuth Configuration

Before users can transfer points to your platform, they need to link their Bankroll account to their account on your platform. This is done via OAuth 2.0 with OpenID Connect.

​
How It Works

1

User initiates account linking

A Bankroll user chooses to connect to your platform. Bankroll redirects the user to your OAuth authorization endpoint.
2

User authenticates on your platform

The user logs in on your platform and authorizes the connection. Your OAuth server redirects back to Bankroll with an authorization code.
3

Bankroll exchanges the code for tokens

Bankroll exchanges the authorization code for an access token and ID token using PKCE. The sub claim from the ID token becomes the user’s externalId used in transfer webhooks.
4

Account linked

The user’s Bankroll account is now linked to their account on your platform. They can start transferring points.

​
Setup

Configure OAuth in the Partner Portal under Settings. You’ll need to provide:
FieldDescriptionExample
Client IDYour OAuth application’s client IDabc123
Client SecretYour OAuth application’s client secretsecret_xyz
Authorize URLYour OAuth authorization endpointhttps://example.com/oauth/authorize
Token URLYour OAuth token endpointhttps://example.com/oauth/token
The Partner Portal will display a Redirect URI that you must add to your OAuth application’s allowed redirect URIs.

​
Requirements

Your OAuth server must support:
  • Authorization Code flow with PKCE (S256 challenge method)
  • OpenID Connect — the token response must include an id_token (JWT) with at least a sub claim

​
ID Token Claims

Bankroll reads the following claims from the id_token:
ClaimRequiredDescription
subYesUnique user identifier on your platform. Becomes externalId in transfer webhooks.
preferred_usernameNoUser’s display name. Falls back to name. Becomes externalName in transfer webhooks.
nameNoUser’s full name (fallback for display name)
emailNoUser’s email address (stored but not used in transfers)
The sub claim must be a stable, unique identifier for the user. Do not use email addresses or display names as the sub — these can change and would break the account link.

​
Security

Bankroll uses the following security measures during the OAuth flow:
  • PKCE (S256) — prevents authorization code interception attacks
  • State parameter — a random token verified on callback to prevent CSRF attacks. Expires after 10 minutes.
  • HTTPS only — all token exchanges happen server-to-server over TLS

​
Scopes

Bankroll requests the following scopes by default: 
openid profile
This is sufficient for most OAuth providers to return an id_token with identity claims.

​
User Identity in Transfers

Once a user links their accounts, the externalId and externalName from the OAuth connection are included in every transfer webhook sent to your platform. Use externalId to identify which user on your platform should receive the transferred value.