Skip to main content

​
Users API

The Users API provides access to user profile information and identity data.

​
Endpoints

​
Get Current User

GET
Retrieve the profile information of the currently authenticated user.

​
Example Request

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

​
Response

{
  "id": "350e8400-e29b-41d4-a716-446655440000",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "display_name": "John Doe",
  "avatar": "https://example.com/avatars/john-doe.jpg",
  "avatar_url": "https://example.com/avatars/john-doe.jpg"
}

​
User Response Fields

​
id
uuid
Unique user identifier
​
first_name
string
User’s first name
​
last_name
string
User’s last name
​
email
string
User’s email address
​
display_name
string
Full display name (typically “First Last”)
​
avatar
string
URL to user’s avatar image
​
avatar_url
string
Alternative URL to user’s avatar image

​
Authentication

This endpoint requires authentication via API key. The response returns information about the user who owns the API key.

​
Testing Your API Key

Use this endpoint to verify that your API key is valid: 
curl -X GET "https://api.plane.so/api/v1/users/me/" \
  -H "X-Api-Key: your_api_key"
A successful response confirms your API key is valid and active.

​
Use Cases

​
Verify Authentication

Check if the current API key is valid and retrieve the associated user: 
curl -X GET "https://api.plane.so/api/v1/users/me/" \
  -H "X-Api-Key: your_api_key"

​
Get User Context

Retrieve user information to personalize your application: 
import requests

headers = {"X-Api-Key": "your_api_key"}
response = requests.get(
    "https://api.plane.so/api/v1/users/me/",
    headers=headers
)

user = response.json()
print(f"Welcome, {user['display_name']}!")

​
Display User Avatar

Retrieve and display the current user’s avatar: 
const response = await fetch('https://api.plane.so/api/v1/users/me/', {
  headers: { 'X-Api-Key': 'your_api_key' }
});

const user = await response.json();
const avatarUrl = user.avatar_url;

// Use avatarUrl in your UI
document.querySelector('#user-avatar').src = avatarUrl;

​
User Lite Serializer

When users appear in other API responses (e.g., as assignees, project members, or cycle owners), they are typically returned using the lightweight UserLiteSerializer format: 
{
  "id": "350e8400-e29b-41d4-a716-446655440000",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "avatar": "https://example.com/avatars/john-doe.jpg",
  "avatar_url": "https://example.com/avatars/john-doe.jpg",
  "display_name": "John Doe"
}
This format is used in:
  • Work item assignees (when using expand=assignees)
  • Project members
  • Cycle owners
  • Module members
  • Comment authors

​
Error Responses

​
Unauthorized

Status: 401 Unauthorized 
{
  "detail": "Given API token is not valid"
}
This error occurs when:
  • The API key is invalid
  • The API key has expired
  • The API key has been revoked
  • No API key was provided

​
Authentication Required

Status: 401 Unauthorized 
{
  "detail": "Authentication credentials were not provided."
}
This error occurs when the X-Api-Key header is missing from the request.

Authentication

Learn how to obtain and use API keys

Workspaces

Access workspace and member information

Build docs developers (and LLMs) love

Get started for freeTalk to us