METAGROK
API / create-a-user-scoped-worker-token-via-api

API

Create a user-scoped worker token via the Cloud Agents API

create-a-user-scoped-worker-token-via-api

Mint a one-hour user-scoped token so a worker can run as an active team member with POST https://api.cursor.com/v1/sub-tokens. Official reference: Cloud Agents API → Create A User-Scoped Worker Token.

The Cloud Agents API v1 is in public beta. This endpoint requires an agent-scoped team service account API key. User-scoped tokens cannot mint other user-scoped tokens. Authenticate with Bearer (or Basic) using that service account key. Availability: Beta (all plans) per the API overview.

The returned token expires after 1 hour and cannot refresh itself. Mint a new token with the service account API key when a running worker needs a refresh.

Request body

Specify exactly one of:

Field Type Meaning
forUserEmail string (optional) Active team member email. Case-insensitive.
forUserId integer (optional) Active team member's numeric Cursor user ID.

By email:

curl --request POST \
  --url https://api.cursor.com/v1/sub-tokens \
  --header "Authorization: Bearer $CURSOR_SERVICE_ACCOUNT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "forUserEmail": "alice@company.com"
  }'

By user ID:

curl --request POST \
  --url https://api.cursor.com/v1/sub-tokens \
  --header "Authorization: Bearer $CURSOR_SERVICE_ACCOUNT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "forUserId": 42
  }'

Response

{
  "accessToken": "eyJ...",
  "expiresAt": "2026-04-24T19:00:00.000Z",
  "userId": 42,
  "teamId": 456
}

Treat accessToken as a secret. Store it only for the worker session, and mint again after expiresAt.