Secure Access

This page describes how to call Apiture Open Banking APIs securely using API Key and user authentication/authorization.

Authentication

Authentication is the process of verifying who is making an API call.

For end users, authentication involves providing credentials (such as a user ID and password) through the financial institution’s trusted identity provider.

A user is a person who has a user ID and can log on via authentication to the digital banking system. Each user is assigned to a role within the system.

Note: The user’s password does not pass through Apiture Open Banking APIs, but is only processed by the secure identity provider.

Authorization

Authorization determines what permission the user has to access data and perform operations. This is determined by roles assigned to users. Example roles may be:

• digital banking user
• account owner or co-owner
• beneficial owner of a business account
• a teller at a financial institution
• a deposit accounts manager at a financial institution
• an IT manager at a financial technology company

Each role has different permissions. For example, an account owner has permission to view their accounts, balances, and transactions associated with those accounts, or to schedule transfers and payments. A deposit accounts manager may have permission to review an account application and any personal identification documents supplied by the applicant in order to approve an account application.

Each secured operation in Apiture Open Banking APIs defines the OAuth scopes in that operation’s security requirements. If the user’s role grants the corresponding OAuth scope, and if the user has entitlement to the resource (for example, account ca34f402-d4ee-43aa-b0af-eb5a40753d77), the operation is allowed. If not, the API call may return either a 403 Forbidden or a 404 Not Found HTTP response code.

Note: A small number of API operations do not require end-user authentication, only the API key. For example, returning the top-level self-descriptive metadata about an API (the GET /<apiName>/ root operation) or its OpenAPI definition (the GET /<apiName>/apiDoc operation) or listing banking products in the Products API, do not require authentication.

Secure client applications such as back office applications may use a private { client ID, client secret } pair using the OAuth2 client credentials grant.

Creating a client

Before you can integrate authentication and authorization into your client, you need to register on the Dev Portal using your company email account, complete your user profile and company profiles, then register a new client application.

This process will create a request to create an API key, client ID, and client secret for your application for a specific environment.

After submitting the request and reviewing with the financial institution, Apiture will provision the API keys and the client ID and client secret which allow the client’s user to authenticate and request authentication tokens at run time, as described below. These authentication tokens and the API key are used to authenticate each API request.

OAuth Access Tokens

Access tokens are strings which represent a user’s authentication and authorization. This is also known as a bearer token. As part of authentication, the OAuth flow returns an access token to the client application. This access token is unique to that authenticated user and the requesting client application. The client application must keep the access token secure and not leak the access token to other users or other applications.

The OpenAPI definitions include an accessToken security requirement on the operations which require an OAuth access token. The accessToken security requirement is defined by the security definition of the same name in the OpenAPI document. This uses the OAuth2 accessCode flow (also known as an authorization code flow.)

This security requirement means that client applications should pass the access token when invoking the operation. Client applications should send an Authorization request header with the header value Bearer {access-token}. For example, if the acquired access token is C1AC67D1EB404070B61DB7ECD5C635A7, the request should use

Authorization: Bearer C1AC67D1EB404070B61DB7ECD5C635A7

Discovery

To initiate authentication, the client must know where to authenticate the user and where to obtain the access token. OpenID Connect (OIDC) provides a discovery mechanism for this. The client begins by fetching the OpenID Connect configuration JSON data from the target environment. For example, the OIDC configuration URL for the sandbox environment used on DevBank (api.devbank.apiture.com) is currently

https://cognito-idp.us-east-1.amazonaws.com/us-east-1_Ai3eCrI1f/.well-known/openid-configuration

The Authentication API returns the OIDC configuration data URL in the GET /auth/ response, in the link with the rel of apiture:openidConfiguration.

Use an HTTP GET to fetch the configuration data from that URL, and save the authorization_endpoint, token_endpoint, userinfo_endpoint and other connection parameters to complete the authorization flows described below.

Open ID Connect and OAuth 2.0 Authentication

The Authentication API supports OpenID Connect authentication flows and OAuth 2.0:

• Authorization Code Flow (OpenID Connect), for Mobile Applications or Web Applications or apps where a user logs in
• Client Credentials Grant (OAuth 2.0), for secure back-end service applications in a secure environment, such as a financial institution’s back-office applications and scheduled jobs which run without user-level authentication.

OpenID Connect Authorization Code Flow

This interactive flow involves browser redirection to the Apiture Identity Provider URL (the OAuth authorization server) for secure user login and consent. After the first redirection, the user is redirected back to the requesting application using the callback URL associated with the client application in the Dev Portal. The application’s Authentication type in the Dev Portal must be Authorization Code.

1. The client requests user authentication via a GET to the authorization_endpoint from the OpenID Connect configuration data (see Discovery above), passing several query parameters:
   • ?state={state} where {state} is a client-assigned unique value. The client should generate a random string for each auth flow.
   • ?scope=openid
   • &response_type=code
   • the &client_id={clientId} and the &redirect_uri={url-encoded-redirect-uri} that are associated with the registered client application key for that environment.
2. The authorization_endpoint validates the query parameters and if valid, presents a form in which the user enters their login credentials for the financial institution. The user may also be prompted to give consent to specific application access.
3. If the client request and user authentication credentials are valid, the authorization operation returns a 302 response and Location header with the client redirect URI, a code, and the client state value. The client redirect URI is the one that you register for that application in the Dev Portal.
4. The client redirects to the redirect URI in order to process the response and code. That page should ensure the state matches the one passed in step #1 and stop the flow if they do not match.
5. If the state matches, the client exchanges the code for an access token to complete the flow. This step should be done securely in your server code connected to the redirect URI. This is done by POST to the "token_endpoint" URL from the configuration, passing:
   • An Authorization request header with the client credentials in the form
     Basic {encoded-credentials}
     where {encoded-credentials} is a Base 64 encoding of the text client-id:client-secret for the registered client (obtained from the Dev Portal). Tip Avoid calling the token_endpoint directly from a web or mobile client, as this allows easy inspection of the HTTP request and decoding of the client ID and secret from the Authorization header.
   • Pass the parameters as form data using Content-Type: application/x-www-form-urlencoded. The form data consists of three values:
     • grant_type:
       This must be set to authorization_code if using the OAuth 2.0 Authorization code flow or refresh_token when refreshing an expired or expiring access token. grant_type is required.
     • code:
       This must be set to the authorization code returned via a callback redirect after calling the authorize operation when using the OAuth 2.0 Authorization code flow. This is required if grant_type is authorization_code.
     • redirect_uri:
       The URL-encoded callback url for user redirection after successful login and consent with the Apiture Identity Provider. This value must match the value used during the client application registration process and the value passed to authorize. Required if using the authorization_code flow.
6. The response is a JSON body with four properties:

The client combines token_type and access_token to form the the Authorization header for API requests, using this request header:

      Authorization: token_type access_token

API operations which have a security requirement of accessToken must use this Authorization header.

Refreshing Expired Tokens

Access tokens have a expiration time which are configurable by the financial institution. A client application can refresh an access token that has expired or is about to expire. When the access token is returned during authentication, a refresh token and an expiration time are also returned, so the client application can preemptively refresh (renew) and acquire a new access token before the old token expires. The client should use the application server code to POST to the "token_endpoint" (from Discovery above) with the same Authorization header and with form parameters grant_type=refresh_token and refresh_token={refresh_token}, substituting the {refresh_token} with the actual refresh token saved from the initial authentication.

OAuth 2.0 Client Credentials Grant

With this authentication method, the client requests an authentication token passing the client ID and client secret that have been provisioned by the Dev Portal. The application’s Authentication type in the Dev Portal must be Client Credentials. This method does not use user authentication or credentials; hence the access token is not associated with a financial institution customer. This is only suitable for secure applications, such as those in a financial institution’s data center. Web or mobile applications must not use this method.

The Client Credentials Grant flow is started by a POST to the token_endpoint URL from the configuration, passing:

• An Authorization request header encoded credentials in the form
  Basic {encoded-credentials}
  where {encoded-credentials} is a Base 64 encoding of the text client-id:client-secret for the registered client (obtained from the developer portal).
• Pass the parameters as form data using Content-Type: application/x-www-form-urlencoded. The data consists of one value:
  • grant_type:
    This must be set to client_credentials when using client-supplied credentials. grant_type is required.

The response is a JSON body with three properties:

The client combines token_type and access_token to form the the Authorization header for API requests, using this request header:

      Authorization: token_type access_token

API operations which have a security requirement of accessToken must use this Authorization header.

API keys

An API Key is a token which identifies a specific licensed client application. The API key is reserved for specific organizations, such as a financial institution’s development team or IT department, or an application vendor. Each application should use its own API key.

Almost all Apiture Open Banking APIs require a valid API key. This is specified with the apiKey security requirement on API operations.

Passing the API key on requests

The OpenAPI definitions indicate which operations require an API key.

Client applications must include an API key with all of requests to the APIs. This is done with a request header called API-Key, as defined by the apiKey security definition in the OpenAPI definitions.

For example, if you API key is ba9ac78c04f5270f54db975038d442154f70bfd2af8ec956fb9c, add a header to each API call:

API-Key: ba9ac78c04f5270f54db975038d442154f70bfd2af8ec956fb9c

If you are using curl(1):

MY_PRIVATE_KEY=ba9ac78c04f5270f54db975038d442154f70bfd2af8ec956fb9c
curl "-HAPI-Key: $MY_PRIVATE_KEY" -X POST https://....

Header names are not case sensitive, so the API key may be passed as Api-Key or api-key; documentation uses API-Key.

Protecting your API key

An API key is like a key to your house. Just as possession of a house key grants any holder access to the house, possession of an API key grants an application access to Apiture Open Banking APIs. Apiture also uses the API key to meter the API calls. Each API key is tied to API rate limits, and if the limits are exceeded, requests may be rejected.

Additionally, Apiture may revoke API keys if you or Apiture detect malicious access attempts via that API key to customer data. If your believe your API Key has been compromised, contact us immediately to revoke access. Any client applications which use the revoke key will not work until you have updated them to use the new API key.

Thus, you should keep your company’s API key private and secure. Do not share it with other users. For example, do not publish it in examples or documentation.

Apiture Open Banking APIs are only accessed via TLS (over encrypted https) which provides a level of protection for API Keys and Authorization headers passed to the APIs.

Passing the User’s Access Token

Pass the user’s access token in the Authorization request header For example, if the user’s token_type is Bearer and their access_token is eyJraWQiOiJpRVhDVGdJR1BnZFhvWlhINERpRWs4bEZ3S2ZnM2t...bH5ivHPCZsu-LiOST3k-7Dw, add a header to each API call:

Authorization: Bearer eyJraWQiOiJpRVhDVGdJR1BnZFhvWlhINERpRWs4bEZ3S2ZnM2t...bH5ivHPCZsu-LiOST3k-7Dw

Header names are not case sensitive, so the access token may be passed as Authorization or authorization or AUTHORIZATION; documentation uses Authorization.

HTTP Response Codes

If a request does not contain an API-Key header or Authorization header when required (almost all operations require both), the operation fails with a 401 Unauthorized response code. If an operation requires authorization and an invalid API key or access token is passed, the operation returns a 403 Forbidden response code.