> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velora.crickdevs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authorization flow

> Registration, consent, request status polling, token usage, and permission rules for the Velora local API.

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`

```bash theme={null}
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`):

```json theme={null}
{
  "request_id": "req_123abc",
  "status": "pending"
}
```

## Step 2: poll request status

`GET /request-status?request_id=<request_id>`

If pending:

```json theme={null}
{
  "request_id": "req_123abc",
  "status": "pending"
}
```

If approved:

```json theme={null}
{
  "request_id": "req_123abc",
  "status": "approved",
  "access_token": "velora_...",
  "token_type": "Bearer",
  "permissions": ["read", "write"]
}
```

If denied:

```json theme={null}
{
  "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.