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
tokenvalue 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