API Tokens — Watchplane Docs

API tokens are long-lived credentials for programmatic access to the Watchplane API. They use the wp_ prefix and are sent in the X-Api-Key header.

Only organization Admins can create and revoke API tokens.

Create a token

Dashboard

Go to Settings → API Tokens → New token. Enter a name and click Create. Copy the token immediately — it won’t be shown again.

API

POST /api/v1/api-tokens
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "name": "CI pipeline"
}

Response:

{
  "data": {
    "id": "tok_abc123",
    "name": "CI pipeline",
    "token": "wp_1a2b3c4d5e6f...",
    "createdAt": "2025-01-15T10:00:00Z"
  }
}

The token value is only returned once. Store it securely in a secrets manager or environment variable.

List tokens

GET /api/v1/api-tokens
Authorization: Bearer <access_token>

{
  "data": [
    {
      "id": "tok_abc123",
      "name": "CI pipeline",
      "lastUsedAt": "2025-01-15T10:30:00Z",
      "createdAt": "2025-01-15T10:00:00Z"
    }
  ]
}

Note: the token value is not returned in list responses.

Revoke a token

DELETE /api/v1/api-tokens/tok_abc123
Authorization: Bearer <access_token>

Returns 200 OK:

{ "message": "API token revoked" }

The token is immediately invalidated.

Using a token

Pass the token in the X-Api-Key header for all requests:

GET /api/v1/projects
X-Api-Key: wp_1a2b3c4d5e6f...

Or with curl:

curl -H "X-Api-Key: wp_1a2b3c4d5e6f..." https://api.watchplane.com/api/v1/projects

Security recommendations

One token per integration — create a separate token for each CI pipeline, deployment tool, or service
Least privilege — tokens currently have full admin access; use separate accounts for different access levels if needed
Rotate regularly — revoke and recreate tokens periodically
Never commit tokens — use environment variables or a secrets manager
Monitor lastUsedAt — revoke tokens that haven’t been used in a long time

Environment variable

The CLI and SDK respect the WATCHPLANE_TOKEN environment variable:

export WATCHPLANE_TOKEN=wp_1a2b3c4d5e6f...
wp monitors list