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 target 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 authorization code flow.

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.

After submitting the request, 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. (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

The OpenID Connect Discovery metadata can be retrieved via GET /auth/openid/metadata.

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 developer portal.

  1. The client requests user authentication via the authorize operation, passing a unique random state value
  2. The Authentication API redirects (via a 302 response) to an authorization page. For example, if the Apiture banking application is on host https://third-party.bank.com and APIs deployed at https://api.third-party.bank.com, the client accesses the Authentication API at https://api.third-party.bank.com/auth/authorize which redirects the client to the authorization server at https://auth.third-party.bank.com/auth/authorize
  3. The user may also be prompted to give consent to specific application access
  4. The user authenticates by accepting the application’s request and entering their credentials in the authorization server’s form
  5. If the client request and user authentication are valid, the authorization operation return a 302 response and Location header with the client redirect URI, a code, and the client state value. The the client redirect URI is the one that you register for that application in the Dev Portal.
  6. The client redirects to the redirect URI in order to process the response and code. The request handler should ensure the state matches the one passed in step #1.
  7. If the state matches, the client exchanges the code for tokens via the getToken operation to complete the flow

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 developer portal. 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.

Refreshing Expired Tokens

Access tokens have a expiration time (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 call the getToken operation with query parameters ?grant_type=refresh_token&refresh_token={refresh_token}, substituting the refresh token save from the initial authentication for the {refresh_token} value.

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 will use 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 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 API key may be passed as Authorization or api-key; documentation will use 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.