Tokens & Security

API Tokens and Security

We provide a valid, signed certificate for our API endpoints. Make sure your connection library supports HTTPS with the SNI extension.

API requests are authenticated using account API tokens. The tokens are keys that grant access to specified endpoints and access to HTTP methods on those endpoints. An authorized API token must accompany every request--requests will otherwise return an error.

The Console's API Tokens page lists your tokens and enables you to manage tokens.

Overview

Your organization has two kinds of production API keys:

Key type	Prefix	Purpose
Secret key	`sk_`	Server-side administration. Used to call the endpoints in this guide. Never expose in client apps or browsers.
Publishable key	`pk_`	Client-side data access. Safe to embed in apps when combined with domain restrictions.

Secret keys authenticate management requests. Publishable keys are the keys you create, configure, and optionally restrict to specific datasets.

NEVER share your Secret API token publicly

What you can do with this API

List, create, update, and delete publishable keys
Rotate your organization's secret key
Restrict a publishable key to a specific set of datasets (dataset allowlist)

Authentication

Every endpoint in this guide requires your organization's secret key (sk_…).

Provide it in either of these ways:

Query parameter (shown in examples below)
```
?token=sk_your_secret_key_here
```
HTTP header (recommended)
```
x-api-key: sk_your_secret_key_here
```

If a non-secret key is used, the API returns:

{ "error": "Secret token required" }

HTTP status: 401

Token management

List tokens

Returns all active production keys (publishable and secret) for your organization.

GET /v1/tokens

Query parameters

Parameter	Type	Default	Description
`limit`	integer	`50`	Page size (1–1000)
`offset`	integer	`0`	Number of records to skip

Example request

curl -s "https://api.blueskyapi.com/v1/tokens?limit=50&offset=0" \
  -H "x-api-key: sk_your_secret_key_here"

Example response

{
  "success": true,
  "tokens": [
    {
      "apiKey": "pk_abc123def456789012345678901234",
      "type": "primaryKeyPublic",
      "keyDomain": "myapp.example.com",
      "nickname": "Production web app",
      "createdDate": "2026-01-15T10:30:00.000Z",
      "isActive": true,
      "datasetAccess": [
        {
          "workspace": "edge",
          "datasetId": "auction_analytics"
        }
      ]
    },
    {
      "apiKey": "sk_your_secret_key_here",
      "type": "primaryKeySecret",
      "keyDomain": null,
      "nickname": null,
      "createdDate": "2025-06-01T08:00:00.000Z",
      "isActive": true,
      "datasetAccess": []
    }
  ],
  "publicTokenCount": 1,
  "publicTokenLimit": 5,
  "pagination": {
    "total": 2,
    "offset": 0,
    "limit": 50
  }
}

Response fields

Field	Description
`tokens[].apiKey`	The key string
`tokens[].type`	`primaryKeyPublic` (publishable) or `primaryKeySecret` (secret)
`tokens[].keyDomain`	Allowed HTTP referer domain for publishable keys, or `null`
`tokens[].nickname`	Human-readable label, or `null`
`tokens[].datasetAccess`	Datasets this publishable key may read when restricted (empty for secret keys)
`publicTokenCount`	Number of publishable keys currently in use
`publicTokenLimit`	Maximum publishable keys allowed for your organization

Get a single token

GET /v1/tokens/{tokenStr}

Replace {tokenStr} with the publishable or secret key you want to inspect.

Example request

curl -s "https://api.blueskyapi.com/v1/tokens/pk_abc123def456789012345678901234" \
  -H "x-api-key: sk_your_secret_key_here"

Example response

{
  "success": true,
  "token": {
    "apiKey": "pk_abc123def456789012345678901234",
    "type": "primaryKeyPublic",
    "keyDomain": "myapp.example.com",
    "nickname": "Production web app",
    "createdDate": "2026-01-15T10:30:00.000Z",
    "isActive": true,
    "datasetAccess": [
      {
        "workspace": "edge",
        "datasetId": "auction_analytics"
      }
    ]
  }
}

Create a publishable key

POST /v1/tokens

Request body

Field	Type	Required	Description
`isTestToken`	boolean	No	When `true`, creates a sandbox key (`Tpk_…`) instead of production (`pk_…`)

Example request

curl -s -X POST "https://api.blueskyapi.com/v1/tokens" \
  -H "x-api-key: sk_your_secret_key_here" \
  -H "Content-Type: application/json" \
  -d '{"isTestToken": false}'

Example response

{
  "success": true,
  "token": {
    "key": "pk_newkey123456789012345678901234",
    "domain": null,
    "nickname": null,
    "createdDate": "2026-06-17T14:00:00.000Z",
    "datasetAccess": []
  }
}

New publishable keys start unrestricted — they can access any dataset your organization is entitled to (subject to subscription and access toggles described below).

Update a publishable key

Update the nickname and/or allowed referer domain. At least one field is required.

PATCH /v1/tokens/{tokenStr}

Request body

Field	Type	Description
`nickname`	string	Display name. Send `""` to clear.
`domain`	string	Allowed HTTP referer domain. Send `""` to remove the restriction.

Only publishable keys (pk_… / Tpk_…) support nickname and domain. Secret keys return a 400 error.

Example request

curl -s -X PATCH "https://api.blueskyapi.com/v1/tokens/pk_abc123def456789012345678901234" \
  -H "x-api-key: sk_your_secret_key_here" \
  -H "Content-Type: application/json" \
  -d '{"nickname": "Mobile app", "domain": "app.example.com"}'

Example response

{
  "success": true,
  "token": {
    "key": "pk_abc123def456789012345678901234",
    "nickname": "Mobile app",
    "domain": "app.example.com"
  }
}

If the domain format is invalid, the API returns HTTP 422:

{ "success": false, "error": "Invalid domain format" }

Delete a publishable key

Soft-deletes a publishable key. Secret keys cannot be deleted through this endpoint — use Rotate secret key instead.

DELETE /v1/tokens/{tokenStr}

Example request

curl -s -X DELETE "https://api.blueskyapi.com/v1/tokens/pk_abc123def456789012345678901234" \
  -H "x-api-key: sk_your_secret_key_here"

Example response

{
  "success": true,
  "token": "pk_abc123def456789012345678901234"
}

Rotate secret key

Issues a new secret key and retires the old one. Plan to update any integrations that store the secret key.

POST /v1/tokens/secret/refresh

Request body

Field	Type	Required	Description
`apiToken`	string	No	Specific secret key to rotate. If omitted, the secret key from the request (`x-api-key` or `token` query param) is rotated.

Example — rotate the key used in the request

curl -s -X POST "https://api.blueskyapi.com/v1/tokens/secret/refresh" \
  -H "x-api-key: sk_your_secret_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Example response

{
  "success": true,
  "token": "sk_newsecret123456789012345678901234"
}

Error responses

Endpoints return JSON error bodies. Common cases:

HTTP status	Error message	Cause
`401`	`Secret token required`	Request used a publishable key instead of a secret key
`401`	`Invalid or missing token`	Secret key is invalid or not recognized
`404`	`Token not found for this organization`	The target key does not belong to your organization
`400`	`cannot delete private key, must be regenerated`	Attempted to delete a secret key
`400`	`nicknames and domains can only be provided for publishable keys`	PATCH called on a secret key
`400`	`At least one of nickname or domain is required`	PATCH body was empty
`400`	`Dataset not found: workspace=…, datasetId=…`	Invalid workspace or dataset ID in PUT body
`400`	`Your subscription does not include dataset: workspace=…, datasetId=…`	Edge dataset not in your subscription
`422`	`Invalid domain format`	Domain string failed validation

Token management endpoints wrap successful responses with "success": true. Dataset permission endpoints return the permission object directly (no success field).

Best practices

Keep secret keys server-side. Only publishable keys belong in client applications.
Set a domain on browser-facing keys. Combine dataset restrictions with a domain value to limit where the key can be used.
Rotate compromised keys promptly. Use POST /v1/tokens/secret/refresh for secret keys and delete/recreate publishable keys as needed.

Quick reference

Method	Path	Description
`GET`	`/v1/tokens`	List all tokens
`GET`	`/v1/tokens/{tokenStr}`	Get one token
`POST`	`/v1/tokens`	Create publishable key
`PATCH`	`/v1/tokens/{tokenStr}`	Update nickname/domain
`DELETE`	`/v1/tokens/{tokenStr}`	Delete publishable key
`POST`	`/v1/tokens/secret/refresh`	Rotate secret key