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.

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 Space settings and API keys. Then select the Content management tokens tab. From there, click on the Generate access token button and input the name you wish to use. You should see something like this:

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!