Authentication

All APIs use the OAuth 2.0 (OAuth2) protocol for authentication and authorization. To authenticate against the API, you must include an API token, generally referred to as a bearer token, in each API call. A bearer token is a string that is used to give the owner of the token access to a resource. The token should be passed as an "Authorization" header using the "Bearer" authentication scheme.

• Authentication during development
  • Creating an API bearer token
  • Authenticate using an API bearer token
• Authentication for production apps
  • OAuth2 scope

Authentication during development

When building applications or tools that use Foundry APIs, users may choose to generate temporary API tokens associated with their account. A temporary API token will hold the same permissions as the user who generated it.

Creating an API bearer token

To create a test API token, follow the steps below:

1. Click Account from the bottom of the Foundry sidebar.
2. Click Settings, click Tokens, and then select Create token.

All user-generated tokens should be kept secure and revoked when they are no longer needed. To revoke tokens manually, return to your tokens list and click Revoke. Tokens are automatically revoked upon expiry.

Authenticate using an API bearer token

To include a token in an API call, pass the token in as an "Authorization" header using the "Bearer" authentication scheme. For example:

Copied!
1
curl -H "Authorization: Bearer <your token>" "https://<hostname>/api/v1/ontologies"

Authentication for production apps

All production applications should use OAuth2 for authentication. OAuth2 improves on the traditional client-server authorization model by providing a layer that enables applications to request access through the use of specifically-issued access tokens and refresh tokens, rather than a static bearer token. OAuth2 manages this access through the use of grants, which are methods of obtaining access tokens. Foundry offers two types of grants:

• Authorization Code grant allows an application to act on behalf of its users. This grant type redirects application users to Foundry to undergo standard authentication in order to gain a short-lived OAuth2 access token.
• Client Credentials grant allows an application to act as a service user. Applications using this grant type must store a client secret which can be used to request a short-lived OAuth2 access token.

Grants are configured during application setup in Developer Console or Control Panel (legacy).

OAuth2 scope

During authorization, OAuth2 clients must specify a scope that represents the permissions requested by the application. In practice, the access granted to the application is the intersection of this scope and the existing permissions of the specific user (in the case of an authorization code grant) or service user (in the case of a client credentials grant) in Foundry.

The API documentation below describes the scopes needed for each endpoint. For example, the Ontologies API documentation specifies the api:ontologies-read scope for reads, api:ontologies-write for writes, and api:ontologies-read api:ontologies-write for both reads and writes.

App builders may limit the scope an application may request from Foundry by navigating to the Resources Panel in Developer Console. This provides a user-agnostic way to control the actions an application may take or the data an application may read from Foundry.

Importantly, a granted scope evaluates only to a set of permissions, not an explicit set of Foundry endpoints. In some cases, an application user may be able to use the granted scope to call underlying service endpoints not listed in the documentation below. We are likely to change this behavior in the future.