Personal Access Tokens

Authentication and authorization is a tough topic. Every developer at a certain point faced the challenges of having to protect some kind of web app, restricting access in some way. Thankfully the ways of doing this are many, but this means that you still need to pick the most appropriate one for your situation.

At Contentful, that meant using OAuth2. As the de facto standard, it was simply the choice that made the most sense. However, OAuth2 certainly isn’t the most immediate solution to get started: obtaining a valid token requires you to do certain steps such as hosting an app on a secure server, and for development purposes, that might be an overkill. This is why we implemented Personal Access Tokens, as a way to make the CMA even more accessible and easy to pick up and run. They are a widespread standard used across well known organisations or services, such as Github.

What is a Personal Access Token and when should I use it?

Personal Access Tokens are an easier alternative to regular OAuth tokens. Technically, it allows access to our CMA, and just like a OAuth token, it is tied to the user who requests it, meaning that they will have the same permissions as the user (in terms of access to organizations, spaces and content).

The difference is subtle but important: with OAuth, you authorize an app to talk to Contentful on your behalf, and 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.

Whether you should use Personal Access Tokens or regular OAuth tokens highly depends on your use case. OAuth apps allow other users to authenticate against Contentful in order for your app to use the issued token. Personal Access Tokens are managed by the user, 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.

How to get a Personal Access Token: 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

{
  "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:

{
  "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.

What is the CMA tokens admin view?

Located under “Settings,” the CMA tokens page provides a complete list of Personal Access Tokens (PAT) 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. 

How do I revoke a token from the 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.

How do I remove a user from the 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. 

How to get a Personal Access Token: the web app

Of course, the easiest way to manage these tokens it through our web app. In the main navigation, choose Settings and CMA tokens. From there, click Generate access token and input the name you wish to use. You will see the following:

It’s important that you copy the actual token: as with the normal API requests, you won’t get access to it any more 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.

Conclusions

This was another step in the our never-ending effort for great a developer experience. We believe this will make starting using Contentful even easier, for first-time users and seasoned Contentful aficionados alike, so get your shiny new Personal Access Token and happy developing!