Authentication

The Watchplane API supports two authentication methods: JWT bearer tokens for interactive sessions and API keys for programmatic/CI access.

Bearer tokens (JWT)

Obtain an access token by posting your credentials to the login endpoint:

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "you@example.com",
  "password": "your-password"
}

Response:

{
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": { "id": "usr_abc", "email": "you@example.com" }
  }
}

Include the accessToken in subsequent requests:

GET /api/v1/projects
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token expiry and refresh

Access tokens expire after 1 hour. Use the refresh token to obtain a new pair without re-entering credentials:

POST /api/v1/auth/refresh-token
Content-Type: application/json

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Bearer tokens are intended for use in web dashboards and short-lived scripts. For long-running automation, use API keys instead.

API keys

API keys never expire (unless you revoke them) and are simpler to use in automation. They carry the prefix wp_.

Create an API key

In the dashboard go to Settings → API Tokens → New token, give it a name, and copy the key — it won’t be shown again.

Or via API:

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

{
  "name": "CI pipeline"
}

Response:

{
  "data": {
    "id": "tok_xyz",
    "name": "CI pipeline",
    "token": "wp_abc123...",
    "createdAt": "2025-01-01T00:00:00Z"
  }
}

Use an API key

Pass the key in the X-Api-Key header:

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

Revoke an API key

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

Only organization Admins can create and revoke API tokens. See API Tokens for the full reference.

CLI authentication

The Watchplane CLI uses API keys stored in ~/.config/watchplane/config.json (or set via environment variable):

wp config set --token wp_abc123...
# or
export WATCHPLANE_TOKEN=wp_abc123...

OAuth (Google)

Google OAuth is available for dashboard login only — it is not available for API or CLI access.

Rate limiting

Auth endpoints are rate-limited per IP to prevent brute-force attacks: