# API

ArtLight Server has a RESTful API which can be used to interact with the service.

Unless otherwise specified, authentication is required for all API calls. You can authenticate using either basic authentication with the admin username and password, or with an API token that provides fine-grained access control.

## CSRF Protection

State-changing API endpoints (POST, DELETE) are protected against Cross-Site Request Forgery (CSRF) attacks.

**For Web Browsers:**
- Requests from same-origin (configured via `csrf_allowed_origins`) are automatically allowed
- Cross-origin requests require a CSRF token

**For Non-Browser Applications:**
- Non-browser clients (for example `curl`, scripts, or custom apps) are exempt from CSRF protection
- CSRF attacks require a browser to silently attach credentials to a cross-origin request; this threat does not apply to non-browser clients that explicitly provide credentials with every request
- Requests with no `Origin` or `Referer` header are automatically allowed without a CSRF token

**Example:**
```bash
curl -u user:pass https://localhost:47990/api/csrf-token
curl -u user:pass -H "X-CSRF-Token: your_token_here" \
  -X POST https://localhost:47990/api/restart
```

@htmlonly
<script src="api.js"></script>
@endhtmlonly

## API Token Security Model and Best Practices

ArtLight Server API tokens are designed for security and fine-grained access control:

- **Token Creation:** When you generate an API token, ArtLight Server creates a secure random 32-character string. Only a cryptographic hash of the token is stored on disk and in memory. The raw token is shown to you only once—immediately after creation. If you lose it, you must generate a new token.
- **Security:** Because only the hash is stored, even if the state file is compromised, attackers cannot recover the original token value.
- **Principle of Least Privilege:** When creating a token, always grant access only to the specific API paths and HTTP methods required for your use case. Avoid giving broad or unnecessary permissions.
- **Token Management:**
  - Store your token securely after creation. Never share or log it.
  - Revoke tokens immediately if they are no longer needed or if you suspect they are compromised.
  - Use HTTPS to protect tokens in transit.
- **Listing and Revocation:** You can list all active tokens (metadata only, not the token value) and revoke any token at any time using the API.

API Tokens can also be managed in the Web UI under the "API Token" tab in the navigation bar.

See below for details on token endpoints and usage examples.

## GET /api/csrf-token
@copydoc confighttp::getCSRFToken()

## GET /api/apps
@copydoc confighttp::getApps()

## POST /api/apps
@copydoc confighttp::saveApp()

## POST /api/apps/close
@copydoc confighttp::closeApp()

## DELETE /api/apps/{index}
@copydoc confighttp::deleteApp()

## GET /api/clients/list
@copydoc confighttp::getClients()

## POST /api/clients/unpair
@copydoc confighttp::unpair()

## POST /api/clients/unpair-all
@copydoc confighttp::unpairAll()

## GET /api/config
@copydoc confighttp::getConfig()


## GET /api/configLocale
@copydoc confighttp::getLocale()

## POST /api/config
@copydoc confighttp::saveConfig()

## GET /api/covers/{index}
@copydoc confighttp::getCover()

## POST /api/covers/upload
@copydoc confighttp::uploadCover()

## GET /api/logs
@copydoc confighttp::getLogs()

- Returns the most recent session log from the managed `logs` folder (ArtLight Server keeps the last 30 sessions, with each session capped at about 10 MiB by rolling ~2MB log files).

## GET /api/logs/export
Downloads a ZIP archive containing logs useful for troubleshooting (Windows only).

- Includes: Sunshine session logs (current and up to 29 previous sessions, including rollovers), Playnite logs (`playnite.log`, `extensions.log`, `launcher.log`), Sunshine Playnite plugin logs (`sunshine_playnite-*.log*` and legacy `sunshine_playnite.log`), launcher helper logs (`sunshine_playnite_launcher-*.log*` / `sunshine_launcher-*.log*` and legacy `sunshine_playnite_launcher.log` / `sunshine_launcher.log`), display helper logs (`sunshine_display_helper-*.log*` and legacy `sunshine_display_helper.log`), and WGC helper logs (`sunshine_wgc_helper-*.log*` and legacy `sunshine_wgc_helper.log`) when present.
- Requires authentication.

## POST /api/password
@copydoc confighttp::savePassword()

## POST /api/pin
@copydoc confighttp::savePin()

## POST /api/reset-display-device-persistence
@copydoc confighttp::resetDisplayDevicePersistence()

## POST /api/restart
@copydoc confighttp::restart()

## Authentication

All API calls require authentication. You can use either:
- **Basic Authentication**: Use your admin username and password.
- **API Token (recommended for automation)**: Use a generated token with fine-grained access control.

### Generating an API Token

**POST /api/token**

Authenticate with Basic Auth. The request body should specify the allowed API paths and HTTP methods for the token:

```json
{
  "scopes": [
    { "path": "/api/apps", "methods": ["GET", "POST"] },
    { "path": "/api/logs", "methods": ["GET"] }
  ]
}
```

**Response:**
```json
{ "token": "...your-new-token..." }
```
> The token is only shown once. Store it securely.

### Using an API Token

Send the token in the `Authorization` header:
```
Authorization: Bearer <token>
```

The token grants access only to the specified paths and HTTP methods.

### Managing API Tokens

- **List tokens:** `GET /api/tokens` (shows metadata, not token values)
- **Revoke token:** `DELETE /api/token/{hash}`

### Managing Remembered Sessions

- **Stay signed in:** Include an optional `"remember_me": true` flag in the JSON body when calling `POST /api/auth/login`. ArtLight Server will issue a hardened `__Host-` cookie with an extended lifetime.
- **Refresh silently:** `POST /api/auth/refresh` rotates the short-lived session token using the HttpOnly refresh cookie. The response sets fresh cookies and also returns the new access token in the JSON payload.
- **List active sessions:** `GET /api/auth/sessions` returns all devices that currently hold a valid ArtLight Server session cookie. Each entry includes creation time, last activity, expiry, remote address, and whether it was a “remember me” session.
- **Revoke a specific session:** `DELETE /api/auth/sessions/{hash}` immediately removes the matching session from disk. If the current device is revoked, its cookie is cleared and the browser must sign in again.

All session metadata is stored hashed and persisted in the same state file as API tokens so ArtLight Server can validate cookies across service restarts.

## GET /api/vigembus/status
@copydoc confighttp::getViGEmBusStatus()

## POST /api/vigembus/install
@copydoc confighttp::installViGEmBus()

<div class="section_buttons">

| Previous                                    |                                  Next |
|:--------------------------------------------|--------------------------------------:|
| [Performance Tuning](performance_tuning.md) | [Troubleshooting](troubleshooting.md) |

</div>

<details style="display: none;">
  <summary></summary>
  [TOC]
</details>

### Host readiness metadata

`GET /api/metadata` includes optional status fields for the v2 interface. Existing fields
and configuration write formats remain compatible.

- `encoder_status`: `state` (`ready`, `failed`, or `unknown`) and `h264`, `hevc`, `av1`
  support from the current encoder-probe cache. Reading metadata never initiates a probe.
- Provider actions are shown only when the corresponding `providers` capability is explicitly
  true. Missing Steam, Lutris, MangoHUD, and Playnite-toggle capabilities mean unavailable.
- Linux `linux.session_role`: `desktop`, `greeter`, or `unknown`.
- Linux `virtual_display.reason`: empty when ready; otherwise
  `driver_or_outputs_unavailable` or `session_or_output_unavailable`.
- Linux `capture_status`: `configured_backend`, `virtual_display_configured`,
  `observed_backend`, and `managed_event_driven`. An observed `kms` backend with
  `managed_event_driven: true` means a managed presentation-event capture loop is currently
  running. Outside that capture lifetime the observed backend is `unknown`. This does not
  claim that another backend is unavailable or that a configured capture path was verified.

Clients must tolerate absent status fields from older hosts and distinguish unknown status
from verified readiness. Virtual-display readiness is not required for physical capture.