Users overview

The users resource has one endpoint. GET /api/v2/users/me/ returns the principal behind your credential: the kind of credential you sent, the identity it resolves to, and, for OAuth tokens, the scopes it was granted. Call it first after you set up credentials, and when a request fails and you aren't sure why.

The current user object

Attributes

• id string (uuid)

  The user this credential acts as. It's the same id that appears as member_id on member rosters, created_by_id on objects you create, and actor_id in audit logs, so you can use it to confirm which records are yours.

• display_name string

  The user's display name.

• email string (email)

  The user's email address. Use it to confirm the credential belongs to the account you expect, for example when you have separate staging and production keys.

• principal_kind string

  What kind of credential is calling. One of:

  • oauth: an OAuth access token issued to an application
  • api_key: a personal API key sent in X-Api-Key
  • other: anything else the server recognizes as authenticated

• scopes array of string

  The scopes this credential carries. For an OAuth token these are the fine-grained scopes the user consented to, for example projects.work_items:read. Compare this list against the scope named on the endpoint you are calling before you conclude that a 403 is a role problem.

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"
  ]
}

Endpoints

Method	Path	Description
GET	/api/v2/users/me/	Get current user

The path has no workspace slug because it describes the credential, not a workspace. v2 has no /users/{id}/ endpoint. To look up other people, read a workspace or project roster with ?expand=member.

Debugging authentication

This endpoint declares no fine-grained scope. An API key can always call it, and an OAuth token needs only a read scope. That makes it useful for narrowing down a failure:

Symptom	What GET /users/me/ tells you
Every call returns 401	If this returns 401 too, the credential itself is wrong: a bad key, the wrong header, or an expired token.
One call returns 403, others work	Compare scopes against the scope that endpoint documents. A missing scope is the usual cause.
Writes land under an unexpected author	Check id and email. The key probably belongs to a different account than you think.
Not sure whether an integration is OAuth or a key	Read principal_kind.

A 409 is not an auth failure

If scopes contains the write scope for the endpoint and the call still fails with 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 request succeeds there. See Work item type modes.

Scopes don't override roles

A token can do only what both its scopes and the user's role allow. A broad scope on a member-level account is still limited by that member's role, so a 403 when the right scope is listed here points at the role, not the token.

Changed from v1

• The response now describes the principal (the credential) as well as the user. principal_kind and scopes are new, and they're what make the endpoint useful for debugging OAuth apps.
• first_name, last_name, avatar, and avatar_url are no longer returned. display_name and email remain.

See Migrating from v1 for the full list.

Related

• Get current user
• Authentication: how to present an API key or OAuth token
• Members overview: resolve other people from a roster