Amperity APIs

Amperity has the following APIs:

Profile API

The Profile API is a RESTful API that supports building custom endpoints against unified customer profiles to enable any downstream workflow.

The Profile API is unique to your tenant. The endpoints that are enabled for your use cases do not exist until the results of queries that have been defined by your brand have been published to the Profile API as an index. A set of actions are available for each endpoint that your brand enables when using the Profile API.

Warning

The Profile API is currently in a closed beta. Ask your Amperity representative about potential use cases that are enabled by the Profile API and for information about how (and when) your brand can get access to the Profile API.

Note

The Profile API Administrator policy allows full access to the Profile API, including the ability to manage a list of Profile API endpoints from the Destinations page.

A user must be assigned the Profile API Administrator policy before they can manage endpoints that are enabled by the Profile API.

A user who is assigned the User Administrator policy can assign the Profile API Administrator policy to individual users within your tenant.

Streaming Ingest API

The Streaming Ingest API is a tenant-specific API that supports real-time streaming of data from external systems to Amperity.

Important

The Streaming Ingest API must be enabled for use in Amperity. Contact your support representative via the Amperity Support Portal (or send email to support@amperity.com) to request adding the Streaming Ingest API capabilities to your tenant.

The Streaming Ingest API is designed for streaming events and profile updates. It is a low latency, high throughput REST API, designed to accept billions of records per day.

Authenticate to Amperity APIs

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.

About Amperity API keys

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

  1. Send data to Amperity in from any upstream workflow using the Streaming Ingest API

  2. Pull data from custom endpoints that your brand defines to enable downstream workflows using the Profile API

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

Important

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

A user who is assigned the User Administrator policy can assign the API Key Administrator policy to individual users within your tenant.

About API keys

API keys are managed directly from the Amperity UI.

Add API keys

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.

You can create the following types of API tokens for the Amperity API:

API issuer token

An API issuer token enables your downstream workflow to programmatically issue new access tokens for API keys.

To add an issuer token

Step 1.

Open the Users & Activity page. Under API keys click Add API key.

Step 2.

From the Add API key dialog, add the name for the API key, select the API Issuer Token option, and then click Save.

Generate an API key.

Profile API data access

A data access token enables your downstream use cases to read data the Profile API.

To add a data access token for the Profile API

Step 1.

Open the Users & Activity page. Under API keys click Add API key.

Step 2.

From the Add API key dialog, add the name for the API key, select the Profile API Data Access option, and then click Save.

Generate an API key.

Streaming Ingest API write access

A write access token enables your upstream use cases to write data to the Streaming Ingest API.

To add a data access token for the Streaming Ingest API

Step 1.

Open the Users & Activity page. Under API keys click Add API key.

Step 2.

From the Add API key dialog, add the name for the API key, select the Streaming Ingest Write Access option, and then click Save.

Generate an API key.

Delete API keys

In situations where rotating an access key isn’t enough, you can delete an API key.

To delete API tokens

Step 1.

Open the Users & Activity page.

Step 2.

Under API keys find the index, and then from the Actions menu select “Delete”.

Delete an API token.

Rotate API keys

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 tokens

Step 1.

Open the Users & Activity page.

Step 2.

Under API keys find the index, and then from the Actions menu select “Rotate API token”.

Rotate an API token.

About access tokens

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.

About JWT

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

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

Generate access tokens

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

To generate access tokens

Step 1.

Open the Users & Activity page.

Step 2.

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”.

Generate an access token.
Step 3.

Select the number of days this token will allow access to the API, after which it will expire. For example, 3 days:

Generate an access token.

The token is generated, and then automatically copied to your clipboard.

Generate an access token.

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.

Refresh access tokens

Access tokens may be refreshed directly (using an issuer token), and by using HTTP or cURL.

using API issuer tokens

Use API issuer tokens to enable a downstream workflow to programmatically refresh access tokens. Generate an access token for the issuer token, and then use the issuer token as part of the programmatic workflow.

using cURL

To refresh an access token using cURL, submit a request similar to:

curl -XPOST \
-H "Content-Type: application/json" \
-H "X-Amperity-Tenant: <tenant-name>" \
-H "Authorization: Bearer <token-refresher token>" \
https://<tenant-name>.amperity.com/api/v0/admin/api-keys/<api-key-id>/tokens \
-d '{"expires-at": "2020-06-16T00:24:16Z"}'

using HTTP

To refresh an access token using HTTP, submit a request similar to:

POST /api/v0/admin/api-keys/<api-key-id>/tokens HTTP/1.1
Host: https://<tenant-name>.amperity.com
Content-Type: application/json
X-Amperity-Tenant: <tenant-name>
Authorization: Bearer <token-refresher token>

{"expires-at": "2020-06-16T00:24:16Z"}

using Postman

Postman is a collaboration platform for API development that enables support for sending data to Amperity using the Streaming Ingest REST API.

Amperity provides complete details for refreshing an API token using a Postman collection for the Refresh Token API . Use this collection as the starting point for testing your refresh token workflow.

About Profile API actions

The following actions are available for each endpoint that your brand enables in the Profile API:

Copy endpoint URL

Use this to get the full URL for your tenant, including the ID for the endpoint. Use this URL in the requests your brand makes to the profile API.

Important

Each request to a profile API endpoint MUST have the correct URL for that endpoint. The URL for an endpoint is similar to:

https://{tenant-domain}/attribute/v0/indexes/{index-id}

To copy the URL for an endpoint

  1. Open the Destinations page.

  2. Under Profile API, select    from a row within the list of endpoints, and then select Copy URL.

    Copy the URL for an endpoint in the Amperity Profile API.

    This copies the full URL to the clipboard on your computer, after which you can use it to configure requests that are made to that endpoint.

Copy index ID

The index ID is a unique identifier for an endpoint. To make a request to any Profile API endpoint you must include the index ID in the URL for the request.

https://{tenant-domain}/attribute/v0/indexes/{index-id}

To copy the index ID for an endpoint

  1. Open the Destinations page.

  2. Under Profile API, select    from a row within the list of endpoints, and then select Copy index ID.

    Copy the index ID for an endpoint in the Amperity Profile API.

    This copies the index ID to the clipboard on your computer, after which it can be added to a request that is made to that Profile API endpoint.

Delete endpoint

If your tenant is not using an endpoint, it may be deleted from the Profile API.

To delete an endpoint

  1. Open the Destinations page.

  2. Under Profile API, select the elipses icon for an endpoint, and then select Delete.

    Delete and endpoint from the Amperity Profile API.
  3. Click the Delete button to confirm that you want to delete the endpoint.

Edit endpoint settings

You can update the settings for any endpoint in the Profile API.

To edit the settings for an endpoint

  1. Open the Destinations page.

  2. Under Profile API, select    from a row within the list of endpoints, and then select Edit.

    Edit the settings for an endpoint in the Amperity Profile API.
  3. Make your changes.

  4. Click Save.

Generate endpoint

Run a query to generate the data that will be available from an endpoint. The Run action does one of the following:

  • Generates the index if it was not generated on save.

  • Regenerates the index and refreshes the data that is available at that endpoint.

To run an endpoint

  1. Open the Destinations page.

  2. Under Profile API, select    from a row within the list of endpoints, and then select Run.

    Generate the index for an endpoint in the Amperity Profile API.

    This action will generate the index if it does not already exist OR this action will regenerate the index and refresh the data that is available from the endpoint.

View endpoint settings

You may view the settings for any configured endpoint.

To view the settings for an endpoint

  1. Open the Destinations page.

  2. Under Profile API, select the elipses icon for an endpoint, and then select View.