Personal Access Tokens
Personal Access Tokens (PATs) offer a simpler alternative to OAuth tokens for accessing the Content Management API (CMA). Like OAuth tokens, PATs are tied to the user who requests them and carry the same permissions, including access to organizations, spaces, and content.
The key difference is that with OAuth, an app is authorized to interact with Contentful on your behalf, and you may never see the credentials. With PATs, you directly request and manage the credentials.
Choose between PATs and OAuth tokens based on your use case. OAuth is ideal for apps where multiple users need to authenticate against Contentful. In contrast, PATs are user-managed and tied to a single account, making them suitable for development and automation tasks that require access from a single Contentful account.
Personal Access Tokens: API endpoints
We have added new endpoints to our CMA to manage Personal Access Tokens, so you can create them, list them, and revoke them using our API. You can find all the details in the docs, but let's take a quick look. For creating a Personal Access Token, send a POST request to https://api.contentful.com/users/me/access_tokens with the body
The response will contain the newly generated access token, but be careful: this is the only time you will be shown the Personal Access Token, so make sure you store it somewhere.
To navigate the current tokens, you can make GET requests to https://api.contentful.com/users/me/access_tokens and https://api.contentful.com/users/me/access_tokens/<tokenId>. Bear in mind that these endpoints will only return the name and scope of the tokens (and some metadata), but not the token itself. This is an example response:
The final endpoint is for revoking the token. To do so, make a PUT request to http://api.contentful.com/users/me/access_tokens/<tokenId>/revoked.
personal access token JSON snippet 1
{
"name": "My Test Token",
"scopes": [
"content_management_manage"
]
}
The response will contain the newly generated access token, but be careful: this is the only time you will be shown the Personal Access Token, so make sure you store it somewhere.
To navigate the current tokens, you can make GET requests to https://api.contentful.com/users/me/access_tokens and https://api.contentful.com/users/me/access_tokens/<tokenId>. Bear in mind that these endpoints will only return name and scope of the tokens (and some metadata), but not the token itself. This is an example response:
personal access token JSON snippet 2
{
"sys": {
"type": "Array"
},
"total": 0,
"skip": 0,
"limit": 100,
"items": [
{
"sys": {
"type": "PersonalAccessToken",
"id": "exampletokenid",
"createdAt": "2015-05-18T11:29:46.809Z",
"updatedAt": "2015-05-18T11:29:46.809Z"
},
"name": "My Token",
"revokedAt": null,
"scopes": [
"content_management_manage"
]
}
]
}
The final endpoint is for revoking the token. To do so, make a PUT request to http://api.contentful.com/users/me/access_tokens/<tokenId>/revoked.
CMA tokens admin view
Located under “Settings,” the CMA tokens page provides a complete list of Personal Access Tokens (PATs) that have access to your organization.
The table summary consists of the token name, date of creation, expiration date, author, type of token and status of the token. You can apply filters to search for tokens by the created date, expiration date, token type and the status of the token.
To search for a token, you can enter the last four digits of the token.
Revoke token from organization
Personal Access Tokens are tied to the users within your organization. In order to prevent a token from accessing your organization, you can click on the name of the author and remove the user from your organization. This will also remove all other tokens belonging to that user from accessing your organization.
NOTE: In order to revoke a token, the user (located under author in the table) must be removed from the organization.
Remove user from organization
To remove a user from the organization by clicking on the user name under the “Author” column. A modal will appear with the user’s access to spaces and teams. At the bottom of the modal, click Remove from organization and the confirmation modal.
Once the user is removed from the organization, their tokens will no longer have access to your organization.
Securing CMA tokens
Content Management API tokens have similar behavior as passwords. Any user can use it in Contentful Contentful on your behalf, so it is important to protect these credentials.
You will need to use environment variables as much as possible. Add any file where a token is mentioned to your VCS ignore list to make sure it can't be leaked.
Getting a Personal Access Token without a Content Management Access token
You need to get a Content Management API token from the Contentful web app. You can request it in the API section.
OAuth app and Personal Access Token use cases
OAuth apps allow other users to authenticate against Contentful for your app to use the issued token as part of its process.
Personal Access Tokens are personal, which means that they are tied to a single Contentful user account. This makes Personal Access Tokens good candidates for development, as well as automation purposes, when an application does only require a single Contentful account to manage content.
Tokens issued by OAuth app and Personal Access tokens
Both use cases are token issuers used to access the Contentful Content Management API. They are both tied to the user who requested it. They both have access to the same organizations, spaces and content as the token’s owner.
With OAuth, you authorize an app to correspond to Contentful on your behalf. This might not ever see the credentials that the app uses; on the other hand, with Personal Access Tokens you are in charge of asking for the credentials to the API, and subsequently managing them.
Personal Access Tokens expiration dates
When you create a personal access token, we recommend that you set an expiration for your token. Upon reaching your token's expiration date, it is automatically revoked. Adding an expiration date increases your organization's ability to secure how your data is accessed.
Set an expiration date for Personal Access Tokens
NOTE: You cannot set an expiration date on existing tokens.
To add an expiration date for a Personal Access Token, you must create a new token. Click Create personal access token at the top right corner of the CMA tokens page. In the modal, enter the name of the new token and choose an expiration date from the dropdown. Click Generate to create the new token.
When a token is approaching expiration, individuals who created the token will receive email notifications with guidance on how to create a new token. However, tokens with an expiration time of less than 1 day will not receive an email notification.
Obtain Personal Access Token in web app
In the main navigation, choose Settings and select CMA tokens. Click on the Create access token and input the intended name.
Important: copy the token. Similar to other API requests, you will not get access to the token after closing this window.
After creating a token, you will see it (along with all previous tokens you created) in the same page, where you will have the ability to revoke them.