Personal access tokens

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

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, by using the GraphQL playground or from within Dynamic Content.

Creating a token using the API

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.

Creating a token in Dynamic Content

You can create a PAT in Dynamic Content by choosing "Personal Access Tokens" from the Development menu, giving the token a name and clicking "Create token".

If you are an organization admin and don't already have 5 tokens added in this account, then the token will be created immediately and available for use in API requests. If you're not an organization admin, then the token creation request will be sent to your admin for approval.

Ensure that you copy the token because you won't be able to access it again. (Note that the token shown in the image below is not an active token).

Once approved, the token is shown in the list, together with any tokens you previously created, either using Dynamic Content or the API.

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"
    }
  )
}

Tokens can also be deleted in Dynamic Content by choosing "Delete token" from the ellipsis menu.

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 using the API. If you are not an organization admin, then you can create a token in Dynamic Content, but the token creation request must be approved by your organization admin.
• 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 be used for the Content Management API, GraphQL Asset Management API and the CLI tool.

Related pages

GraphQL Asset Management API

GraphQL playground

Account management- PAT approval

Content Management API

Finding the organization id

CLI tool