OAuth V2

The OAuth V2 APIs provide the core authentication and authorization services for the Candescent Developer Experience Portal (DevEx). OAuth V2 issues OAuth 2.0 Bearer access tokens and also supports OpenID Connect (OIDC) ID tokens for partner integrations.

OAuth V2 tokens are required to access most current Candescent APIs, including Accounts, Alerts, Banking Images, Disclosures, Money Movement, and Transactions.

End-user benefits

• Provides secure, scoped access to banking data and services across Candescent APIs.
• Supports institution-level access, customer-authenticated access, and OIDC partner integrations.
• Limits exposure through token expiration and scope restrictions aligned with the registered application's Apigee configuration.
• Enables session renewal using refresh tokens (from the password or authorization_code grants) without requiring repeated credential entry.
• Supports logout and incident response by allowing access and refresh tokens to be revoked when a session must be terminated.

Integration capabilities

• Client Credentials — Institution-level, server-to-server access. User context can be established on downstream API calls using hostUserId or loginId.
• Password — Customer-specific access using digital banking credentials. Returns an access_token and a refresh_token.
• Authorization Code — OpenID Connect (OIDC) partner flow. Uses Bearer authentication in a multi-step process and exchanges the authorization code for an access_token and id_token.
• Refresh Token — Obtain a new access token using a refresh token issued by the password or authorization_code grant.
• Token Revocation — Invalidate access or refresh tokens to immediately terminate active sessions.
• Token requests must use application/x-www-form-urlencoded encoding and HTTP Basic authentication with the financial institution’s Apigee application client_id and client_secret obtained during registration.
• Authorization code requests must use application/x-www-form-urlencoded encoding and include a Bearer access token for an already authenticated user.
• When using the client_credentials, password, or authorization_code grant types, the institutionId request header is required.

Authentication flows

OAuth V2 supports two categories of integration: token endpoint grants (server and direct sign-in) and the authorization code flow (OIDC partner integrations). Retail and Business user context applies only to end‑user flows—password grant and authorization code. They do not apply when grant type is client_credentials.

Business context resolution (post‑authentication, only for Business users)

After authentication is complete, resolve the business context before making subsequent API requests required for business-scoped APIs.

1. Retrieve associated business entities: GET /v1/customers/<BUSINESS_USER_LOGIN_ID>?userIdType=LOGIN_ID
2. Select the correct business entity: From the customers response, match the correct memberNumber (TIN/EIN) and capture the associated customerId.
3. Apply business context: Include customerId as the value of the institutionCustomerId query parameter on all business‑scoped API requests.

OAuth 2.0 access token flows

These grants use POST /oauth2/v1/token with HTTP Basic Authentication (client_id and client_secret). See Create Access Token V2.

1. Client credentials grant

Provides server‑to‑server, institution‑level authentication.

Important considerations

• No end‑user authentication occurs
• User context must be supplied on subsequent API calls:
  • Retail: hostUserId or loginId
  • Business: loginId
• Business context resolution is required before calling business‑scoped APIs

2. Password grant

Authenticates an end user directly using credentials.

Important considerations

• Supports both Retail and Business users
• Issues a refresh token in addition to an access token
• Business context resolution is required before calling business‑scoped APIs

3. Token refresh

Renews an access token using a refresh token.

Important considerations

• Available only for tokens issued via the password grant
• Does not require re‑authentication with user credentials

4. Token revocation

Invalidates an existing access or refresh token via POST /oauth2/v1/revoke. See Revoke Access Token V2.

Important considerations

• Immediately terminates the associated session
• Prevents further API access using the revoked token

OpenID Connect (OIDC) authorization code flow

This flow is used for OpenID Connect (OIDC) partner integrations. It is a distinct, multi-step flow and is not a variant of the password grant. Authorization-code endpoints use Bearer authentication with an access token for an already authenticated user; the token exchange step uses HTTP Basic authentication.

Prerequisites

• The end user is authenticated in digital banking
• A Bearer access token is available for authorization-code API calls
• The client application is registered with the authorization_code grant type

Steps

1. Authorize client (recommended) — Authorize Client
   • Returns approved scopes and authorization policy flags (MFA, consent, device registration)
2. Generate authorization code — Generate Authorization Code
   • Standard OAuth parameters include client_id, scopes, username, and institution_user_id
3. Exchange code for tokens — POST /oauth2/v1/token with grant_type=authorization_code
   • Returns an access_token and an OIDC id_token

Important considerations

• API and resource scopes are specified in scopes; OpenID Connect scopes (openid, profile, offline_access) are specified in requested_scopes
• The client_id used in the authorization-code request must differ from the client associated with the Bearer token; self-authorization is not permitted
• Business context must be resolved before invoking business-scoped APIs

Required headers

OAuth V2

Header	Description
Authorization	Basic <BASE64_ENCODED(CLIENT_ID:CLIENT_SECRET)
transactionId	UUID used to trace and correlate requests across services for debugging and logging.
institutionId	Identifier of the financial institution (required when grant_type is client_credentials or password).
Content-Type	application/x-www-form-urlencoded

Auth-Code

Header	Description
Authorization	Bearer {token} (OAuth V2)
transactionId	UUID used to trace and correlate requests across services for debugging and logging.
institutionId	Identifier of the financial institution.
Content-Type	application/x-www-form-urlencoded

Error codes

OAuth V2

Code	Message	HTTP Status Code
CMN_90000	Internal server error	500
CMN_90001	Client not authorized to access this resource	401
CMN_90001	Internal server error	500
CMN_90001	Quota limit violation	500
CMN_90002	Spike limit violation	500
CMN_90004	Invalid credentials	401
CMN_90005	Header institutionId is invalid	400
CMN_90005	institutionUserId is invalid	400
CMN_90006	Not authorized to access this resource	403
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	400
CMN_90013	Username is invalid	400
CMN_90014	Password is invalid	400
CMN_90015	Invalid user credentials	401
CMN_90016	Invalid token	400
CMN_90016	Invalid user	400
CMN_90017	Request contains non printable ASCII characters	400
CMN_90019	Error creating token	400

Auth-Code

Code	Message	HTTP Status Code
CMN_90000	Internal server error	500
CMN_90001	Client not authorized to access this resource	401
CMN_90001	Internal server error	500
CMN_90001	Quota limit violation	500
CMN_90002	Spike limit violation	500
CMN_90004	Invalid client credentials	400
CMN_90004	Invalid credentials	401
CMN_90005	Header institutionId is invalid	400
CMN_90005	Form param institution_user_id is invalid	400
CMN_90007	Invalid grant type	400
CMN_90008	Header transactionId is invalid	400
CMN_90009	Access blocked	400
CMN_90009	Access blocked	403
CMN_90010	Header is invalid	400
CMN_90012	Request is invalid	400
CMN_90013	Username is invalid	400
CMN_90017	Request contains non printable ASCII characters	400
CMN_90018	Invalid token	400
CMN_90019	Error creating authorization code	400
CMN_90020	App cannot authorize itself	400
CMN_90021	Invalid client configuration	400

Endpoints

Create OAuth Token (V2)

Issues an OAuth 2.0 access token for accessing current Candescent APIs. The returned access

Revoke Access Token

Permanently revokes an access token or refresh token, immediately preventing it from being

Authorize Client

Returns the approved OAuth scopes, Apigee application identifier, and authorization-flow

Generate Authorization Code

Generates an OAuth 2.0 authorization code for a signed-in user and a client application.