Authentication

All requests that are made to Amperity API endpoints must be authenticated using an API key.

Authenticate to Amperity APIs by including the following line in the request:

-H "Authorization: Bearer ${access-token}"

After the token passes validation, the request will look up any access policies attached to the API key, and then determine whether the requested operation is permitted.

Authenticate to Amperity APIs by including the following line in the request:

-H "Authorization: Bearer ${access-token}"

After the token passes validation, the request will look up any access policies attached to the API key, and then determine whether the requested operation is permitted.

Important

A user must be assigned the Allow API key administration policy before they can manage API keys and access tokens that are required by Amperity APIs.

A user who is assigned the Allow user administration policy can assign the Allow API key administration policy to individual users within your tenant.

API keys

Amperity API keys are synthetic identities that are bound to your tenant and enable programmatic access to Amperity.

Add API key

Each API key has a unique internal secret that is signed into the claims of all access tokens that are issued for that API key. This secret is one of the validation checks that occurs during authentication to the Amperity API.

An API key enables your downstream use cases to interact with the Amperity API.

To add an API key for the Amperity API

	Open the Settings page, and then select the Security tab. Under API keys click Add API key.
	From the Add API key dialog, add the name for the API key, select the DataGrid Operator option, and then click Save.

Rotate API key

You can rotate the internal secrets used by access tokens to ensure that previously-issued access tokens cannot authenticate to the Amperity API.

When an API key is rotated a new internal secret is generated, after which it becomes the active secret for that API key. The previously-issued access token is deposed, which allows the previous code to remain valid for a short period of time to allow for distribution of the new access token. A deposed access token will remain valid for 30 days, or may be explicitly dropped.

If an access token already has a deposed token, that deposed token is dropped and the previously-issued access token will take its place as the deposed token.

This process may be used to invalidate outstanding tokens issued without expiry times. Clients should be careful not to rotate too often (e.g. on every issue call), or they will be surprised when their existing tokens stop working suddenly.

Note

If you rotate your tokens too quickly you may run into issues where previously-issued access tokens are not deposed for a long enough time, which prevents newly-issued tokens from being distributed.

API tokens can be rotated directly from Amperity.

To rotate API keys

	Open the Settings page, and then select the Security tab.
	Under API keys find the index, and then from the Actions menu select “Rotate API token”.

Access tokens

Access to the Amperity API requires using JSON Web Token (JWT) access tokens that are signed by Amperity-managed API keys.

Generate access token

A JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties.

Amperity uses a JSON Web Token (JWT) for authentication to the Amperity API. These access tokens are issued from API keys which are authorized to perform certain actions with Amperity.

Because a JWT access token automatically expires, tokens should be refreshed on a regular basis.

Access tokens are managed directly from the Amperity UI.

Programmatic workflows should authenticate to Amperity APIs using JWT access tokens as the bearer token within the header of a request.

Access tokens that enable authentication to the Amperity API are managed directly from the Users & Activity page in Amperity.

To generate access tokens

	Open the Settings page, and then select the Security tab.
	Under API keys find the API key for which you want to generate an access token, and then from the Actions menu select “Generate access token”.
	Select the number of days this token will allow access to the API, after which it will expire. For example, 3 days: Use the Rotate key secret option to rotate an existing secret when generating an access token. This will force all previously-provisioned tokens that are associated with the current API key to expire in 30 days. Click Generate token. The token is generated, and then is automatically copied to your clipboard. Important You are the only person who will have access to the newly-generated access key. Amperity does not save the access key anywhere and it will disappear when you close this dialog. Store the access key in a safe place.

Revoke access token

You may revoke access tokens associated with an API key by opening the Actions menu for an API key, and then choosing Revoke tokens. There are two options:

1. Revoke all tokens that were issued prior to the last rotation.

2. Revoke all tokens immediately.

The selected action cannot be undone.

To revoke access tokens

	Open the Settings page, and then select the Security tab.
	Under API keys find the API key for which you want to revoke tokens, and then from the Actions menu select “Revoke token”.
	From the Revoke tokens dialog, choose one of the following options: Use Revoke old tokens to revoke only tokens that were created prior to the last rotation. Use Revoke all tokens to immediately revoke all tokens.
	Click Revoke tokens, and then confirm that you want to revoke the selected tokens. This action cannot be undone.