Secure Access

Authentication and Authorization

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.

The user authenticates securely using the identity provider’s user experience (a web form or dialog, a form on a mobile device, or other means) via secure OpenID Connect, using an OAuth2 implicit flow.

Secure client applications such as back office applications may instead use a private { client ID, client secret } pair using the OAuth2 authorization code flow.

Operations in the Authentication API allow a user to authenticate via OpenID Connect and the financial institution’s identity provider and authorization server. After authenticating, the Authentication API returns to the client application an _access token_ which is unique to that authenticated user. The client application must then pass that access token to all API operations which require authentication. The client application must keep the access token secure and not leak the access token to other users.

Client applications should pass the access token via an Authorization header on each request that requires authorization, using the header value Bearer <access-token>. For example if the acquired access token is C1AC67D1EB404070B61DB7ECD5C635A7, the request should use

Authorization: Bearer C1AC67D1EB404070B61DB7ECD5C635A7

The OpenAPI specifications for each API indicate which operations require an authentication access token. The Apiture APIs support two authorization options, either

API Key and OAuth implicit flow (via apitureApiKey and apitureImplicitOAuth security definitions in the OpenAPI document). This uses the OAuth2 implicit flow and should be used for interactive applications, such as web applications, mobile applications, or desktop applications, as it requires user interaction with the identity provider.
API Key and OAuth implicit flow (via apitureApiKey and apitureClientOAuth security definitions in the OpenAPI document). This uses the OAuth2 authorizationCode flow. It is best suited for trusted clients (for example, a financial institution’s back office applications). Unsecured applications such as mobile or web applications should *not* use this authorization mode because such applications cannot keep the client ID and client secret secure.

If a request does not contain a valid API-Key header or a valid Authorization header with a valid access token, the operation will fail with a 401 Unauthorized response code.

Refreshing Expired Tokens

The Authentication API also describes how a client can refresh an access token that has expired. Access tokens have a expiration time (configurable by the financial institution). When the access token is returned during authentication, a refresh token and an expiration time are also returned, so the client can preemptively refresh (renew) and acquire a new access token before the old token expires.

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:

end user
account owner
account 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, but the applicant does not have that permission.

Each secured operation in Apiture APIs requires an OAuth scope as documented in that operation’s security requirements (see the API reference documentation for the security requirements and scopes for each API and operation.) 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 401 Forbidden or a 404 Not Found.

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

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, getApi) or its OpenAPI definiton (the GET /<apiName>/apiDoc operation, getApiDoc) or listing banking products in the Products API, do not require authentication.

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 institutions application develop team or IT department, or an application vendor. Each application should use its own API key.

Obtaining an API key

API keys are available after registering a developer or organization on developer.apiture.com, then registering a new client application. The API key will be granted for that application.

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

Passing the API key on requests

The OpenAPI specifications for each API indicate which operations require an API key.

Client applications must include an API key with all of your requests to the APIs. This is done with a request header called API-Key. If you API key is ba9ac78c04f5270f54db975038d442154f70bfd2af8ec956fb9c, add a header to each API call:

API-Key: ba9ac78c04f5270f54db975038d442154f70bfd2af8ec956fb9c

For example, 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 this 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 the 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 applications which use the 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.

Documentation