Generate Signed Auth & Refresh Tokens

This API generates signed authentication (auth_token) and refresh (refresh_token) tokens using the app's settings. The request payload allows storing custom claims such as sub (subject, typically a user ID, username, or email), aud (audience, such as web or mobile apps), ip, useragent, and any other key-value data.

Endpoint

POST /app/{app_id}/sign

Headers

Name Type Required Description
Authorization string Yes The app-key of the project.

Example Request

curl --request POST \
--url http://{{your-endpoint}}:{{your-port}}/app/{{app-id}}/sign \
--header 'Authorization: {{app-key}}' \
--header 'content-type: application/json' \
--data '{
"sub":"test@test.com",
"aud":"web-app",
"ip": "1.1.1.1",
"useragent":"my-user-agent",
"personal":{
    "name":"test-user"  
}
}'
const request = require('request');

const options = {
    method: 'POST',
    url: 'http://{{your-endpoint}}:{{your-port}}/app/{{app-id}}/sign',
    headers: {Authorization: '{{app-key}}', 'content-type': 'application/json'},
    body: {
    sub: 'test@test.com',
    aud: 'web-app',
    ip: '1.1.1.1',
    useragent: 'my-user-agent',
    personal: {name: 'test-user'}
    },
    json: true
};

request(options, function (error, response, body) {
    if (error) throw new Error(error);

    console.log(body);
});
import requests

url = "http://{{your-endpoint}}:{{your-port}}/app/{{app-id}}/sign"

payload = {
    "sub": "test@test.com",
    "aud": "web-app",
    "ip": "1.1.1.1",
    "useragent": "my-user-agent",
    "personal": { "name": "test-user" }
}
headers = {
    "Authorization": "{{app-key}}",
    "content-type": "application/json"
}

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

print(response.json())
<?php
$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'http://{{your-endpoint}}:{{your-port}}/app/{{app-id}}/sign', [
    'body' => '{
    "sub":"test@test.com",
    "aud":"web-app",
    "ip": "1.1.1.1",
    "useragent":"my-user-agent",
    "personal":{
    "name":"test-user"  
    }
}',
    'headers' => [
    'Authorization' => '{{app-key}}',
    'content-type' => 'application/json',
    ],
]);

echo $response->getBody();
package main

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

func main() {

    url := "http://{{your-endpoint}}:{{your-port}}/app/{{app-id}}/sign"

    payload := strings.NewReader("{\n  \"sub\":\"test@test.com\",\n  \"aud\":\"web-app\",\n  \"ip\": \"1.1.1.1\",\n  \"useragent\":\"my-user-agent\",\n  \"personal\":{\n    \"name\":\"test-user\"  \n  }\n}")

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

    req.Header.Add("Authorization", "{{app-key}}")
    req.Header.Add("content-type", "application/json")

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

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

    fmt.Println(res)
    fmt.Println(string(body))

}
AsyncHttpClient client = new DefaultAsyncHttpClient();
client.prepare("POST", "http://{{your-endpoint}}:{{your-port}}/app/{{app-id}}/sign")
    .setHeader("Authorization", "{{app-key}}")
    .setHeader("content-type", "application/json")
    .setBody("{\n  \"sub\":\"test@test.com\",\n  \"aud\":\"web-app\",\n  \"ip\": \"1.1.1.1\",\n  \"useragent\":\"my-user-agent\",\n  \"personal\":{\n    \"name\":\"test-user\"  \n  }\n}")
    .execute()
    .toCompletableFuture()
    .thenAccept(System.out::println)
    .join();

client.close();

Request Fields

Field Type Required Description
sub string Yes Subject (User identifier such as email, username, or user ID).
aud string Yes Audience requesting the JWT (e.g., web-app, mobile-app).
ip string Yes IP address of the user performing the login.
useragent string Yes User agent of the request origin.
... key-value / object No Any additional key-value data or nested key-value data to be stored inside the JWT.

Example Success Response

{
"auth_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IjAxSk1WMjhGSlZCS0YwSkcwWVNHNjU1RUhZIiwidHlwIjoiSldUIn0.eyJhdWQiOiJ3ZWItYXBwIiwiZXhwIjoxNzQwNDI2ODg5LCJpYXQiOjE3NDA0MjMyODksImlwIjoiMS4xLjEuMSIsImlzcyI6ImFwcF8yIiwiamlkIjoiMDFKTVdNWlBFWFpLOEtLQkUxSllCQUdCOVYiLCJuYmYiOjE3NDA0MjMyODksInBlcnNvbmFsIjp7Im5hbWUiOiJ0ZXN0LXVzZXIifSwic3ViIjoidGVzdEB0ZXN0LmNvbSIsInVzZXJhZ2VudCI6Im15LXVzZXItYWdlbnQifQ.OY8tCesz-VlIg0kUeCEmKmpWVQ_bxfUEIMa0dZEfNM7x_6z139E8Of4hrffyRCmR3icsuIW5ICvj5QI2aD0I2g",
"key_id": "01JMV28FJVBKF0JG0YSG655EHY",
"public_key": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZrd0V3WUhLb1pJemowQ0FRWUlLb1pJemowREFRY0RRZ0FFOWpkd1JWSTFTT2RsNGJDNkd5MHRycUVNc01DNQo2NW9VK3ltV2MvQ09JUTJlM0tkNGwvNkoweUlUMTFnT25UdERhOGdudXZKZ1JKc2JXNWQxZkMzUk5BPT0KLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0tCg==",
"refresh_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IjAxSk1WMjhGSlZCS0YwSkcwWVNHNjU1RUhZIiwidHlwIjoiSldUIn0.eyJleHAiOjE3NDA0MjQzNjksImlhdCI6MTc0MDQyMzI4OSwiaXNzIjoiYXBwXzIiLCJqaWQiOiIwMUpNV01aUEVYWks4S0tCRTFKWUJBR0I5ViIsIm5iZiI6MTc0MDQyNjI4OSwidHlwZSI6InJlZnJlc2gifQ.7P06dQev1xxEUg1XxkIx0yX4eSWrtuwuGAhaAGIUGRauJjWNb4F6OMEzWQtCwu_3sdW7vULZTgvAhzTXIr9hPg"
}

Response Fields

Field Type Description
auth_token string Signed JWT authentication token.
key_id string (ULID) A unique identifier of the public-private key pair was used for the signing.
public_key string Base64-encoded public key, can be use for frontend JWT verification.
refresh_token string enum (RSA,ECDSA) Signed JWT refresh token for session renewal.

Responses

Status Code Description
200 Ok Success
400 Bad Request Mostly when the form validation fails. The error will be returned as a response.
403 Access Denied When the provided app key in Authorization header is invalid.
500 Internal Server Error Mostly because of the database error. Check the log for root cause details.