Skip to main content

​
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}
PrefixEnvironmentUsage
river_live_ProductionLive API calls, charged to your account
river_test_SandboxTesting, 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:
PermissionDescriptionExample
permissionsPermission object restricting key access{ "video:create": true }
ipWhitelistIP addresses allowed to use this key["203.0.113.50"]
spendLimitMaximum spend limit in USD1000
When no permissions are set, the key has full access to all providers and types.

​
Security Best Practices

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}`,
  },
});
Add .env to your .gitignore file. If a key is accidentally committed, rotate it immediately from the Dashboard.
Create separate keys for different environments and services. Scope each key to only the providers and types it needs.
Use spendLimit to cap usage per key and prevent unexpected charges.

​
Error Responses

StatusCodeDescription
401AUTH_REQUIREDNo API key provided
401AUTH_INVALID_TOKENInvalid or malformed API key
401AUTH_TOKEN_EXPIREDAPI key has expired
403KEY_PERMISSION_DENIEDKey lacks required permissions
403KEY_REVOKEDKey has been deleted