Using UPS Tokens

What are User Personal Secret Tokens?

UPS Tokens (commonly called UPS or User Personal Secrets) are random and unique keys that are exchanged during the Authentication process for an access token.

These access tokens are the same credentials as always, with added information about the user who generated them: This means that these tokens are nominal and non-transferrable.

Where are my Personal Secret Tokens?

You manage your User Personal Secret Tokens from the My Account page in your Inbenta App. To find them, see Managing your UPS Token in the Inbenta Help Center (You need an Inbenta account to see this page).

Oce you have your tokens, see the next section to use them. 

How do I use my Personal Secret Tokens?

The purpose of the User Personal Secrets is to be used for the Inbenta Authentication API. You must provide the tokens on the "user_personal_secret" payload attribute, along with the API "secret" and the API key on the "x-inbenta-key" header.

If the credentials are valid, a new Personal Access Token is issued that contains the information of the user who generated it.

Important: The implementation of any feature related to the retrieval and processing of user information (e.g. actions authorization, tracking, etc.) belongs with the individual Inbenta Product APIs.

Availability  

Actions performed on in the Product App with Personal Secret Tokens are not immediately available on production APIs. There is a delay of two to four minutes to allow for the synchronization of data:

  • If you just created a new token, you may not be able to authenticate during the synchronization period
  • If you just revoked a token, you may still be able to authenticate during the synchronization period.

Restrictions and limitations

  • You can only use Personal Access Tokens with APIs related to the user's instances. If you use a UPS during authentication with an instance that does not belong to the user, the system returns a 403 error.
  • If the token is invalid, does not exist or was revoked, the system returns a 422 error.
  • You cannot refresh Personal Access Tokens. When the token expires, you must request a new one. 

Request & response examples

Authentication with UPS

curl --request POST \
    --url https://api.inbenta.io/v1/auth \
    --header 'content-type: application/json' \
    --header 'x-inbenta-key: YOUR_API_KEY' \
    --data '{
      "secret": "",
      "user_personal_secret": ""
}'

Error responses

// Token does not exist, is invalid or was revoked
{
  "error": {
    "code": 422,
    "message": "Invalid user personal secret"
  }
}
 
// Token is used with a domain key
{
  "error": {
    "code": 422,
    "message": "user_personal_secret can't be used with a domain key"
  }
}
 
// User does not have permissions on the instance of the API
{
  "error": {
    "code": 403,
    "message": "User has no rights for instance"
  }
}
 
// Attempting to refresh a Personal Access Token
{
  "error": {
    "code": 403,
    "message": "Personal Access Tokens cannot be refreshed"
  }
}