Skip to main content

​
Authentication

The Plane API uses API key authentication to secure requests. All API requests must include a valid API key in the request headers.

​
Authentication Method

Plane uses the X-Api-Key header for authentication: 
X-Api-Key: your_api_key_here

​
Obtaining an API Key

To generate an API key:
  1. Log in to your Plane workspace
  2. Navigate to Settings → API Tokens
  3. Click Generate New Token
  4. Provide a descriptive name for your token
  5. Set an expiration date (optional)
  6. Copy the generated token immediately (it won’t be shown again)
Store your API key securely. Never commit it to version control or expose it in client-side code.

​
Making Authenticated Requests

Include the X-Api-Key header in every API request: 
curl -X GET "https://api.plane.so/api/v1/users/me/" \
  -H "X-Api-Key: pk_1234567890abcdef" \
  -H "Content-Type: application/json"

​
Example: Get Current User

curl -X GET "https://api.plane.so/api/v1/users/me/" \
  -H "X-Api-Key: your_api_key"

curl -X GET "https://api.plane.so/api/v1/users/me/" \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json"

​
API Token Types

Plane supports two types of API tokens:

​
1. API Key

  • Rate Limit: 60 requests per minute (default)
  • Scope: User-level access
  • Use Case: Personal integrations, scripts, and automation

​
2. Service Token

  • Rate Limit: 300 requests per minute
  • Scope: Workspace-level access
  • Use Case: Production integrations, high-volume applications

​
API Token Properties

​
token
string
The API token value (only shown once during creation)
​
label
string
Descriptive name for the token
​
user
uuid
ID of the user who created the token
​
workspace
uuid
ID of the workspace the token belongs to
​
is_active
boolean
Whether the token is currently active
​
expired_at
datetime
When the token expires (null for no expiration)
​
last_used
datetime
Timestamp of the last API request using this token
​
created_at
datetime
When the token was created

​
Token Security Best Practices

​
Secure Storage

  • Store API keys in environment variables
  • Use secret management services (e.g., AWS Secrets Manager, HashiCorp Vault)
  • Never hardcode keys in your source code

​
Token Rotation

  • Rotate API keys regularly (every 90 days recommended)
  • Delete unused tokens immediately
  • Use different tokens for different environments

​
Least Privilege

  • Create tokens with the minimum required permissions
  • Use workspace-specific tokens when possible
  • Monitor token usage via the last_used field

​
Authentication Errors

​
Missing API Key

Status: 401 Unauthorized 
{
  "detail": "Authentication credentials were not provided."
}

​
Invalid API Key

Status: 401 Unauthorized 
{
  "detail": "Given API token is not valid"
}
This error occurs when:
  • The API key doesn’t exist
  • The API key has been revoked
  • The API key has expired
  • The API key is inactive (is_active=False)

​
Expired API Key

Status: 401 Unauthorized 
{
  "detail": "Given API token is not valid"
}
API keys with an expired_at date in the past will be rejected.

​
Testing Authentication

Use the /users/me/ endpoint to verify your API key: 
curl -X GET "https://api.plane.so/api/v1/users/me/" \
  -H "X-Api-Key: your_api_key"
Successful response: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "display_name": "John Doe",
  "avatar": "https://example.com/avatar.jpg",
  "avatar_url": "https://example.com/avatar.jpg"
}

​
Rate Limit Headers

Authenticated requests include rate limit information: 
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1678356060
See Rate Limiting for more details.

​
Next Steps

Work Items API

Create and manage work items

Projects API

Manage your projects

Build docs developers (and LLMs) love

Get started for freeTalk to us