API Tokens

Create and manage API tokens for programmatic access to the Watchplane API.

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 — a token acts with its creator’s current role in the token’s organization, so a token never has more rights than the person who made it. If the creator is demoted, the token loses those rights on its next request. If the creator is removed from the organization, the token is revoked and stops working
  • 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
Documentation