Get Current Identity
Fetch the bot_user identity associated with the current token.
Get Current Identity
Use Case
Use this endpoint to identify the bot user associated with the current token and to inspect the effective capabilities of that token.
Endpoint
| Item | Value |
|---|---|
| Method | GET |
| Path | /v2/users/me |
| Request body | None |
| Returns | bot_user |
| Scope | No additional scope. Any valid protected token can call it. |
Permissions
Requires a valid Bearer token. No additional scope is required.
Response Example
{
"object": "bot_user",
"id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
"name": "My Integration",
"workspace_id": "99999999-9999-4999-8999-999999999999",
"workspace_name": "Team Workspace",
"owner": {
"object": "user",
"id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
},
"capabilities": {
"pages.read": true,
"pages.write": true,
"blocks.read": true,
"blocks.write": true,
"databases.read": true,
"databases.write": true,
"users.read": true,
"users.email.read": false,
"search.read": true
},
"type": "integration",
"integration_id": "77777777-7777-4777-8777-777777777777"
}
Behavior
- The response is the API identity for the token, not the profile of the integration creator.
- OAuth tokens return the scopes authorized for that token.
- Use
capabilitiesto decide which UI actions or background jobs to enable.
Resource scope versus capabilities
capabilities answers "which actions are permitted"; the X-Resource-Scope response header answers "over how much". The JSON body retains the published BotUser shape. The two are independent:
| Value | Meaning |
|---|---|
workspace |
Can reach the whole workspace. |
pages |
Can only reach the explicitly granted pages and their subtrees. |
The same capabilities can come with either resource scope, so decide whether a workspace-wide listing is possible by reading the X-Resource-Scope response header (or credential.resource_scope from the workspace overview); it cannot be inferred from capabilities. When it is pages, workspace-level endpoints such as the sidebar sections and the member list return 403, and you should use List Child Pages to walk the granted subtrees instead.
For workspace scale, product switches and a fuller credential self-check, call Get Workspace Overview.
Errors
401 unauthorized: missing, invalid, or expired token.