Introduction

The Authentication API provides the means to access all other APIs on the Developer Portal. For example, when calling an API to retrieve a list of a customer’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 Experience Portal (DevEx) 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 DevEx 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 DevEx APIs

NOTE: As of March 2020, the Authentication Service contains two proxies: one to be used to retrieve the Bearer Token for DexEx V1 APIs and another for DevEx V2 APIs. Please see the last section of this documentation for a list of V1 and V2 APIs currently exposed in the Developer Portal.

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.

Value

The Authentication API enables Customers to secure authentication methods that keep malicious actors out and ensure only valid actors can access your data. It provides Developers access to tokens required when calling other Banking APIs.

What is Supported

While the technical documentation in the API Specs section describes the endpoints (or ways to call the API with different parameters to execute different actions), the following provides a simplified list of use cases for Authentication:

Get Token (for V1 APIs)

• Method:* POST
• Endpoint Definition:* /v1/oauth/token
• Request Headers:*

Name	Type	Description
di_tid *	String	Unique id used to identify the request. The id allows the request to be traced through the entire request and response flow. The expected id is a UUID, in the canonical form e.g 123e4567-e89b-12d3-a456-426655440000
user-agent *	String	Identifies the application and the platform making the request. The expected format is `{Appname}/{Appversion}[/{DeviceID}][;{Platform User-Agent}]` e.g. iPhone/1.0/abc12345;Nokia3110
di_fiid *	String	The financial institution for which the authentication token is being requested. The scope of the OAuth2.0 token will be restricted to this Financial Institution.
offering_id	String	Uniquely identifies the name of the client app making the request. When not provided this is derived based on a property held against the application within Apigee
originating_ip	String	The IP address of the device making the request for authentication. If not provided the IP address logged will be the IP address extracted from the HTTP request Note: this should be the originating device, rather than the client making the request e.g. if a mobile device is used the ip address should be that of the mobile device, rather than a back end service
Authorization *	String	Standard HTTP Basic Authentication based on the `consumer key` and `consumer secret` provided during the application registration process. A string composed of `Basic`+ `(space)` + `base64encode(consumer_key + “:” + consumer_secret)`; example `Basic ODU4S0pRczVXwGdMRkhUUUhtSGhNdTRYHlpRa3N1ZGY6STA0UThtMFJZZEF1dUlwY

Get Token (for V2 APIs)

• Method:* POST
• Endpoint Definition:* /{baseurl}/v1/token
• Request Headers:*

Name	Type	Description
Authorization *	String	Basic Auth - Base64 encoded client credentials
Content-Type *	String	Request content type
transactionId *	String	A unique identifier for this request.
institutionId *	String	Numeric unique id of the financial institution
Accept	String

Additional Product Details

Sample Responses

V1 Client Credentials Response:

\

00000

aLongGeneratedAlphanumericString

1799

\

V2 Client Credentials Response:

\

00000

aLongAlphanumericString

000000000

aLongGeneratedAlphanumericString

1799

\

Lists of V1 and V2 API Proxies

Proxies requiring V1 oAuth Bearer Tokens (By Service Product and Endpoint):

Alerts and Messaging

• Send Event
  - POST (/messagingservices/v1/fis/{di_fiid}/fiCustomers/{di_ficustomer}/events)
• Get Destinations
  - GET (/destinations/v2/fis/{di_fiid}/products/{product_id}/notificationApps/{notification_app_id}/fiCustomers/
  {di_ficustomer}/destinations)
• Create Destinations
  - POST (/destinations/v2/fis/{di_fiid}/products/{product_id}/notificationApps/{notification_app_id}/fiCustomers/
  {di_ficustomer}/destinations)
• Update Destinations
  - PUT (/destinations/v2/fis/{di_fiid}/products/{product_id}/notificationApps/{notification_app_id}/fiCustomers/
  {di_ficustomer}/destinations)
• Delete Destinations
  - DELETE (/destinations/v2/fis/{di_fiid}/products/{product_id}/notificationApps/{notification_app_id}/fiCustomers/
  {di_ficustomer}/destinations)
• Delete Destination (single) - DELETE (/destinations/v2/fis/{di_fiid}/products/{product_id}/notificationApps/{notification_app_id}/fiCustomers/
  {di_ficustomer}/destinations)

Banking Services

• Get FI Customer - GET (/bankingservices/v2/fis/{fiId}/fiCustomers/{fiCustomerId})

Customer

• Register User (for Digital Banking) - POST (/registration/v4/fis/{di_fiid}/fiCustomers)

Proxies Requiring V2 oAuth Bearer Tokens (By Service Product & Endpoint):

Accounts

• Get Accounts - GET /v1/accounts
• Get Account - GET (/v1/accounts/{accountId})

Alerts and Messaging

• Get Alert Preferences - GET (/v1/alert-preferences)
• Get Alert Preference by ID - GET  (/v1/alert-preferences/{alertPreferenceId})
• Create Alert Preference - POST (/v1/alert-preferences)
• Update Alert Preference - PUT (/v1/alert-preferences/{alertPreferenceId})
• Delete Alert Preference - DELETE (/v1/alert-preferences/{alertPreferenceId})
• Get Alert Type - GET (/v1/alert-types)
• Create Alert Type - POST (/v1/alert-types)
• Update Alert Type - PUT (/v1/alert-types)
• Delete Alert Type - DELETE (/v1/alert-types/{id})
• Get Alert Templates - GET (/v1/alert-templates)
• Create Alert Template - POST (/v1/alert-templates)
• Update Alert Template - PUT (/v1/alert-templates)
• Delete Alert Template - DELETE (/v1/alert-templates)
• Get Alert History - GET (/v1/alert-history)
• Get Alert History Content - GET (/v1/alert-history-content)

Banking Image Services

• Get Images - GET (/v1/banking-images)
• Get Image - GET (/v1/banking-images/{bankingImageId})

Disclosures

• Get FI Disclosures - GET (/v1/institution-disclosures)
• Create FI Disclosure - POST (/v1/institution-disclosures)
• Update FI Disclosure - PUT (/v1/institution-disclosures/{institutionDisclosureId})
• Get All User Accepted Disclosures - GET (/v1/institution-user-disclosures)
• Create User Disclosure Acceptance - POST (/v1/institution-user-disclosures)
• Update User Acceptance Disclosures - PUT (/v1/institution-user-disclosures)
• Update User Acceptance Disclosure (by ID) - PUT (/v1/institution-user-disclosures/{institutionUserDisclosureId})
• Delete User Acceptance Disclosure - DELETE (/v1/institution-user-disclosures)
• Delete User Acceptance Disclosure (by ID)- DELETE (/v1/institution-user-disclosures/{institutionUserDisclosureId})

Money Movement

• Create Transfer - POST (/v1/transfers)
• Get Recipients - GET (/v1/recipients)
• Get Recipient - GET (/v1/recipients/{recipientId})
• Create Recipient - POST (/v1/recipients)
• Update Recipient - PUT( /v1/recipients/{recipientId})
• Delete Recipient - DELETE (/v1/recipients/{recipientId})

Transactions

• Get Transactions - GET (/v1/transactions)