Service API token

A service API token grants AI Search permission to access R2 buckets in your account. This token is only required if you connect an R2 bucket as a data source. If you use a website or upload files directly through the Items API, you do not need a service API token.

When you need a service API token

You need a service API token when you create an AI Search instance with type: "r2". The token authorizes AI Search to read objects from your R2 bucket for indexing.

Create via the dashboard or Wrangler

The simplest way to get a service API token is to create an R2-backed AI Search instance through the dashboard or Wrangler CLI at least once. Cloudflare creates and registers a service token for you automatically during the setup flow.

Once created, the token is saved to your account and reused across all AI Search instances. You do not need to create a new token for each instance.

Create via the API

If you need to create a service API token programmatically, follow these steps.

1. Create an API token with token creation permissions

You need an API token with permission to create other tokens.

In the Cloudflare dashboard, go to My Profile > API Tokens.
Go to API Tokens
Select Create Token.
Select Create Custom Token.
Enter a Token name, for example Token Creator.
Under Permissions, select User > API Tokens > Edit.
Select Continue to summary, then select Create Token.
Copy and save the token value. This is your CREATOR_TOKEN.

2. Create the service token

Use the Create token API to create a service token with the AI Search Index Engine permission. Replace <CREATOR_TOKEN> with the token from step 1 and <ACCOUNT_ID> with your account ID.

curl -X POST "https://api.cloudflare.com/client/v4/user/tokens" \
  -H "Authorization: Bearer <CREATOR_TOKEN>" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "AI Search Service API Token",
    "policies": [
      {
        "effect": "allow",
        "resources": {
          "com.cloudflare.api.account.<ACCOUNT_ID>": "*"
        },
        "permission_groups": [
          { "id": "9e9b428a0bcd46fd80e580b46a69963c" }
        ]
      }
    ]
  }'

Save the id and value from the response:

{
  "result": {
    "id": "<CF_API_ID>",
    "name": "AI Search Service API Token",
    "status": "active",
    "value": "<CF_API_KEY>"
  },
  "success": true
}

3. Register the token with AI Search

Use the AI Search tokens API to register the service token. Replace <API_TOKEN> with an API token that has AI Search Edit permissions.

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/tokens" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  --data '{
    "cf_api_id": "<CF_API_ID>",
    "cf_api_key": "<CF_API_KEY>",
    "name": "AI Search Service Token"
  }'

Save the id from the response. This is your token_id to pass when creating R2-backed instances:

{
  "success": true,
  "result": {
    "id": "<TOKEN_ID>",
    "name": "AI Search Service Token",
    "cf_api_id": "<CF_API_ID>",
    "created_at": "2025-12-25 01:52:28",
    "enabled": true
  }
}

4. Use the token when creating an instance

Pass the token_id when creating an R2-backed instance:

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/instances" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  --data '{
    "id": "my-r2-docs",
    "type": "r2",
    "source": "<R2_BUCKET_NAME>",
    "token_id": "<TOKEN_ID>"
  }'

Manage your token

Once registered, the service API token is stored securely and reused across all AI Search instances in your account.

Rotate your token

To create a new service API token from the dashboard:

Go to an existing AI Search instance in the Cloudflare dashboard.
Go to AI Search
Select Settings.
Under General, find Service API Token and select the edit icon.
Select Create a new token.
Select Save.

To create a new token via the API, follow steps 1 through 3 above.

View registered tokens

List the service API tokens registered with AI Search in your account:

curl https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/tokens \
  -H "Authorization: Bearer <API_TOKEN>"