This guide explains how to authenticate with Contentful’s Content Management API (CMA) using Personal Access Tokens.

What we need

[] API Token [] Organization ID

Overview

Contentful provides several APIs for interacting with your content, with the Content Management API (CMA) being the primary API for creating and managing content. To use the CMA, you need to authenticate your requests, and the Personal Access Token (PAT) method is the most common approach for automated processes and integrations.

Authentication with Personal Access Token (PAT)

The Personal Access Token (PAT) is a simpler and more common method for authenticating with the Content Management API (CMA), especially for automated processes or when building integrations. This method doesn’t require user interaction and is commonly used for services or backend applications.

This is Contentful’s Documentation on getting an Authentication token: https://www.contentful.com/developers/docs/references/authentication/

How to Obtain a Personal Access Token

1. Go to the Contentful Dashboard:
   • Navigate to your Contentful space where you want to interact with the API.
2. Generate the Token:
   • Log in to the Contentful web app.
   • Open the space that you want to access using the space selector in the top left.
   • Click Settings and select CMA tokens from the drop-down list.
   • Click Create personal access token. The Create personal access token window is displayed.
   • Enter a custom name for your personal access token and click Generate. Your personal access token is created.
   • Copy your personal access token to clipboard.

How to Use the Personal Access Token

Once you have your Personal Access Token, you’ll include it in the Authorization header of each API request you make to the CMA.

Example of a CMA API Request

curl -X GET "https://api.contentful.com/spaces/{space_id}/entries" \ 
-H "Authorization: Bearer {your_personal_access_token}"

In this request:

• Replace {space_id} with your actual Contentful space ID.
• Replace {your_personal_access_token} with the Personal Access Token you generated.

This request retrieves the entries in your Contentful space, and the token authenticates the request, granting access to the CMA.

Important Considerations for Using PAT

Permissions

• The Personal Access Token inherits the permissions of the user who generated it.
• It can be scoped to give read, write, or full access depending on the required actions.

Environment-Specific Tokens

• If you’re working with multiple environments in Contentful (like staging and production), ensure the token has access to the relevant environment.

Security

• Store the token securely and never expose it publicly in client-side code. It’s effectively like a password for API access.
• If the token is compromised, revoke it immediately via the Contentful UI.

Token Expiry

• Personal Access Tokens are long-lived but may be revoked at any time. Ensure you handle token management in your application accordingly.

Permissions Example

Here is the documentation around what roles are available: https://www.contentful.com/help/roles/space-roles-and-permissions/

GraphQL API Access

For more advanced queries, especially when you need to retrieve work specifically related to a person, you may need to use Contentful’s GraphQL API:

1. The GraphQL endpoint is available at: https://graphql.contentful.com/content/v1/spaces/{space_id}
2. Authentication works the same way as with the REST API, using the Bearer token in the Authorization header

For more information on using the GraphQL API, refer to the Contentful GraphQL documentation.

Testing Your Authentication

You can verify that your token is working correctly by running the following example request:

curl -X GET "https://api.contentful.com/spaces/{space_id}" \
-H "Authorization: Bearer {your_personal_access_token}"

This should return information about your Contentful space if the authentication is successful.

Support

For questions about Contentful’s API, visit the Contentful Developer Documentation.