Generate auth token (v2)

Mint a JWT auth token with user identity and resource permissions using the Velt v2 REST API to securely sign in users to organizations, folders, and documents.

POST /v2/auth/generate_token

Generate Token

cURL

curl --request POST \
  --url https://api.velt.dev/v2/auth/generate_token \
  --header 'Content-Type: application/json' \
  --header 'x-velt-api-key: <x-velt-api-key>' \
  --header 'x-velt-auth-token: <x-velt-auth-token>' \
  --data '
{
  "data": {
    "userId": "<string>",
    "userProperties": {
      "isAdmin": true,
      "name": "<string>",
      "email": "<string>"
    },
    "permissions": {
      "resources": [
        {
          "type": "<string>",
          "id": "<string>",
          "organizationId": "<string>",
          "accessRole": "<string>",
          "expiresAt": 123
        }
      ]
    }
  }
}
'

import requests

url = "https://api.velt.dev/v2/auth/generate_token"

payload = { "data": {
        "userId": "<string>",
        "userProperties": {
            "isAdmin": True,
            "name": "<string>",
            "email": "<string>"
        },
        "permissions": { "resources": [
                {
                    "type": "<string>",
                    "id": "<string>",
                    "organizationId": "<string>",
                    "accessRole": "<string>",
                    "expiresAt": 123
                }
            ] }
    } }
headers = {
    "x-velt-api-key": "<x-velt-api-key>",
    "x-velt-auth-token": "<x-velt-auth-token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-velt-api-key': '<x-velt-api-key>',
    'x-velt-auth-token': '<x-velt-auth-token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    data: {
      userId: '<string>',
      userProperties: {isAdmin: true, name: '<string>', email: '<string>'},
      permissions: {
        resources: [
          {
            type: '<string>',
            id: '<string>',
            organizationId: '<string>',
            accessRole: '<string>',
            expiresAt: 123
          }
        ]
      }
    }
  })
};

fetch('https://api.velt.dev/v2/auth/generate_token', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.velt.dev/v2/auth/generate_token",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'data' => [
        'userId' => '<string>',
        'userProperties' => [
                'isAdmin' => true,
                'name' => '<string>',
                'email' => '<string>'
        ],
        'permissions' => [
                'resources' => [
                                [
                                                                'type' => '<string>',
                                                                'id' => '<string>',
                                                                'organizationId' => '<string>',
                                                                'accessRole' => '<string>',
                                                                'expiresAt' => 123
                                ]
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-velt-api-key: <x-velt-api-key>",
    "x-velt-auth-token: <x-velt-auth-token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.velt.dev/v2/auth/generate_token"

	payload := strings.NewReader("{\n  \"data\": {\n    \"userId\": \"<string>\",\n    \"userProperties\": {\n      \"isAdmin\": true,\n      \"name\": \"<string>\",\n      \"email\": \"<string>\"\n    },\n    \"permissions\": {\n      \"resources\": [\n        {\n          \"type\": \"<string>\",\n          \"id\": \"<string>\",\n          \"organizationId\": \"<string>\",\n          \"accessRole\": \"<string>\",\n          \"expiresAt\": 123\n        }\n      ]\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-velt-api-key", "<x-velt-api-key>")
	req.Header.Add("x-velt-auth-token", "<x-velt-auth-token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.velt.dev/v2/auth/generate_token")
  .header("x-velt-api-key", "<x-velt-api-key>")
  .header("x-velt-auth-token", "<x-velt-auth-token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"data\": {\n    \"userId\": \"<string>\",\n    \"userProperties\": {\n      \"isAdmin\": true,\n      \"name\": \"<string>\",\n      \"email\": \"<string>\"\n    },\n    \"permissions\": {\n      \"resources\": [\n        {\n          \"type\": \"<string>\",\n          \"id\": \"<string>\",\n          \"organizationId\": \"<string>\",\n          \"accessRole\": \"<string>\",\n          \"expiresAt\": 123\n        }\n      ]\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.velt.dev/v2/auth/generate_token")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-velt-api-key"] = '<x-velt-api-key>'
request["x-velt-auth-token"] = '<x-velt-auth-token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"data\": {\n    \"userId\": \"<string>\",\n    \"userProperties\": {\n      \"isAdmin\": true,\n      \"name\": \"<string>\",\n      \"email\": \"<string>\"\n    },\n    \"permissions\": {\n      \"resources\": [\n        {\n          \"type\": \"<string>\",\n          \"id\": \"<string>\",\n          \"organizationId\": \"<string>\",\n          \"accessRole\": \"<string>\",\n          \"expiresAt\": 123\n        }\n      ]\n    }\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "result": {
    "status": "success",
    "message": "Token generated successfully.",
    "data": {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJ1c2VyMTIzIiwiaWF0IjoxNjQwOTk1MjAwfQ.signature"
    }
  }
}

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.

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

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 for concepts and detailed guidance.

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

Body

Params

data · object · required

Show properties

userId · string · required

Unique identifier for the user.

userProperties · object · required

Show 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

Show properties

resources · Resource[] · required

Array of resource permission objects.

Show 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

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.

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)

{
  "data": {
    "userId": "user123",
    "userProperties": {
      "isAdmin": false,
      "name": "John Doe",
      "email": "[e-mail]"
    },
    "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)

{
  "data": {
    "userId": "user456",
    "userProperties": {
      "isAdmin": true,
      "name": "Jane Smith",
      "email": "[e-mail]"
    },
    "permissions": {
      "resources": [
        {
          "type": "organization",
          "id": "org_789",
          "accessRole": "viewer"
        }
      ]
    }
  }
}

3. Generate token with folder permissions (editor)

{
  "data": {
    "userId": "user789",
    "userProperties": {
      "isAdmin": false,
      "name": "Bob Wilson",
      "email": "[e-mail]"
    },
    "permissions": {
      "resources": [
        {
          "type": "organization",
          "id": "org_123"
        },
        {
          "type": "folder",
          "id": "folder_001",
          "organizationId": "org_123",
          "accessRole": "editor"
        }
      ]
    }
  }
}

Response

Success Response

{
  "result": {
    "status": "success",
    "message": "Token generated successfully.",
    "data": {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
}

Failure Response

{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}

{
  "result": {
    "status": "success",
    "message": "Token generated successfully.",
    "data": {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJ1c2VyMTIzIiwiaWF0IjoxNjQwOTk1MjAwfQ.signature"
    }
  }
}