Secure Access

This page describes how to call Apiture 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.

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

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>/ 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.

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

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.

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 APIs require a valid API key. This is specified with the apiKey security requirement on API operations.

Obtaining an API key

API keys are available after registering a developer and organization (company or other entity) on developer.apiture.com, then registering a new client application. The API key will be granted for that application. Registering an application on the developer portal also provides a client ID and a client secret.

Note: Until this application registration process is complete, contact Apiture to obtain an API key, client ID, and client secret.

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

HTTP Response Codes

If a request does not contain a valid API-Key header or a valid Authorization header with a valid bearer access token, the operation will fail with a 401 Unauthorized response code. If an operation requires authorization and an invalid API key or access token is passed, the operation will return a 403 Forbidden response code.

Documentation