> ## Documentation Index
> Fetch the complete documentation index at: https://velt.dev/docs/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.

> [!NOTE]
>
> * Returns permissions per user and resource. Temporary permissions include an `expiresAt` (Unix seconds) value.
> * See the [Access Control overview](https://velt.dev/docs/key-concepts/overview.md#access-control) for concepts and detailed guidance.

# Endpoint

`POST https://api.velt.dev/v2/auth/permissions/get`

# Headers

**x-velt-api-key** `string` *required*

Your API key.

**x-velt-auth-token** `string` *required*

Your [Auth Token](https://velt.dev/docs/security/auth-tokens.md).

# Body

**data** `object` *required*

**properties**

**organizationId** `string` *required*

The ID of the organization to query.

**userIds** `string[]` *required*

Array of user IDs to fetch permissions for.

**folderIds** `string[]`

Optional array of folder IDs to include in the result.

**documentIds** `string[]`

Optional array of document IDs to include in the result.

## Example Request

> [tab] JSON
>
> ```json theme={null}
> {
>   "data": {
>     "organizationId": "org1",
>     "documentIds": ["freestyle-comments1"],
>     "userIds": ["samarth"]
>   }
> }
> ```

> [tab] cURL
>
> ```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

> [!NOTE]
>
> Error responses include an `errorCode` field with structured error codes from the [UserPermissionAccessRoleResult](https://velt.dev/docs/api-reference/sdk/models/data-models.md#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](https://velt.dev/docs/api-reference/sdk/models/data-models.md#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](https://velt.dev/docs/key-concepts/overview.md#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"
                    }
                }
            }
        }
    }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.