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

# Add Permissions

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

<Info>
  * 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.
</Info>

<Info>
  **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](/key-concepts/overview#access-control) for concepts and detailed guidance.
</Info>

# Endpoint

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

# Headers

<ParamField header="x-velt-api-key" type="string" required>
  Your API key.
</ParamField>

<ParamField header="x-velt-auth-token" type="string" required>
  Your [Auth Token](/security/auth-tokens).
</ParamField>

# Body

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="user" type="object" required>
      <Expandable title="properties">
        <ParamField body="userId" type="string" required>
          The ID of the user to add permissions to.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="permissions" type="object" required>
      <Expandable title="properties">
        <ParamField body="resources" type="object[]" required>
          Array of resource objects to grant permissions for.

          <Expandable title="Resource Object">
            <ParamField body="type" type="string" required>
              The type of resource. Can be `organization`, `document` or `folder`.
            </ParamField>

            <ParamField body="id" type="string" required>
              The ID of the resource.
            </ParamField>

            <ParamField body="organizationId" type="string">
              The ID of the organization. Required if `type` is `document` or `folder`.
            </ParamField>

            <ParamField body="accessRole" type="string">
              Optional access role for this resource. Allowed values: “viewer” | “editor”. Default: "editor".
            </ParamField>

            <ParamField body="expiresAt" type="number">
              A Unix timestamp (in seconds) that specifies when the permission should expire. This is optional.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## **Example Requests**

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

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

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

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

<Tabs>
  <Tab title="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>

  <Tab title="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
            }
          ]
        }
      }
    }
    ```
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="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>

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

# 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"
  }
}
```

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