Authentication

Bearer Token Authentication

All API requests must include a valid API key in the Authorization header:

Authorization: Bearer river_live_xxxxxxxxxxxxx

API Key Format

API keys follow the pattern:

river_{environment}_{random32}

Prefix	Environment	Usage
`river_live_`	Production	Live API calls, charged to your account
`river_test_`	Sandbox	Testing, no charges incurred

Managing API Keys

Create a Key

Create API keys from the Dashboard or via the API:

curl -X POST https://api.modelhunter.ai/api/v1/api-keys \
  -H "Authorization: Bearer river_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Backend",
    "spendLimit": 1000,
    "expiresAt": "2027-01-01T00:00:00Z"
  }'

The full API key is only shown once at creation time. Store it securely — you cannot retrieve it later.

Rotate a Key

To rotate a key, create a new one, update your application, then delete the old key.

Delete a Key

curl -X DELETE https://api.modelhunter.ai/api/v1/api-keys/{key_id} \
  -H "Authorization: Bearer river_live_xxx"

Permissions

Each API key can be scoped with fine-grained permissions:

Permission	Description	Example
`permissions`	Permission object restricting key access	`{ "video:create": true }`
`ipWhitelist`	IP addresses allowed to use this key	`["203.0.113.50"]`
`spendLimit`	Maximum spend limit in USD	`1000`

When no permissions are set, the key has full access to all providers and types.

Security Best Practices

Use environment variables

Never hardcode API keys in your source code.

# .env
MODELHUNTER_KEY=river_live_xxxxxxxxxxxxx

const response = await fetch('https://api.modelhunter.ai/api/v1/...', {
  headers: {
    'Authorization': `Bearer ${process.env.MODELHUNTER_KEY}`,
  },
});

Never commit keys to Git

Add .env to your .gitignore file. If a key is accidentally committed, rotate it immediately from the Dashboard.

Use scoped keys

Create separate keys for different environments and services. Scope each key to only the providers and types it needs.

Set spend limits

Use spendLimit to cap usage per key and prevent unexpected charges.

Error Responses

Status	Code	Description
401	`AUTH_REQUIRED`	No API key provided
401	`AUTH_INVALID_TOKEN`	Invalid or malformed API key
401	`AUTH_TOKEN_EXPIRED`	API key has expired
403	`KEY_PERMISSION_DENIED`	Key lacks required permissions
403	`KEY_REVOKED`	Key has been deleted

Getting Started

Core Concepts

More

Bearer Token Authentication

API Key Format

Managing API Keys

Create a Key

Rotate a Key

Delete a Key

Permissions

Security Best Practices

Error Responses

​Bearer Token Authentication

​API Key Format

​Managing API Keys

​Create a Key

​Rotate a Key

​Delete a Key

​Permissions

​Security Best Practices

​Error Responses

Bearer Token Authentication

API Key Format

Managing API Keys

Create a Key

Rotate a Key

Delete a Key

Permissions

Security Best Practices

Error Responses