API Environments

API target environments are servers running the Apiture APIs. You may view available environments at 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 the following three separate environments:

  • dev.api.3rdparty.bank - a development environment, used for prototyping or developing applications within the 3rd Party Bank institution.
  • uat.api.3rdparty.bank - a user acceptance test (UAT) environment, used to validate applications and deployment options before promoting them to the production environment.
  • api.3rdparty.bank - the production environment where 3rd Party Bank live customer data and accounts are available. The Apiture Open APIs operating here access live data.

DevBank is an example of an API environment. You may think of DevBank as a sandbox environment for use by the Apiture Developer Portal. This page uses the DevBank environment as an example, but the information applies to any target API environment available via the Dev Portal.

Selecting a Target API Environment in the Dev Portal

On pages which contain Try It blocks or other interactive features for calling Apiture APIs, the Dev Portal allows users to choose the API environment for API calls.

Select an environment by using the Environment selector in the top banner of the Dev Portal.

Environment selector

Choose the desired target environment from the drop down list.

Users may select from environments where they have access authorization. Note: The Dev Portal does not allow you to select production environments.

Some development or user acceptance test environments exist for a specific partner (such as dev.api.3rdparty.bank). Only Dev Portal users who have verified email addresses associated with such environments may select them from the Environments selector. For example, Walter.White@3rdparty.bank has access to the dev.api.3rdparty.bank environment but anon2893489@black-hats.example.com cannot access the dev.api.3rdparty.bank environment through the Dev Portal.

All users can access the DevBank environment.

Authentication and Authorization

To make API calls in an environment from the Dev Portal, you first need to create a user in that target environment. See Registering Users for additional details.

Once you have registered a user on the environment, you can return to the portal and reselect the environment for API calls. You may need to authenticate again from the portal, since the portal does not employ single sign-on with the target environments.

The Apiture Open APIs create resources owned by your DevBank user, and the APIs return only the data associated with your DevBank identity. All resources in the APIs are guarded by end-user entitlements. For example, each user can see their accounts, but not other peoples’ accounts. (However, co-owners and authorized signers can see their associated accounts.)

Your Explorer API Key and Access Token

When you register with the Dev Portal and select an environment for the first time, the portal requests a new Explorer Key for your use with that environment. Please allow one or two business days for Explorer Key approval. You will receive an email when your Explorer Key is ready. If you do not receive your Explorer Key after a couple of days, please contact us via Support. If your Explorer Key is still pending for an environment, the portal uses a Discoverer Key.

Using the Target Environment in Try It blocks

Apiture APIs require authentication via API keys and OAuth access tokens. See Secure Access for more information. The Dev Portal automatically inserts your Explorer Key and your access token in the Try It blocks in the API reference or tutorials. It inserts your Explorer Key as the API-Key request header and your access token as the Authorization: Bearer <access-token> request header. The API key and bearer token are both presented as masked data in the Try It blocks, but you can reveal them in your My Accounts page.

Using your Explorer API Key and Access Token from outside the Dev Portal

Get your Explorer Key and current access token from the My Account page. A different key and token are assigned for each API environment. Also, the Explorer Key is only associated with the DevPortal, as its client application. To reveal your Explorer Key and your access token in your My Account page, click the “eye-con”.

You can use your Explorer Key as an API Key for direct API calls outside the Dev Portal. See Secure Access for more information about calling Apiture Open APIs in a secure manner. For example, if you reveal your explorer key and access tokens and they have the values 4508485571702fea0e8b and ef0ea4086f04d14d3984c4aefaf7e0aa5c, you can use them in an API call via curl:

# Use bash `read' so your key and token are not saved in shell history:
$ read KEY
4508485571702fea0e8b
$ read TOKEN
ef0ea4086f04d14d3984c4aefaf7e0aa5c
$ curl "-HAPI-Key:$KEY" \
       "-HAuthorization: Bearer $TOKEN" \
       https://api.devbank.apiture.com/accounts/accounts

To use your Explorer Key and access token outside of the Dev Portal in API calls, paste these values into curl or http commands, or into Postman or other API testing tools.

Your Explorer access token expires every 45 minutes, but the Dev Portal automatically refreshes it if you remain active. If you try an API call with your Explorer Key and token and get a 401 Unauthorized or 403 Forbidden HTTP response code, your may have used an expired access token. Return to your My Account page and copy the most recent access token.

You should treat both the Explorer API key and your access token as secret data. Do not share your key or token with others or embed them in source code.