> ## 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.

# Add Permissions

Use this API to add permissions to a user for various resources like organizations, folders, documents, etc.

> [!NOTE]
>
> * You can add permissions for multiple resources in a single API call.
> * The `expiresAt` field is optional. If provided, the permission will expire at the given timestamp.

> [!NOTE]
>
> **Access Control**
>
> * Set `accessRole` to `viewer` (read-only) or `editor` (read/write) on each resource to define the user's capabilities for that resource.
> * `accessRole` can only be set via the v2 Users and Auth Permissions REST APIs. Frontend SDK methods do not accept or change `accessRole`.
> * Relevant endpoints: `/v2/users/add`, `/v2/users/update`, `/v2/auth/permissions/add`, `/v2/auth/generate_token`.
> * 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/add`

# 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**

**user** `object` *required*

**properties**

**userId** `string` *required*

The ID of the user to add permissions to.

**permissions** `object` *required*

**properties**

**resources** `object[]` *required*

Array of resource objects to grant permissions for.

**Resource Object**

**type** `string` *required*

The type of resource. Can be `organization`, `document` or `folder`.

**id** `string` *required*

The ID of the resource.

**organizationId** `string`

The ID of the organization. Required if `type` is `document` or `folder`.

**accessRole** `string`

Optional access role for this resource. Allowed values: “viewer” | “editor”. Default: "editor".

**expiresAt** `number`

A Unix timestamp (in seconds) that specifies when the permission should expire. This is optional.

## **Example Requests**

#### 1. Add permissions to a specific organization

> [tab] Editor
>
> ```json theme={null}
> {
>   "data": {
>     "user": {
>       "userId": "some-user-id"
>     },
>     "permissions": {
>       "resources": [
>         {
>           "type": "organization",
>           "id": "YOUR_ORGANIZATION_ID",
>           "accessRole": "editor"
>         }
>       ]
>     }
>   }
> }
> ```

> [tab] Viewer
>
> ```json theme={null}
> {
>   "data": {
>     "user": {
>       "userId": "some-user-id"
>     },
>     "permissions": {
>       "resources": [
>         {
>           "type": "organization",
>           "id": "YOUR_ORGANIZATION_ID",
>           "accessRole": "viewer"
>         }
>       ]
>     }
>   }
> }
> ```

#### 2. Add permissions to a specific document within an organization

> [tab] Editor
>
> ```json theme={null}
> {
>   "data": {
>     "user": {
>       "userId": "some-user-id"
>     },
>     "permissions": {
>       "resources": [
>         {
>           "type": "document",
>           "id": "YOUR_DOCUMENT_ID",
>           "organizationId": "YOUR_ORGANIZATION_ID",
>           "accessRole": "editor",
>           "expiresAt": 1728902400
>         }
>       ]
>     }
>   }
> }
> ```

> [tab] Viewer
>
> ```json theme={null}
> {
>   "data": {
>     "user": {
>       "userId": "some-user-id"
>     },
>     "permissions": {
>       "resources": [
>         {
>           "type": "document",
>           "id": "YOUR_DOCUMENT_ID",
>           "organizationId": "YOUR_ORGANIZATION_ID",
>           "accessRole": "viewer",
>           "expiresAt": 1728902400
>         }
>       ]
>     }
>   }
> }
> ```

#### 3. Add permissions to a specific folder within an organization

> [tab] Editor
>
> ```json theme={null}
> {
>   "data": {
>     "user": {
>       "userId": "some-user-id"
>     },
>     "permissions": {
>       "resources": [
>         {
>           "type": "folder",
>           "id": "YOUR_FOLDER_ID",
>           "organizationId": "YOUR_ORGANIZATION_ID",
>           "accessRole": "editor"
>         }
>       ]
>     }
>   }
> }
> ```

> [tab] Viewer
>
> ```json theme={null}
> {
>   "data": {
>     "user": {
>       "userId": "some-user-id"
>     },
>     "permissions": {
>       "resources": [
>         {
>           "type": "folder",
>           "id": "YOUR_FOLDER_ID",
>           "organizationId": "YOUR_ORGANIZATION_ID",
>           "accessRole": "viewer"
>         }
>       ]
>     }
>   }
> }
> ```

# Response

#### Success Response

```JSON theme={null}
{
  "result": {
    "status": "success",
    "message": "Permissions added successfully."
  }
}
```

#### Failure Response

```JSON theme={null}
{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}
```

```js theme={null}
{
  "result": {
    "status": "success",
    "message": "Permissions added successfully."
  }
}
```


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