> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velt.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Permissions
Use this API to get a user's permissions for various resources like organizations, folders, documents, etc.
* Returns permissions per user and resource. Temporary permissions include an `expiresAt` (Unix seconds) value.
* See the [Access Control overview](/key-concepts/overview#access-control) for concepts and detailed guidance.
# Endpoint
`POST https://api.velt.dev/v2/auth/permissions/get`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
The ID of the organization to query.
Array of user IDs to fetch permissions for.
Optional array of folder IDs to include in the result.
Optional array of document IDs to include in the result.
## Example Request
```json theme={null}
{
"data": {
"organizationId": "org1",
"documentIds": ["freestyle-comments1"],
"userIds": ["samarth"]
}
}
```
```bash cURL theme={null}
curl --location 'https://api.velt.dev/v2/auth/permissions/get' \
--header 'x-velt-api-key: apiKey' \
--header 'x-velt-auth-token: authToken' \
--header 'Content-Type: application/json' \
--data '{
"data": {
"organizationId": "org1",
"documentIds": [
"freestyle-comments1"
],
"userIds": [
"samarth"
]
}
}'
```
# Response
Error responses include an `errorCode` field with structured error codes from the [UserPermissionAccessRoleResult](/api-reference/sdk/models/data-models#userpermissionaccessroleresult) enum. This helps you handle permission resolution failures programmatically.
## Response Schema
The response returns a nested structure with permissions per user and resource type. Each resource permission can include:
| Field | Type | Description |
| ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `accessRole` | `string` | The user's access role (`"editor"` or `"viewer"`) |
| `accessType` | `string` | The effective access type for the resource: `"public"`, `"restricted"`, or `"organizationPrivate"`. Documents inside folders inherit the folder's `accessType`. Also present on `PERMISSION_DENIED` entries. |
| `expiresAt` | `number` | Unix timestamp (seconds) when temporary access expires |
| `error` | `string` | Human-readable error message if permission resolution failed |
| `errorCode` | `string` | Error code from [UserPermissionAccessRoleResult](/api-reference/sdk/models/data-models#userpermissionaccessroleresult) enum (v4.5.4+) |
#### Success Response
```json theme={null}
{
"result": {
"status": "success",
"message": "User permissions retrieved successfully.",
"data": {
"1.1": {
"folders": {
"folder2": {
"accessRole": "editor",
"accessType": "restricted"
}
},
"documents": {
"document1-26-may-2025-folder2": {
"accessRole": "viewer",
"accessType": "restricted"
}
},
"organization": {
"org1": {
"accessRole": "editor"
}
}
}
}
}
}
```
#### Success Response with Context Access Info
When using [Access Context](/key-concepts/overview#set-feature-level-permissions-using-access-context-custom-metadata) for feature-level permissions, the response includes a `context` object with `accessFields` showing which context values the user has access to:
```json theme={null}
{
"result": {
"status": "success",
"message": "User permissions retrieved successfully.",
"data": {
"user_123": {
"documents": {
"document1": {
"accessRole": "editor",
"accessType": "organizationPrivate"
}
},
"organization": {
"org1": {
"accessRole": "editor"
}
},
"context": {
"accessFields": ["widgetId:1", "widgetId:2", "widgetId:3"]
}
}
}
}
}
```
The `accessFields` array contains strings in the format `"fieldName:value"` representing each context field and value combination the user has access to.
#### Permission Denied
```json theme={null}
{
"result": {
"status": "success",
"message": "User permissions retrieved successfully.",
"data": {
"1.1": {
"documents": {
"document5": {
"error": "User does not have access to document",
"errorCode": "permission_denied",
"accessType": "restricted"
}
},
"organization": {
"org1": {
"accessRole": "editor"
}
}
}
}
}
}
```
#### Error Response Examples
When a resource does not exist, is denied, or encounters an error, the response includes both an `error` message and an `errorCode`:
**Resource Not Found:**
```json theme={null}
{
"error": {
"details": {
"1.1": {
"documents": {
"document1-26-may-2025-folder222": {
"error": "Document does not exist",
"errorCode": "does_not_exist"
}
},
"organization": {
"org1": {
"accessRole": "editor"
}
}
}
},
"message": "Folder or document does not exist",
"status": "NOT_FOUND"
}
}
```
#### API Failure Response
```json theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "User permissions retrieved successfully.",
"data": {
"1.1": {
"folders": {
"folder2": {
"accessRole": "editor",
"accessType": "restricted"
}
},
"documents": {
"document1-26-may-2025-folder2": {
"accessRole": "viewer",
"accessType": "restricted"
}
},
"organization": {
"org1": {
"accessRole": "editor"
}
}
}
}
}
}
```