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

# Generate Token

Use this API to generate authentication JWT token for users to access Velt features. The token contains user information and permissions for specific resources like organizations, folders and documents.

<Info>
  Within `permissions.resources[]`, use `accessRole` to assign `viewer` (read-only) or `editor` (read/write) for each resource.
</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>

<Info>
  * JWT token expires in 48 hours.
  * You can specify permissions for different resource types (organization, folder, document)
</Info>

# Endpoint

`POST https://api.velt.dev/v2/auth/generate_token`

# 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

#### Params

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="userId" type="string" required>
      Unique identifier for the user.
    </ParamField>

    <ParamField body="userProperties" type="object" required>
      <Expandable title="properties">
        <ParamField body="isAdmin" type="boolean">
          Whether the user has admin privileges. Defaults to false.
        </ParamField>

        <ParamField body="name" type="string" required>
          Display name of the user.
        </ParamField>

        <ParamField body="email" type="string" required>
          Email address of the user.
        </ParamField>
      </Expandable>
    </ParamField>

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

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

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

            <ParamField body="organizationId" type="string">
              Organization ID. Required when 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">
              Unix timestamp when the permission expires. Optional.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## **Example Requests**

<Warning>
  The request body must be wrapped in a top-level `data` object (matching the rest of the REST API surface). Posting the unwrapped object returns `INVALID_ARGUMENT`.
</Warning>

<Warning>
  `organizationId` does **not** belong in `userProperties`. It must be provided as a resource entry in `permissions.resources[]` with `type: "organization"`.
</Warning>

#### 1. Generate token with organization and document permissions (viewer on org, editor on document)

```JSON theme={null}
{
  "data": {
    "userId": "user123",
    "userProperties": {
      "isAdmin": false,
      "name": "John Doe",
      "email": "john@example.com"
    },
    "permissions": {
      "resources": [
        {
          "type": "organization",
          "id": "org_123",
          "accessRole": "viewer"
        },
        {
          "type": "document",
          "id": "doc_456",
          "organizationId": "org_123",
          "accessRole": "editor",
          "expiresAt": 1640995200
        }
      ]
    }
  }
}
```

#### 2. Generate token with only organization access (viewer)

```JSON theme={null}
{
  "data": {
    "userId": "user456",
    "userProperties": {
      "isAdmin": true,
      "name": "Jane Smith",
      "email": "jane@example.com"
    },
    "permissions": {
      "resources": [
        {
          "type": "organization",
          "id": "org_789",
          "accessRole": "viewer"
        }
      ]
    }
  }
}
```

#### 3. Generate token with folder permissions (editor)

```JSON theme={null}
{
  "data": {
    "userId": "user789",
    "userProperties": {
      "isAdmin": false,
      "name": "Bob Wilson",
      "email": "bob@example.com"
    },
    "permissions": {
      "resources": [
        {
          "type": "organization",
          "id": "org_123"
        },
        {
          "type": "folder",
          "id": "folder_001",
          "organizationId": "org_123",
          "accessRole": "editor"
        }
      ]
    }
  }
}
```

# Response

#### Success Response

```JSON theme={null}
{
  "result": {
    "status": "success",
    "message": "Token generated successfully.",
    "data": {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
}
```

#### Failure Response

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

<ResponseExample>
  ```js theme={null}
  {
    "result": {
      "status": "success",
      "message": "Token generated successfully.",
      "data": {
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJ1c2VyMTIzIiwiaWF0IjoxNjQwOTk1MjAwfQ.signature"
      }
    }
  }
  ```
</ResponseExample>