Skip to main content
Velora local API authorization is request-based and user-approved.

​
Step 1: register your app

POST /register Required body:
  • app.name (required)
  • permissions (optional; normalized to read and write, defaults to read)
Optional app metadata:
  • app.description
  • app.developer
  • app.website
  • app.icon
app.icon validation:
  • Accepts http or https URL (up to 2048 characters)
  • Accepts data:image/*;base64,... payload (up to 1 MB)
  • Invalid icon format returns 400
curl -X POST http://127.0.0.1:39031/register \
  -H "Content-Type: application/json" \
  -d '{
    "app": {
      "name": "Game Launcher",
      "description": "Local game launcher that allows downloading and playing games",
      "developer": "CrickDevs",
      "website": "https://gamelauncher.crickdevs.com",
      "icon": "https://gamelauncher.crickdevs.com/icon.png"
    },
    "permissions": ["read", "write"]
  }'
Pending response (202): 
{
  "request_id": "req_123abc",
  "status": "pending"
}

​
Step 2: poll request status

GET /request-status?request_id=<request_id> If pending: 
{
  "request_id": "req_123abc",
  "status": "pending"
}
If approved: 
{
  "request_id": "req_123abc",
  "status": "approved",
  "access_token": "velora_...",
  "token_type": "Bearer",
  "permissions": ["read", "write"]
}
If denied: 
{
  "request_id": "req_123abc",
  "status": "denied"
}

​
Step 3: call authenticated endpoints

Authenticated calls accept either:
  • Authorization: Bearer <token>
  • ?access_token=<token> query parameter
Permissions are enforced per endpoint:
  • read: read endpoints and WebSocket
  • write: control endpoints
If the token is missing, invalid, or revoked, the API returns 401. If the app is revoked or missing required permission, the API returns 403.

​
Token lifecycle

Tokens and approved apps are persisted by the desktop app. Users can revoke or reset access from the app’s developer settings, which immediately invalidates tokens and closes active WebSocket sessions.