Personal access tokens

Personal access tokens (PATs) are long lasting tokens that are used to authorize access to the Dynamic Content Management and the account management features of the GraphQL Asset Management APIs. PATs can be used in the place of a token generated by a clientID and secret.

Tokens are created per user and per organization and are only granted the permissions of the user that created them. A user can only create a token for themselves, it is not possible to create a token on behalf of another user. PATs do not expire, but they can be deleted.

To create and manage PATs, use the GraphQL Asset Management API. You can create tokens in your own code or by using the GraphQL playground.

Creating a token

To create a PAT use the createPersonalAccessToken mutation and send the organization Id and a name as input.

mutation {
  createPersonalAccessToken(
    input: {
      name: "My personal access token"
      organizationId: "T4JnYW5penF0aW9uOm9yZ18QVUI0OU51NDF4eU4zanZQ"
    }
  ) {
    id
    name
    token
    createdDate
    lastUsedDate
  }
}

The token is returned in the response. The PAT returned in this example is not an active token and has been truncated.

{
  "data": {
    "createPersonalAccessToken": {
      "id": "UGVyc29uYWxBY2Nlc3NUb2tlbjoyMDA4MjdjZC1mNTFjLTRkM2UtYmI1MC04NzYyM2QxYzU3NjgvZDE1MGVmZTUtYTllOC00NTQyLWJiM2UtNjM1NjYxOTIwZWFk",
      "name": "My personal access token",
      "token": "amp_pat_0VDx5anoRUK7QmNWYZIOrQ.IqSKk8gASgZKhp…",
      "createdDate": "2023-11-21T14:36:00.916Z",
      "lastUsedDate": null
    }
  }
}

Note that createPersonalAccessToken is the only request that will return the PAT, so you will need to store it securely for future use.

Using the token in a request

Once the token is generated, it can then be used in requests made to the Content Management API and GraphQL Asset Management API. The token is sent in the Authorization header of the request and with the authorization format set to bearer.

For example, to make a request to the Content Management API, you would send a request to the API endpoint, in this case a GET request to return a list of hubs.

GET https://api.amplience.net/v2/content/hubs

In the request header you must set the Authorization format to Bearer and include the access_token: ​

Authorization : Bearer {access_token}

Listing your tokens

You can list your own personal access tokens using the following query:

query {
  viewer {
    personalAccessTokens {
      id
      name
      token
      createdDate
      lastUsedDate
    }
  }
}

A partial example response is shown below.

For each token the request will return the id, name and created and last used date, together with the start of the token itself.

You can delete a token using its id.

{
  "data": {
    "viewer": {
      "personalAccessTokens": [
        {
          "id": "UGVyc29uYWxBY2Nlc3NUb2tlbjoyMDA4MjdjZC1mNTFjLTRkM2UtYmI1MC04NzYyM2QxYzU3NjgvNWU4NTU5ZGMtNTY2ZS00MWU2LWIwZGYtMzU2Njk5OTdlZjhj",
          "name": "my pat token",
          "token": "amp_pat_XoVZ3FZuQeaw3zVmmZfvjA.*******************************************",
          "createdDate": "2023-11-16T13:18:22.925Z",
          "lastUsedDate": null
        },
        {
          "id": "UGVyc29uYWxBY2Nlc3NUb2tlbjoyMDA4MjdjZC1mNTFjLTRkM2UtYmI1MC04NzYyM2QxYzU3NjgvNzQxZDA2ZWQtYjU0OC00YzkwLWJhYzAtM2YzMTI1ZmYzMWU1",
          "name": "My personal access token",
          "token": "amp_pat_dB0G7bVITJC6wD8xJf8x5Q.*******************************************",
          "createdDate": "2023-11-23T14:59:52.016Z",
          "lastUsedDate": "2023-11-23T15:00:23.324Z"
        },
        ....

Deleting a token

You can delete one of your own tokens using the deletePersonalAccessToken mutation, passing in the id of the token as input.

mutation {
  deletePersonalAccessToken(
    input: {
      id: "UGVyc29uYWxBY2Nlc3NUb2tlbjoyZjM4YTFhOS1jNzZkLTRmMzQtOTFmYS02NTJkMDliNmVlZGUvZWI4ZGJmMTgtMGY0Yi00OWFmLWI0YWUtZjZjOGUzZTNkNWNk"
    }
  )
}

Finding token information

You can find out information about a token by using the token itself, even if you didn't create the token. This may be useful if you need to delete a token that you're using for an automation job, for example, and you're not sure who created it. You must still be an admin of the organization in which the token was created.

Include the token in place of the bearer token used in the request to the GraphQL Asset Management API. This is simple to do in the playground, as shown in the image below.

In this example we're listing all the tokens belonging to the user that created the token (1). We can then match the token listed to the one included in the Authorization header, find the token id (2) and use this to delete the token.

To make it easier to identify the owner of the token you can include the name and email address in the response.

query {
  viewer {
    personalAccessTokens {
      id
      name
      token
      createdDate
      lastUsedDate
    }
    email
    id
    name
  }
}

Using tokens for automations

PATs are particularly useful for back end automations because they don't expire. You may want to create a dummy user with only the permissions that are required for a particular job, create a token for that user, and then use that token for the automation task.

Usage notes

• A user must have organization admin permissions in order to create a token.
• A user can only create a token for themselves, it is not possible to create a token for another user.
• Tokens are created per user and for a specific organization. The token provides only those permissions that the user has.
• The token is validated each time it is used. If a user has been removed from an organization or they no longer have sufficient permissions for a particular request, then an error will be returned.
• Tokens are not set to expire but can be deleted.
• Each user can create up to 5 tokens.
• PATs can only be used for Content Management API and the account management features of the GraphQL Asset Management API.
• PATs cannot be used for the CLI tool. The tool requires the use of an API key and secret.

Related pages

GraphQL Asset Management API

GraphQL playground

Content Management API

Finding the organization id