Get the current principal
Returns the identity of the credential making the request: user_id
(a user handle, or null for API-key principals, since API keys are
not tied to a user), org_id, is_staff, the effective scopes,
and a preferences sub-object carrying the user's stored UX
preferences (currently timezone).
scopes is always an array and is never null, so you can iterate it
without a nil check. Customer principals always see is_staff: false.
preferences is null for API-key principals (api keys are not
user-scoped) and for Clerk callers whose user row has not yet been
materialised by the user.created webhook. When non-null, the
sub-object carries timezone: <IANA name> or timezone: null for
"never set", the FE then falls back to the browser's resolved
timezone or UTC.
This endpoint requires only authentication; no scope is needed.
Authenticate by sending your API key as a bearer token:
Authorization: Bearer am_live_.... Every request is automatically
scoped to the organization that owns the key and to the scopes granted
to that key.
In: header
Response Body
application/json
application/json
curl -X GET "https://example.com/v1/me"{
"success": true,
"data": {
"user_id": "9f8a5b34-1234-5678-9abc-def012345678",
"org_id": "0190a1b2-c3d4-e5f6-a7b8-c9d0e1f2a3b4",
"is_staff": false,
"scopes": [
"messages:send",
"messages:read",
"org:read",
"org:admin:write"
]
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "authentication failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}