Get current user

GET/api/v2/users/me/

Return the principal behind the credentials you just sent: which user it acts as, whether it is an OAuth token or an API key, and which scopes it carries.

Call this first with a new key or a newly authorized OAuth app. A 200 confirms the credential is accepted and shows its scopes, so you can check whether an endpoint is in scope before you debug it.

Path parameters

None. The path is fixed. It has no {slug} and no user id because the endpoint describes the credential, not a workspace or a user you choose.

Query parameters

None. The endpoint has no filters, no pagination, and no ?expand=.

Scopes

No fine-grained scope is required. The endpoint declares none, so there is no users:* scope to request.

An API key can always call it. An OAuth token needs a read scope, and a token granted only write scopes gets 403. In practice, any token issued for real work already has one, so this endpoint is a reliable check when you're unsure what your credential can reach.

Errors

Status	Code	Cause
401	unauthorized	Missing or invalid credentials: a wrong key, the wrong header, or an expired or revoked OAuth token.
402	payment_required	The feature this endpoint belongs to isn't enabled on your plan, or is switched off.
403	forbidden	The credential is valid but has no read scope, for example an OAuth token granted only write scopes.
404	not_found	The calling principal could not be resolved to a user record.
406	not_acceptable	The Accept header asks for a representation the API can't produce.
429	rate_limited	Throttled. Honor the Retry-After header before retrying.

Separate 401 from 403 before you debug anything else

A 401 here means the credential is wrong, so no other endpoint will work either. A 200 here and a 403 elsewhere means the credential is fine, but the scope or role is too narrow for that endpoint. Compare its documented scope with the scopes array in this response.

Send the key as X-Api-Key

v2 reads the API key from X-Api-Key, or an OAuth token from Authorization: Bearer <token>. v1's X-API-Key casing is a common cause of a 401 here when porting a v1 client. See Authentication.

A 409 isn't a credential problem

If your scopes look right and a write still returns 409 work_item_types_managed_at_workspace or work_item_types_managed_at_project, the credential is fine. The workspace manages work item types on the other surface, and the same call succeeds there. See Work item type modes.

Get current user

curl -X GET \
  "https://api.plane.so/api/v2/users/me/" \
  -H "X-Api-Key: $PLANE_API_KEY"

import requests

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

print(me["principal_kind"], me["email"])
if "projects.work_items:write" not in me["scopes"]:
    raise SystemExit("This credential cannot create work items.")

const response = await fetch("https://api.plane.so/api/v2/users/me/", {
  headers: {
    "X-Api-Key": "your-api-key",
  },
});
const me = await response.json();

const canWriteWorkItems = me.scopes.includes("projects.work_items:write");

Response200

{
  "id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
  "display_name": "Priya Raghavan",
  "email": "priya@example.com",
  "principal_kind": "oauth",
  "scopes": [
    "projects.work_items:read",
    "projects.work_items:write",
    "projects.states:read",
    "workspaces.members:read"
  ]
}

Response200

{
  "id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
  "display_name": "Priya Raghavan",
  "email": "priya@example.com",
  "principal_kind": "api_key",
  "scopes": []
}

Response401

{
  "type": "unauthorized",
  "code": "unauthorized",
  "detail": "Authentication credentials were not provided or are invalid."
}

Reading the response

• principal_kind is the credential type: oauth for an application token acting for a user, api_key for a personal key, and other for anything else the server authenticates.
• scopes is the OAuth grant. For an OAuth token, it lists the fine-grained scopes the user consented to. Check it against the scope named on the endpoint you're calling. An empty array means the credential has no fine-grained scopes.
• id is the identity your writes carry. It appears as created_by_id on objects you create and as actor_id in audit logs.
• The response doesn't include roles. Scopes limit what a token may attempt, and the user's role in each workspace and project decides whether it succeeds. A 403 when the right scope is listed here is a role problem.

Related

• Users overview
• Authentication
• Members overview: the roster where this id appears as member_id
• Errors: the full list of error codes