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

> [!NOTE]
>
> Within `permissions.resources[]`, use `accessRole` to assign `viewer` (read-only) or `editor` (read/write) for each resource.

> [!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.

> [!NOTE]
>
> * JWT token expires in 48 hours.
> * You can specify permissions for different resource types (organization, folder, document)

# Endpoint

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

# 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

#### Params

**data** `object` *required*

**properties**

**userId** `string` *required*

Unique identifier for the user.

**userProperties** `object` *required*

**properties**

**isAdmin** `boolean`

Whether the user has admin privileges. Defaults to false.

**name** `string` *required*

Display name of the user.

**email** `string` *required*

Email address of the user.

**permissions** `object` *required*

**properties**

**resources** `Resource[]` *required*

Array of resource permission objects.

**Resource Object Properties**

**type** `string` *required*

Type of resource. Can be "organization", "document", or "folder".

**id** `string` *required*

ID of the resource.

**organizationId** `string`

Organization ID. Required when type is "document" or "folder".

**accessRole** `string`

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

**expiresAt** `number`

Unix timestamp when the permission expires. Optional.

## **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]
>
> `organizationId` does **not** belong in `userProperties`. It must be provided as a resource entry in `permissions.resources[]` with `type: "organization"`.

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

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


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