Authentication
Authenticate API requests using Bearer tokens with scoped API keys.
Overview
The ReadyRaider API uses API key authentication. Every request must include a valid API key in the Authorization header as a Bearer token.
Authorization: Bearer rr_live_your_api_key_hereAPI Key Format
ReadyRaider API keys follow a consistent format for easy identification:
rr_live_{64 hex characters}Prefix: rr_live_
Identifies this as a ReadyRaider production API key.
Random Part: 64 cryptographically random hex characters
Generated using a secure random number generator (256 bits of entropy).
Security Model
API keys are designed with security as a priority:
Hashed Storage
Keys are hashed with SHA-256 before storage. ReadyRaider never stores your raw API key. This means if our database were ever compromised, your keys cannot be recovered.
One-Time Display
The full API key is only shown once when created. Copy and store it securely immediately. It cannot be retrieved again.
Prefix Identification
Each key stores its first 12 characters as a prefix for identification. This lets you identify which key is which without exposing the full key.
Instant Revocation
Keys can be revoked at any time. Revoked keys are immediately rejected by the API. Revocation is a soft-delete for audit trail purposes.
Danger
Creating an API Key
You can create API keys through the web interface or via the API itself.
Via the API
curl -X POST https://readyraider.com/api/v1/me/api-keys \
-H "Authorization: Bearer rr_live_your_existing_key" \
-H "Content-Type: application/json" \
-d '{
"name": "My Discord Bot",
"permissions": ["tournaments:read", "leagues:read"],
"expires_at": "2027-01-01T00:00:00Z"
}'Request Body
| Parameter | Type | Description |
|---|---|---|
name | string | A descriptive name for this key (1-100 characters) |
permissions | string[] | Array of permission scopes to grant |
expires_at | string | ISO 8601 expiration date. Omit for non-expiring keys |
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "My Discord Bot",
"key_prefix": "rr_live_abc1",
"key": "rr_live_abc123def456...",
"permissions": ["tournaments:read", "leagues:read"],
"created_at": "2026-02-13T10:00:00Z",
"expires_at": "2027-01-01T00:00:00Z"
}
}Warning
key field is only included in the creation response. Store it immediately — you won't be able to see it again.Permission Scopes
Each API key is granted one or more scopes that control which endpoints it can access. A request to an endpoint that requires a scope not granted to the key will return a 403 Forbidden error.
Granular Scopes
| Scope | Access |
|---|---|
tournaments:read | Read tournaments, participants, brackets, matches |
tournaments:write | Create and manage tournaments (future) |
leagues:read | Read leagues, seasons, standings |
leagues:write | Create and manage leagues (future) |
organizations:read | Read organization profiles |
organizations:write | Manage organizations (future) |
raids:read | Read raids for your organizations |
raids:write | Create and manage raids (future) |
profiles:read | Read your profile and list API keys |
profiles:write | Create and revoke API keys |
Shorthand Aliases
For convenience, you can use shorthand aliases that expand to multiple scopes:
| Alias | Expands To |
|---|---|
read | All :read scopes |
write | All :write scopes |
Tip
tournaments:read.Authentication Errors
When authentication fails, the API returns one of these error responses:
401 Missing or Invalid Key
{
"error": {
"code": "unauthorized",
"message": "Missing or invalid API key",
"details": []
}
}401 Expired Key
{
"error": {
"code": "unauthorized",
"message": "API key has expired",
"details": []
}
}403 Insufficient Scope
{
"error": {
"code": "forbidden",
"message": "API key lacks required scope: tournaments:read",
"details": []
}
}Key Limits
| Limit | Value |
|---|---|
| Max active keys per account | 10 |
| Key name length | 1 – 100 characters |
| Min scopes per key | 1 |