Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/rivenmedia/riven/llms.txt

Use this file to discover all available pages before exploring further.

Every Riven API endpoint (except GET /api/v1/) requires a valid API key. The key is stored in AppModel.api_key inside Riven’s settings file and is checked on every incoming request. You can generate a new key at any time without restarting the server.

​
How authentication works

Riven’s resolve_api_key dependency accepts a key through any one of three mechanisms and rejects the request with 401 Unauthorized if none of them supply the correct value.
MethodWhere to send the key
x-api-key headerx-api-key: YOUR_KEY
Bearer tokenAuthorization: Bearer YOUR_KEY
Query parameter?api_key=YOUR_KEY
WebSocket connections only support the query-parameter method (?api_key=YOUR_KEY) because browser WebSocket APIs cannot set arbitrary headers.

​
x-api-key header

The simplest and most common method for server-to-server calls. 
curl http://localhost:8080/api/v1/health \
  -H "x-api-key: YOUR_KEY"

​
Bearer token

Standard OAuth-style Authorization header — convenient when your HTTP client already handles Bearer auth. 
curl http://localhost:8080/api/v1/health \
  -H "Authorization: Bearer YOUR_KEY"

​
Query parameter

Useful in browser contexts or when configuring webhooks that don’t support custom headers. 
curl "http://localhost:8080/api/v1/health?api_key=YOUR_KEY"

​
WebSocket

WebSocket connections authenticate exclusively via the api_key query parameter. 
ws://localhost:8080/api/v1/ws/logging?api_key=YOUR_KEY

​
Generating a new API key

Send a POST request to /api/v1/generateapikey. Riven generates a cryptographically random key, persists it to the settings file, and returns it in the response. The old key is immediately invalidated. 
curl -X POST http://localhost:8080/api/v1/generateapikey \
  -H "x-api-key: YOUR_CURRENT_KEY"
Response 
{
  "message": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
The value in message is your new API key. Update every client that uses the old key before making further requests.

​
Error responses

When authentication fails, Riven returns 401 Unauthorized with a JSON body: 
{
  "detail": "Invalid authentication credentials"
}
This error is returned when:
  • No API key is present in the request.
  • The provided key does not match the stored key.
  • A WebSocket connection supplies an incorrect api_key query parameter.

​
Security recommendations

  • Store your API key in an environment variable or secrets manager — never hard-code it in source control.
  • Use the x-api-key header (not the query parameter) for server-side calls so the key does not appear in server access logs.
  • Rotate the key immediately via POST /api/v1/generateapikey if it is ever exposed.
  • Restrict network access to port 8080 to trusted hosts at the firewall level; the API does not implement rate limiting.

Build docs developers (and LLMs) love

Get started for freeTalk to us