Generate auth signature (v2)

Generate a server-side signed payload signature using the Velt v2 REST API to securely authenticate end-user identity claims sent from your backend.

POST /v2/auth/generate_signature

Generate Signature

cURL

curl --request POST \
  --url https://api.velt.dev/v2/auth/generate_signature \
  --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": {
    "permissions": [
      {
        "userId": "<string>",
        "resourceId": "<string>",
        "type": "<string>",
        "hasAccess": true,
        "accessRole": "<string>",
        "expiresAt": 123
      }
    ]
  }
}
'

import requests

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

payload = { "data": { "permissions": [
            {
                "userId": "<string>",
                "resourceId": "<string>",
                "type": "<string>",
                "hasAccess": True,
                "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: {
      permissions: [
        {
          userId: '<string>',
          resourceId: '<string>',
          type: '<string>',
          hasAccess: true,
          accessRole: '<string>',
          expiresAt: 123
        }
      ]
    }
  })
};

fetch('https://api.velt.dev/v2/auth/generate_signature', 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_signature",
  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' => [
        'permissions' => [
                [
                                'userId' => '<string>',
                                'resourceId' => '<string>',
                                'type' => '<string>',
                                'hasAccess' => true,
                                '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_signature"

	payload := strings.NewReader("{\n  \"data\": {\n    \"permissions\": [\n      {\n        \"userId\": \"<string>\",\n        \"resourceId\": \"<string>\",\n        \"type\": \"<string>\",\n        \"hasAccess\": true,\n        \"accessRole\": \"<string>\",\n        \"expiresAt\": 123\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_signature")
  .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    \"permissions\": [\n      {\n        \"userId\": \"<string>\",\n        \"resourceId\": \"<string>\",\n        \"type\": \"<string>\",\n        \"hasAccess\": true,\n        \"accessRole\": \"<string>\",\n        \"expiresAt\": 123\n      }\n    ]\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

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

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    \"permissions\": [\n      {\n        \"userId\": \"<string>\",\n        \"resourceId\": \"<string>\",\n        \"type\": \"<string>\",\n        \"hasAccess\": true,\n        \"accessRole\": \"<string>\",\n        \"expiresAt\": 123\n      }\n    ]\n  }\n}"

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

{
  "result": {
    "status": "success",
    "message": "Signature generated successfully.",
    "data": {
      "signature": "a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890"
    }
  }
}

Use this API to generate a secure signature for Permission Provider responses. The signature validates the integrity of permission decisions returned from your authorization service.

Security Critical: This endpoint must be called from your backend server, never from client-side code. The signature ensures that permission responses haven’t been tampered with.

Permission Provider Integration

This API is used in conjunction with the Permission Provider configuration mode. When implementing your backend Permission Provider endpoint, use this endpoint to generate a secure signature for your permission response.

Endpoint

POST https://api.velt.dev/v2/auth/generate_signature

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

permissions · PermissionData[] · required

Array of permission decisions to sign. Each object must include user ID, resource information, access decision, and optional role/expiration.

Show PermissionData Object Properties

userId · string · required

ID of the user this permission applies to.

resourceId · string · required

ID of the resource (document, folder, or organization).

type · string · required

Type of the resource. Allowed values: "document" | "folder" | "organization".

hasAccess · boolean · required

Whether the user has access to the resource.

accessRole · string

Access role for the user. Only applicable for document resources. Allowed values: "viewer" | "editor". viewer can view and comment, editor can edit content.

expiresAt · number

UTC timestamp in milliseconds when this permission expires. Velt will revalidate access after expiration.

Example Requests

1. Generate signature for document access with viewer role and expiration

{
  "data": {
    "permissions": [
      {
        "userId": "user123",
        "resourceId": "document456",
        "type": "document",
        "hasAccess": true,
        "accessRole": "viewer",
        "expiresAt": 1759745729823
      }
    ]
  }
}

2. Generate signature for multiple resources (organization and folder)

{
  "data": {
    "permissions": [
      {
        "userId": "user123",
        "resourceId": "org789",
        "type": "organization",
        "hasAccess": true
      },
      {
        "userId": "user123",
        "resourceId": "folder101",
        "type": "folder",
        "hasAccess": true
      }
    ]
  }
}

3. Generate signature denying access

{
  "data": {
    "permissions": [
      {
        "userId": "user456",
        "resourceId": "document789",
        "type": "document",
        "hasAccess": false
      }
    ]
  }
}

4. Generate signature for document with editor role

{
  "data": {
    "permissions": [
      {
        "userId": "user789",
        "resourceId": "document123",
        "type": "document",
        "hasAccess": true,
        "accessRole": "editor"
      }
    ]
  }
}

5. Generate signature for document with viewer role

{
  "data": {
    "permissions": [
      {
        "userId": "user456",
        "resourceId": "document123",
        "type": "document",
        "hasAccess": true,
        "accessRole": "viewer"
      }
    ]
  }
}

Response

Success Response

{
  "result": {
    "status": "success",
    "message": "Signature generated successfully.",
    "data": {
      "signature": "a1b2c3d4e5f6..."
    }
  }
}

Failure Response

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

{
  "result": {
    "status": "success",
    "message": "Signature generated successfully.",
    "data": {
      "signature": "a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890"
    }
  }
}