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": "john.doe@example.com",
  "display_name": "John Doe",
  "avatar": "https://example.com/avatars/john-doe.jpg",
  "avatar_url": "https://example.com/avatars/john-doe.jpg"
}

User Response Fields

uuid

Unique user identifier

string

User’s first name

string

User’s last name

string

User’s email address

string

Full display name (typically “First Last”)

string

URL to user’s avatar image

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']}!")

const response = await fetch('https://api.plane.so/api/v1/users/me/', {
  headers: { 'X-Api-Key': 'your_api_key' }
});

const user = await response.json();
console.log(`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": "john.doe@example.com",
  "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

​Users API

​Endpoints

​Get Current User

​Example Request

​Response

​User Response Fields

​Authentication

​Testing Your API Key

​Use Cases

​Verify Authentication

​Get User Context

​Display User Avatar

​User Lite Serializer

​Error Responses

​Unauthorized

​Authentication Required

​Related Endpoints

Authentication

Workspaces

Users API

Endpoints

Get Current User

Example Request

Response

User Response Fields

Authentication

Testing Your API Key

Use Cases

Verify Authentication

Get User Context

Display User Avatar

User Lite Serializer

Error Responses

Unauthorized

Authentication Required

Related Endpoints