Was this page helpful?

Authentication

To retrieve or store content with Contentful, you first need to authenticate your app with an OAuth bearer token. Contentful offers five APIs, and each requires separate authentication, except for the Images API, which delivers images without authentication.

A token provides read-only access to one or more environments. We recommend using different access tokens for different environments in your development process. For example, use one for your production environment and another for staging or continuous integration. This allows you to revoke them individually in the future and manage your delivery channels independently.

There are two ways to send the authentication token to an API. You can include it as a query parameter, access_token=$token, or as an HTTP header Authorization: Bearer $token. The header method is recommended.

# As a query parameter:
curl -v https://cdn.contentful.com/spaces/cfexampleapi/entries?access_token=b4c0n73n7fu1
# As a header:
curl -v https://cdn.contentful.com/spaces/cfexampleapi/entries -H 'Authorization: Bearer b4c0n73n7fu1'

If you fail to include a valid access token, you will receive an error message:

# Request
curl https://cdn.contentful.com/spaces/cfexampleapi/entries?access_token=wrong

# Response
{
  "sys": {
    "type": "Error",
    "id": "AccessTokenInvalid"
  },
  "message": "The access token you sent could not be found or is invalid.",
  "requestId": "bcc-1808911724"
}

If you include a valid access token, but one that is not able to access a resource, you will receive a 404 error:

# Request
curl https://cdn.contentful.com/spaces/some_other_space/entries?access_token=b4c0n73n7fu1

# Response
{
  "sys": {
    "type": "Error",
    "id": "NotFound"
  },
  "message": "The resource could not be found.",
  "details": {
    "sys": {
      "type": "Space"
    }
  },
  "requestId": "9f3-2148374087"
}
Note: If you use one our language or platform SDKs, setting your token in a configuration file will handle the authentication process for you.

Each Contentful API requires you follow different steps to obtain an access token.

The delivery and preview API

These two APIs use an API key that you can create using the Content Management API.

You can also create API keys using the Contentful web app. Open the space that you want to access (the top left corner lists all spaces), and navigate to the Settings > API keys. Select the API keys option and create your first token.

The Content Management API

To access the content management API and store content created in your apps, you need a content management token that represents the desired account of your user. This token will have the same rights as the owner of the account. There are two types of content management tokens which you can use:

  • Personal access tokens - Use if you're using the content management API to access data from your own Contentful user account
  • OAuth tokens - Use if you're building a public integration that requests access to other Contentful user's data

Getting a personal access token

You can create personal access tokens using the Contentful web app. Open the space that you want to access (the top left corner lists all spaces), and navigate to the APIs area. Open the Content management tokens section and create a token.

Note: Make sure to immediately copy your new Personal Access Token. You won’t be able to see it again!

Getting an OAuth token

Contentful doesn't have an API for acquiring an OAuth token directly for a user account, OAuth applications acquire them.

If you are creating an application intended for re-use by other Contentful users, you should follow the Create OAuth 2.0 application.