OAuth V2

The Authentication API is a core Candescent Developer Experience Portal (DevEx) service. It issues OAuth 2.0 access tokens that authenticate and authorize requests to protected resources. V2 tokens are used by most current endpoints: Accounts, Alerts, Banking Images, Disclosures, Money Movement, Transactions, and related APIs.

End-user benefits

• Provides secure access to most current endpoints: Accounts, Alerts, Banking Images, Disclosures, Money Movement, Transactions, and related APIs.
• Supports both customer-specific and institution-level access.
• Tokens include scopes and expiration for time-bound access.

Integration capabilities

• Client credentials — Institution-level access; add user context on later calls.
• Password — First-party apps with direct user authentication.
• Authorization code — OAuth / OIDC-style flows (internal).
• Refresh token — Renew expired tokens without full re-authentication.
• Token revocation — Invalidate tokens on logout or security events.
• Use HTTP Basic Auth with client_id and client_secret. Register with a valid client_id and client_secret.

Authentication flows

Flows support Retail and Business users (business flows identify the business entity).

Business user setup

1. Lookup business entity ID: GET /db-users/v1/institution-users/{{login_id_bb}}?userIdType=LOGIN_ID
2. From institutionCustomers, match the correct memberNumber (TIN/EIN) and use the corresponding institutionCustomerId.
3. Include institutionCustomerId as a query parameter on subsequent requests for business context.

1. Client credentials grant

Server-to-server (institution-level) authentication. Subsequent calls need user context: Retail — hostUserId or loginId; Business — loginId.

2. Password grant

Direct user authentication with credentials.

3. Token refresh

Only applicable if the original token was issued via password grant.

4. Token revocation

Invalidates an existing access token via DELETE /oauth2/v1/revoke.

Required headers

Header	Description
Authorization	HTTP Basic: Basic + Base64(client_id:client_secret).
Content-Type	application/x-www-form-urlencoded for token request bodies.
transactionId	Unique identifier for this request (UUID).
institutionId	Numeric unique ID of the financial institution (required for client_credentials and password).

Error codes

Code	Message	HTTP Status Code
CMN_90000	Internal server error	500
CMN_90001	Internal server error - Cross Talk	500
CMN_90002	Quota limit violation	500
CMN_90003	Spike limit violation	500
CMN_90004	Invalid client credentials	401
CMN_90005	Header institutionId is invalid or Form param institution_user_id is invalid	400
CMN_90006	Not authorized to access this resource	400
CMN_90007	Invalid grant type	400
CMN_90008	Header transactionId is invalid	400
CMN_90009	Access blocked	400
CMN_90010	Header is invalid	400
CMN_90011	Request is invalid	400
CMN_90012	Request is invalid - Scopes	400
CMN_90013	Username is invalid	400
CMN_90014	Password is invalid	400
CMN_90015	Invalid user credentials	401
CMN_90016	Invalid user	400
CMN_90017	Request contains non printable ASCII characters	400
CMN_90018	Invalid token	401
CMN_90019	Error creating token	500
CMN_90020	App cannot authorize itself	400
CMN_90021	Invalid client configuration	400

Endpoints

Authorize Client

Authorizes a client application to access resources on behalf of a user. Used in the OAuth 2.0 authorization

Create V2 Access Token

**V2 Token Endpoint** - Use this endpoint for most current Candescent APIs (Accounts, Alerts, Banking Images, Disclosures, Money Movement, Transactions).

Get Authorization Code

Generates an authorization code for OAuth 2.0 authorization code flow. The returned code can be exchanged

Revoke Access Token

Revokes an active OAuth 2.0 access token, rendering it unusable for future API requests.