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

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

The Content Delivery and Preview API

To request data from the Content Delivery API or Content Preview API you can create API keys in two ways:

• use the Content Management API.
• use the Contentful web app

API keys in the Contentful web app

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. To create a personal access token:

1. Log in to the Contentful web app.
2. Open the space that you want to access using the space selector in the top left.
3. Click Settings and select CMA tokens from the drop-down list.
4. Click Create personal access token. The Create personal access token window is displayed.
5. Enter a custom name for your personal access token and click Generate. Your personal access token is created.
6. Copy your personal access token to clipboard.

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.