Managing API Access Tokens

Emplifi uses OAuth 2.0 Bearer tokens to control API access. Each Emplifi Ratings & Reviews site can have up to 10 API access tokens: one primary API access token and nine additional access tokens. The primary token is created and managed via the TurnTo API. The other nine tokens are created and managed in the API page in the Emplifi Ratings & Reviews portal.

When should I make a new API access token?

Create a new API access token when you need to give API access to another platform or company. This provides the ability to identify when the token was generated, maintain an independent token history, and manage API access independently of other tokens. You should not provide your primary access token to other platforms or companies.

Managing the primary API access token

When you are new to Emplifi Ratings & Reviews, use OAuth endpoints in the TurnTo API to obtain a primary API access token. You can also invalidate the primary API access token and get a new one using the API. You cannot manage non-primary API tokens via the endpoints.

The token that uses endpoints in the API is designated the primary API access token.

Users with the appropriate access level can view (but not change) the primary token’s details in the API page within the Emplifi Ratings & Reviews portal. For more on the API page and what you can do there, see Managing non-primary API access tokens.

Obtaining the primary access token

To obtain a primary API access token, submit a POST request to the /oauth2/token endpoint with the following request body:

client_id=<SITE KEY>&client_secret=<AUTH KEY>&grant_type=client_credentials

Replace <SITE KEY> and <AUTH KEY> with the values provided in the Emplifi Ratings & Reviews Portal.

Once generated, a primary API access token does not expire.

Do not share or expose the primary API access token.

Additional API reference documentation: OAuth.

Do not request a new primary access token each time you call the API. Emplifi Ratings & Reviews does not automatically invalidate the primary access token. Consider using a persistent cache to limit the number of calls for the token. If your security process requires the token be renewed periodically, you can invalidate the access token and request a new one.

Invalidating the primary access token

Access tokens do not expire. Only invalidate your primary API access token if it has been compromised or you have a security policy that requires periodically renewing it.

To invalidate the primary access token, submit a POST request to the /oauth2/invalidate_token endpoint with the following request body:

client_id=<SITE KEY>&client_secret=<AUTH KEY>&access_token=<PRIMARY ACCESS TOKEN>

Replace <SITE KEY> and <AUTH KEY> with the values in the Emplifi Ratings & Reviews Portal.

Once the primary access token is invalidated, API requests using the invalid token will result in authorization errors.

Additional API reference documentation: OAuth.

If you invalidate the primary API access token and create a new one via the Emplifi API, the API page in the portal displays the new value for the primary token. It shows the primary token as active, and the primary token’s history is retained.

Managing non-primary API access tokens

In the Emplifi Ratings & Reviews Portal on the API page, you can create, regenerate, validate, and invalidate a site’s non-primary API tokens, and view history for all of a site’s API tokens.

Each token displays a description, the token value, an indicator of whether the token is active (valid), and a timestamp for when the token was generated.

The API page sorts the tokens in this order from top to bottom:

• Primary token

• Active tokens

• Inactive tokens

Permissions

Only Emplifi Ratings & Reviews site admins and customer site managers can access the API page in a site's settings within the Emplifi Ratings & Reviews Portal.

Creating a non-primary token

1. In Emplifi Ratings & Reviews, click Settings → API access.

   

   As long as there are fewer than 10 tokens for a site, a Create Token button appears on the page.

2. Select the Create Token button.

3. In the Create Bearer Token modal, add a description for the new token.

4. Click Continue. The new token is active.

Invalidating a non-primary token

An Invalidate button displays for all active, non-primary tokens on the API page. Click the button to mark the token as inactive (the Active checkbox is empty). API access is denied when a token is invalid.

Remember, you cannot invalidate the primary token from the API page, but after successfully invalidating the primary token, it is marked as inactive in the API page.

Regenerating a non-primary token

A Regenerate button displays for all non-primary tokens. Click the Regenerate button; a new token value is created and the Date Generated field is updated.

You can regenerate an inactive token. To use the regenerated token value, you must also validate the inactive token.

Validating a non-primary token

API access is allowed when a token is valid. A Validate button displays for all inactive, non-primary tokens. When a user clicks the Validate button, the token is marked as active.

You cannot validate the primary token from the API page.

Viewing token history

Click the History button to view the history of an API token.

Emplifi records all changes to a token as entries in the token’s history. Each record includes a timestamp of the change, the user name, and the kind of change:

• Token Created

• Validated

• Invalidated

• Regenerated

Because the primary token is updated more often than other tokens, its history does not include entries for Validated or Regenerated.

Updating token descriptions

When creating a token, a description is required. You can update a token’s description when regenerating, validating, or invalidating the token from the API page. Special characters are prohibited.

You cannot change the primary token’s description, which is always Store Name Primary Token, where Store Name is the site's internal display name.