Applications and 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 client application should use its own API key.

To request an API key, follow the following steps:

  • Register as a user and log onto the Apiture developer portal
  • Register the client application
  • Choose an API product that the client application will use
  • Identify one or more API environments where you wish your client application to call Apiture APIs

See also Secure Access for additional guidance on API key management and keeping your API keys secure.

Terminology

TermDefinition
API Environment A developer requests API keys to allow their app to call Apiture APIs in one or more API environments. These may be test environments, partner environments, demo environments, or full production environments. For example, a (fictional) financial institution 3rd Party Bank operating on the Apiture platform may have three separate environments:
  • api.3rdparty.bank - the production environment where 3rd Party Bank live customer data and accounts are available. The Apiture APIs operating here access live data.
  • uat.api.3rdparty.bank - a user acceptance test (UAT) environment, used to validate applications before promoting them to the production environment.
  • dev.api.3rdparty.bank - a development environment, used for prototyping or developing applications within the 3rd Party Bank institution.
API Product API Products are collections of Apiture APIs that support a specific set of features. Licenses are granted for specific API products. Examples of API products may be Digital Banking or Digital Account Opening. Some products may include (embed) other products.
Client Application A web application, mobile application, or service application that uses the Apiture APIs. Each client application is a unique entity and requires its own API key.
API key An API key is a unique private token that identifies a client application within a specific API environment.

At present, a unique API key is required for each combination of:

  • Client application
  • API product
  • API environment

If an application runs against multiple environments (such as dev, uat, and production), the client should register separate API keys for each.

A client ID and client secret (also known as client credentials) are additional authentication credentials. These credentials allow non-interactive service applications to authenticate to the Apiture APIs. The client ID and client secret combination are only used to authenticate a client application within secure client environments, such as back-office automation processes behind a secure firewall.

Company Each client application is tied to a company (also known as a partner organization). The company is based on the email domain of the developers. For example, developers with @apiture.com email addresses are all members of the same company, identified by the common apiture.com domain. The email addresses are validated, so you can only register as a member of a company/domain if you can receive email at the corresponding email address.

The first person to register with a company domain can invite other developers to the company on the Apiture developer portal.

Registering a Client Application

To request API keys, begin by registering a new client applications.

  • You must be logged in to register a client application.
  • In addition, you must complete your profile on the My Profile page and accept the terms and conditions outlined there.
  • If your organization/company data is not complete, enter your company information in the My Company page.

(My Profile and My Company are also available from the account menu under your user ID at the top right of the page.)

To register a new application, open the My APIs page and click the Create a new Application button. Fill in the information on the form:

The New Client Application form

The form fields are described below:

Field Details
Application Name This is your name for your application, so you can return to and access the application on the dev portal. You should use a unique name for each application within your company/organization name.
Application Type Select the type of application. Authentication and security constraints for applications vary by application type. For example, web and mobile applications are harder to keep secure because they often operate in insecure public networks. Web and mobile applications may require an OAuth call back URL to complete authentication and authorization flows. They use a Client ID but do not use Client Secrets to authenticate the application. Trusted service applications use Client IDs and Client Secrets for their OAuth flow.
Application URL The URL of the application, or a web page which describes the applicaition or allows others to download the application. This is for information purposes.
Redirect URL The redirect URL used in OAuth flows. When a user authenticates with the application's authorization server, the authorization server will redirect to this URL to complete the authentication process. This prevents other applications from using the application's client ID and secret.
Description and Purpose A descrition of your application and its intended use. This is for your information, to help you manage multiple client applications.
Product Each client application must select an API product, which determines which APIs the client is licensed to invoke. In the future, API rate limits will also be available.
Environments Choose one or more runtime API environments where the client application will run. When approved, the developer portal will provision a unique API key for each environment.

Click the **Submit** button. The portal will queue a request to provision the API keys for that application. When that process is complete, you will receive an email. Return to the My APIs page to view the API keys and Client ID/secret for the application. Only the application owner may view the API keys and Client ID/secrets. However, an application owner may designate other members of the company to be co-owners and grant them access to view the API keys. This should be done with caution.

Managing Your Applications

The application owner can return to My APIs at any time to manage their applications. When you select the expand icon for the application in the My Applications list, the table expands to show all environments and the status of each API key.

The application owner(s) can also perform the following actions on the applications:

Action Details
Delete Delete the application. This removes the application's API key from all environments and deletes the application from the My Applications list. Any deployed instances of the software applications using these keys or client credentials will no longer work: all API calls using these keys will fail. Use this only when you and your application users are no longer using the application.

Warning: This operation cannot be undone.

Deactivate You can temporarily deactivate an application. This removes the application's corresponding API keys and client credentials from all environments. This is useful if you suspect misuse or suspicious activity with your API keys.

Warning: After disabling the application, any deployed application instances will no longer work. All API calls using these keys or client credentials will fail until you restore the keys.

Restore You can restore an application you have temporarily deactivated. This restores the application's corresponding API keys and client credentials in all its environments.
Invite Other Team Members You may invite other developers to the Apiture developer portal. Other users can see the company's applications, but not edit or view the API keys for applications owned by others in the company. They can create and edit their own applications. Note: Members must share the same email domain.
Edit the application This operation lets you change the application name, description, application type, product, and environments. New keys will be provisioned for any new environments. Use this with caution, as keys associated with removed environments are deleted, not disabled, and they are not enabled again if you edit the application later add those environments back.

In the future, there will be an operation to recycle the API keys. This will replace the application's keys in each environment with new keys.

Using API Keys

See also Secure Access for additional guidance on how to pass your client application's API keys to the Apiture APIs.