.png)
Introduction
The Authentication API provides the means to access all other APIs on DevX. For example, when calling an API to retrieve a list of an account holder’s accounts, your request must provide a valid OAuth 2.0 bearer token. The authentication service provides that token.
The service available through the Candescent Developer Hub provides tokens for two different grant types:
Client Credentials:
Used for trusted server-side applications
Sending a request passes a key-and-secret pair assigned to your application
Since the token is issued in the context of a Financial Institution (FI) rather than a user, no end-user login is required
Response provides the Bearer Token to be used to call other Developer Hub APIs
Password:
Best for first-party native applications (such as the FI’s own mobile application)
Request is sent with key-and-secret pair plus the customer’s username and password
Response provides Bearer Token to be used to call other Developer Hub APIs
NOTE: As of March 2020, the Authentication Service contains two proxies: one to be used to retrieve the Bearer Token for Developer Hub V1 APIs and another for Developer Hub V2 APIs. Please see the last section of this documentation for a list of V1 and V2 APIs currently exposed in the Developer Hub.
Though there are differences in the request headers and form data, both V1 and V2 Authentication work in the same manner:
Allow a registered application to obtain an OAuth2.0 Bearer Token, which is required when accessing the rest of the Digital Insight API suite
Utilize two grant types:
Client Credentials: used a digital banking customer isn’t present to provide their credentials but has trusted your application to act on their behalf
Password: used when the username and password of the digital banking customer are known
The selection of the grant type to use determines the parameter set expected by the request. The parameter list explicitly states the requirement for each grant type:
When Password is requested, the authentication request is made within the context of a customer. The success response will therefore contain their member ID and the scope of the token will be restricted to that customer.
When Client Credentials is requested, the success response will not contain any customer-specific data or scoping.
Note: The OAuth2.0 token will expire after 30 minutes, after which a subsequent request to this service is required.
System Requirements & Configurations
Endpoints for the Authentication service can be accessed from the Developer Hub.
This is the new oAuth2 token generation service. The auth token from this service is utilized by Accounts, Alerts and Messaging, Banking Image Services, Disclosures, Money Movement, Transactions. The service type in the Developer Hub is Authentication and the service subType is db-apx-tokens. The legacy oAuth token generation service is used by Banking Services and Customer services. This is generally referred to as legacy token generation service. The service type in the Developer Hub is Authentication and the service subType is db-oauth.
What is Supported?
- Method:* POST
- Endpoint Definition:* /v1/oauth/token
- Request Headers:*
Getting Started
Candescent’s APIs support financial institutions worldwide. They can empower financial institutions and their partners to build valuable digital banking experiences.
It’s important to work with your Candescent representative to get officially onboarded to DevX for access to these APIs. Once onboarded, you’ll be able to implement your application, access shared and secret keys and begin testing the APIs.
After all the legal and compliance partnership agreements are in place, we'll set you up with your Authentication API client account. This will grant you access to a unique secret key that will be your ticket to the authentication API and staging and production environments.
The service available through the Candescent Digital Banking Developer Portal provides a token for the grant type:
Client Credentials
- Used for trusted server-side applications
- Sending a request passes a key-and-secret pair assigned to your application
- Since the token is issued in the context of a Financial Institution (FI) rather than a user, no end-user login is required
- Response provides the Bearer Token to be used to call other DevEx APIs
Steps to getting started:
- Sign up and/or Login in for authentication
To make your first API request, you'll need toself-register by clicking the Sign Up button. Then, click the link in your welcomeemail to verify your emailaddress. - Review API documentation and request postman collections
Your Candescent representative will be able to email you the Postman collection for an API you are interested in. You may reach out directly or add the specific API to your favorites to alert your representative.
- Test APIs in Postman
In addition to the sample apps, a test drive environment is available to help you visualize the APIs. Using the JSONcollection and Postman, you’ll be able to see API requests working in action and view the information required to make them.
This will also allow you to experience actual API behavior prior to beginning your integration. For a deeper dive into Postman, view additional reference material here.
Authentication
Authentication proves that you are who you say you are. Authentication tokens identify a user (the person using the app or site).
You‘ll need the following items to set up basic authentication:
- Developer Hub account
- Sandbox environment with an organization
- Shared Key
- Secret Key
Generating your Secret Key
You’ll need a bearer token or an API security key to authenticate API calls. A secret key serves as a secure token to authenticate and authorize requests. Unauthorized use of a secret key could potentially cause a security breach. Thes ecret key holds the error token used to access real data through the API.
Visit our guide on authentication to learn more.
Before you begin, you‘ll require a unique client_id and client_secret for your app. Notify your implementation manager or PossibleNOW Support atsupport@possiblenow.com to request an OAuth client_id and client_secret. Include your My Preferences Client ID and the environment (staging (sandbox) or production) for which you want to generate the credentials in your request.
These credentials must be treated securely.
Use Cases & Examples
All APIs require authorization token as header to get a successful response. OAuth2 token is used for authorization which is a standard industry-wide way of authorizing a call.
Creates the bearer token for authorization
- Get list of accounts GET /db-accounts/v1/accounts
- Request -> Query Parameters:
hostUserId: The specific identifier for that customer - Headers:
Authorization: The bearer access token from the Authentication API
TransactionId: A UUID string used as unique identifier for this token request
Get the specified account for the given user
- Get the accounts GET /db-accounts/v1/accounts/{accountId}
- Request:
Headers:
Authorization: The access token from the Authentication APITransactionId: A UUID string used as unique identifier for this token request
