Tokens API

Create and manage API Access Tokens.

An API Access Token grants access to specific data through a specific connection. Because the token travels to the browser in a public application, its grants are the security boundary — scope them to exactly what the application reads and nothing more.

Tokens created here are identical to the ones created in the Workspace, so you can manage them either way.

Endpoint	What it does
POST /v3/tokens	Create a token
GET /v3/tokens	List tokens
GET /v3/tokens/{token}	Get a token
PATCH /v3/tokens/{token}	Update a token
DELETE /v3/tokens/{token}	Delete a token

These endpoints need an OAuth Access Token, not an API Access Token. See Authorization.

How grants work

Each grant pairs a connection with a source:

{
  "grants": [
    { "connection_name": "carto_dw", "source": "carto-demo-data.demo_tables.airports" }
  ],
  "allowed_apis": ["sql", "maps"]
}

• source is a fully qualified table name or a SQL query. resource accepts wildcards such as project.dataset.*.

• * grants everything reachable through the connection — avoid it in public applications.

• allowed_apis limits which APIs accept the token.

• referers limits which domains can use it.

A token without expiration_date never expires, and the expiration can only be set at creation. To rotate, create a new token and delete the old one.

Endpoints

Create a token

post

https://gcp-us-east1.api.carto.comhttps://gcp-europe-west1.api.carto.comhttps://gcp-asia-northeast1.api.carto.comhttps://gcp-australia-southeast1.api.carto.comhttps://your-carto-tenant-domain.com/api

/v3/tokens

Creates an API Access Token.

Each grant ties a connection to a source — a fully qualified table name, a SQL query, or * for everything reachable through that connection. Keep grants as narrow as your application allows.

Authorizations

accessToken

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Body

application/json

referersstring[]Optional

Restrict use of the token to these HTTP referers. Empty means any.

namestringOptional

A name for the token. Generated if omitted.

expiration_datestring · date-timeOptional

When the token stops working. Must be in the future. Omit for a token that never expires. Can only be set at creation.

Responses

201

The token was created.

application/json

tokenstringOptional

The token to send in the Authorization header.

referersstring[] · nullableOptional

namestringOptional

user_idstring · nullableOptional

account_idstringOptional

created_atstring · date-timeOptional

updated_atstring · date-timeOptional

expiration_datestring · nullableOptional

400

The request is malformed or a parameter failed validation.

application/json

401

The token is missing, malformed or expired.

application/json

403

The token doesn't grant access to this resource.

application/json

429

You went over the rate limit for this API.

application/json

post/v3/tokens

HTTPcURLJavaScriptPython

POST /v3/tokens HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 135

{
  "grants": [
    {
      "connection_name": "carto_dw",
      "source": "carto-demo-data.demo_tables.airports"
    }
  ],
  "referers": [],
  "allowed_apis": [
    "sql",
    "maps"
  ]
}

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "grants": [
    {
      "connection_name": "carto_dw",
      "source": "carto-demo-data.demo_tables.airports"
    }
  ],
  "referers": [],
  "allowed_apis": [
    "sql",
    "maps"
  ],
  "name": "tk_1a2b3c",
  "account_id": "ac_jfakef5m",
  "created_at": "2026-07-30T16:10:35.732Z"
}

List tokens

get

https://gcp-us-east1.api.carto.comhttps://gcp-europe-west1.api.carto.comhttps://gcp-asia-northeast1.api.carto.comhttps://gcp-australia-southeast1.api.carto.comhttps://your-carto-tenant-domain.com/api

/v3/tokens

Lists the API Access Tokens you can see.

Authorizations

accessToken

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Responses

200

The tokens.

application/json

tokenstringOptional

The token to send in the Authorization header.

referersstring[] · nullableOptional

namestringOptional

user_idstring · nullableOptional

account_idstringOptional

created_atstring · date-timeOptional

updated_atstring · date-timeOptional

expiration_datestring · nullableOptional

401

The token is missing, malformed or expired.

application/json

429

You went over the rate limit for this API.

application/json

get/v3/tokens

HTTPcURLJavaScriptPython

GET /v3/tokens HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "token": "text",
    "grants": [
      {
        "connection_name": "text",
        "source": "text",
        "resource": "text"
      }
    ],
    "allowed_apis": [
      "maps"
    ],
    "referers": [
      "text"
    ],
    "name": "text",
    "user_id": null,
    "account_id": "text",
    "created_at": "2026-08-09T08:47:04.506Z",
    "updated_at": "2026-08-09T08:47:04.506Z",
    "expiration_date": null
  }
]

Get a token

get

https://gcp-us-east1.api.carto.comhttps://gcp-europe-west1.api.carto.comhttps://gcp-asia-northeast1.api.carto.comhttps://gcp-australia-southeast1.api.carto.comhttps://your-carto-tenant-domain.com/api

/v3/tokens/{token}

Authorizations

accessToken

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Path parameters

tokenstringRequired

The token string.

Responses

200

The token.

application/json

tokenstringOptional

The token to send in the Authorization header.

referersstring[] · nullableOptional

namestringOptional

user_idstring · nullableOptional

account_idstringOptional

created_atstring · date-timeOptional

updated_atstring · date-timeOptional

expiration_datestring · nullableOptional

401

The token is missing, malformed or expired.

application/json

403

The token doesn't grant access to this resource.

application/json

404

The resource doesn't exist.

application/json

get/v3/tokens/{token}

HTTPcURLJavaScriptPython

GET /v3/tokens/{token} HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "token": "text",
  "grants": [
    {
      "connection_name": "text",
      "source": "text",
      "resource": "text"
    }
  ],
  "allowed_apis": [
    "maps"
  ],
  "referers": [
    "text"
  ],
  "name": "text",
  "user_id": null,
  "account_id": "text",
  "created_at": "2026-08-09T08:47:04.506Z",
  "updated_at": "2026-08-09T08:47:04.506Z",
  "expiration_date": null
}

Update a token

patch

https://gcp-us-east1.api.carto.comhttps://gcp-europe-west1.api.carto.comhttps://gcp-asia-northeast1.api.carto.comhttps://gcp-australia-southeast1.api.carto.comhttps://your-carto-tenant-domain.com/api

/v3/tokens/{token}

Replaces the grants, referers, allowed APIs and name of a token. The expiration date can't be changed — create a new token instead.

Authorizations

accessToken

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Path parameters

tokenstringRequired

The token string.

Body

application/json

referersstring[]Optional

Restrict use of the token to these HTTP referers. Empty means any.

namestringOptional

A name for the token. Generated if omitted.

expiration_datestring · date-timeOptional

When the token stops working. Must be in the future. Omit for a token that never expires. Can only be set at creation.

Responses

200

The updated token.

application/json

tokenstringOptional

The token to send in the Authorization header.

referersstring[] · nullableOptional

namestringOptional

user_idstring · nullableOptional

account_idstringOptional

created_atstring · date-timeOptional

updated_atstring · date-timeOptional

expiration_datestring · nullableOptional

400

The request is malformed or a parameter failed validation.

application/json

401

The token is missing, malformed or expired.

application/json

403

The token doesn't grant access to this resource.

application/json

404

The resource doesn't exist.

application/json

patch/v3/tokens/{token}

HTTPcURLJavaScriptPython

PATCH /v3/tokens/{token} HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 173

{
  "grants": [
    {
      "connection_name": "carto_dw",
      "source": "carto-demo-data.demo_tables.airports"
    }
  ],
  "referers": [
    "https://example.domain.com"
  ],
  "allowed_apis": [
    "sql",
    "maps",
    "imports"
  ]
}

{
  "token": "text",
  "grants": [
    {
      "connection_name": "text",
      "source": "text",
      "resource": "text"
    }
  ],
  "allowed_apis": [
    "maps"
  ],
  "referers": [
    "text"
  ],
  "name": "text",
  "user_id": null,
  "account_id": "text",
  "created_at": "2026-08-09T08:47:04.506Z",
  "updated_at": "2026-08-09T08:47:04.506Z",
  "expiration_date": null
}

Delete a token

delete

https://gcp-us-east1.api.carto.comhttps://gcp-europe-west1.api.carto.comhttps://gcp-asia-northeast1.api.carto.comhttps://gcp-australia-southeast1.api.carto.comhttps://your-carto-tenant-domain.com/api

/v3/tokens/{token}

Deletes a token and returns the deleted object.

Authorizations

accessToken

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Path parameters

tokenstringRequired

The token string.

Responses

200

The deleted token.

application/json

tokenstringOptional

The token to send in the Authorization header.

referersstring[] · nullableOptional

namestringOptional

user_idstring · nullableOptional

account_idstringOptional

created_atstring · date-timeOptional

updated_atstring · date-timeOptional

expiration_datestring · nullableOptional

401

The token is missing, malformed or expired.

application/json

403

You can't delete this token — either it isn't yours, or a map is still using it.

application/json

404

The resource doesn't exist.

application/json

delete/v3/tokens/{token}

HTTPcURLJavaScriptPython

DELETE /v3/tokens/{token} HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "token": "text",
  "grants": [
    {
      "connection_name": "text",
      "source": "text",
      "resource": "text"
    }
  ],
  "allowed_apis": [
    "maps"
  ],
  "referers": [
    "text"
  ],
  "name": "text",
  "user_id": null,
  "account_id": "text",
  "created_at": "2026-08-09T08:47:04.506Z",
  "updated_at": "2026-08-09T08:47:04.506Z",
  "expiration_date": null
}