API Keys

API keys authenticate your application with the Rhumby API. Keys are scoped to specific operations and belong to your user account.

Key Format

All API keys have the prefix rhb_ followed by a random string:

rhb_sk_1a2b3c4d5e6f7g8h9i0j

API keys are shown only once upon creation. Save them securely immediately. They cannot be retrieved later.

Scopes

API keys support granular scopes to limit access:

read — View events, results, standings (default)
write — Create and update events, results
register — Submit registrations on behalf of users
results — Submit race results and scoring data
admin — Full access including webhooks and embed tokens

You can assign multiple scopes to a single key.

Endpoints

GET/api/v1/keys

List your API keys

POST/api/v1/keys

Create a new API key

DELETE/api/v1/keys?id=:id

Revoke an API key

List API Keys

Retrieve all active API keys for your account. Revoked keys are not returned.

GET /api/v1/keys

Example Request

curl "https://rhumby.com/api/v1/keys" \
  -H "Cookie: session=..."

This endpoint requires session authentication (logged in via web app). It does not accept API key authentication.

Example Response

{
  "data": [
    {
      "id": "key_abc123",
      "name": "Production API Key",
      "keyPrefix": "rhb_sk_1a2b3c",
      "scopes": ["read", "write"],
      "rateLimit": 1000,
      "lastUsedAt": "2026-03-29T10:30:00Z",
      "expiresAt": null,
      "createdAt": "2026-01-15T09:00:00Z"
    },
    {
      "id": "key_def456",
      "name": "Results Upload Key",
      "keyPrefix": "rhb_sk_7x8y9z",
      "scopes": ["results"],
      "rateLimit": 1000,
      "lastUsedAt": "2026-03-28T18:45:00Z",
      "expiresAt": "2027-01-15T09:00:00Z",
      "createdAt": "2026-01-20T14:30:00Z"
    }
  ]
}

Parameter	Type	Required	Description
`id`	`string`	No	Unique key identifier
`name`	`string`	No	Human-readable key name
`keyPrefix`	`string`	No	First 14 characters of the key for identification (e.g., "rhb_sk_1a2b3c")
`scopes`	`array`	No	Array of granted scopes
`rateLimit`	`number`	No	Requests per hour (default: 1000)
`lastUsedAt`	`string`	No	ISO 8601 timestamp of last API call using this key (null if never used)
`expiresAt`	`string`	No	ISO 8601 expiration timestamp (null if no expiration)
`createdAt`	`string`	No	ISO 8601 timestamp of key creation

Create API Key

Generate a new API key with specified scopes and optional expiration.

POST /api/v1/keys

Request Body

Parameter	Type	Required	Description
`name`	`string`	Yes	Human-readable name for the key (max 100 characters)
`scopes`	`array`	No	Array of scopes to grant (default: ["read"])
`expiresInDays`	`number`	No	Number of days until expiration (1-365, default: never expires)

Example Request

curl -X POST "https://rhumby.com/api/v1/keys" \
  -H "Cookie: session=..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key",
    "scopes": ["read", "write", "results"],
    "expiresInDays": 365
  }'

Example Response

{
  "data": {
    "id": "key_abc123",
    "name": "Production API Key",
    "keyPrefix": "rhb_sk_1a2b3c",
    "scopes": ["read", "write", "results"],
    "expiresAt": "2027-03-29T16:00:00Z",
    "createdAt": "2026-03-29T16:00:00Z",
    "apiKey": "rhb_sk_1a2b3c4d5e6f7g8h9i0j"
  },
  "message": "Save this API key now — it won't be shown again."
}

The full apiKey value is returned only in this response. Store it securely. You cannot retrieve it later.

Revoke API Key

Permanently revoke an API key. Revoked keys cannot be reactivated.

DELETE /api/v1/keys?id=:id

Query Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	The key ID to revoke

Example Request

curl -X DELETE "https://rhumby.com/api/v1/keys?id=key_abc123" \
  -H "Cookie: session=..."

Example Response

{
  "message": "API key revoked"
}

Revoking a key takes effect immediately. Any in-flight requests using that key will fail on the next API call.

Best Practices

Security

Never commit keys to version control. Use environment variables or secret managers.
Rotate keys regularly, especially for production services (every 90-365 days).
Use minimal scopes. Grant only the permissions your application needs.
Revoke unused keys immediately to reduce attack surface.

Development Workflow

Separate keys for dev/staging/prod. Use different keys per environment.
Name keys descriptively. Include environment and purpose (e.g., "Production Results Upload").
Monitor lastUsedAt. Identify and revoke stale keys that haven't been used in months.

Rate Limiting

All API keys default to 1,000 requests/hour. If you exceed this limit, requests return 429 Too Many Requests. Contact support for higher limits if needed.

Authentication Guide — How to use API keys in requests
Webhooks — Subscribe to real-time event notifications (requires admin scope)
Embed Tokens — Generate tokens for public widget embeds (requires organization membership)

API Keys

API keys authenticate your application with the Rhumby API. Keys are scoped to specific operations and belong to your user account.

Key Format

All API keys have the prefix rhb_ followed by a random string:

rhb_sk_1a2b3c4d5e6f7g8h9i0j

API keys are shown only once upon creation. Save them securely immediately. They cannot be retrieved later.

Scopes

API keys support granular scopes to limit access:

read — View events, results, standings (default)
write — Create and update events, results
register — Submit registrations on behalf of users
results — Submit race results and scoring data
admin — Full access including webhooks and embed tokens

You can assign multiple scopes to a single key.

Endpoints

GET/api/v1/keys

List your API keys

POST/api/v1/keys

Create a new API key

DELETE/api/v1/keys?id=:id

Revoke an API key

List API Keys

Retrieve all active API keys for your account. Revoked keys are not returned.

GET /api/v1/keys

Example Request

curl "https://rhumby.com/api/v1/keys" \
  -H "Cookie: session=..."

This endpoint requires session authentication (logged in via web app). It does not accept API key authentication.

Example Response

{
  "data": [
    {
      "id": "key_abc123",
      "name": "Production API Key",
      "keyPrefix": "rhb_sk_1a2b3c",
      "scopes": ["read", "write"],
      "rateLimit": 1000,
      "lastUsedAt": "2026-03-29T10:30:00Z",
      "expiresAt": null,
      "createdAt": "2026-01-15T09:00:00Z"
    },
    {
      "id": "key_def456",
      "name": "Results Upload Key",
      "keyPrefix": "rhb_sk_7x8y9z",
      "scopes": ["results"],
      "rateLimit": 1000,
      "lastUsedAt": "2026-03-28T18:45:00Z",
      "expiresAt": "2027-01-15T09:00:00Z",
      "createdAt": "2026-01-20T14:30:00Z"
    }
  ]
}

Parameter	Type	Required	Description
`id`	`string`	No	Unique key identifier
`name`	`string`	No	Human-readable key name
`keyPrefix`	`string`	No	First 14 characters of the key for identification (e.g., "rhb_sk_1a2b3c")
`scopes`	`array`	No	Array of granted scopes
`rateLimit`	`number`	No	Requests per hour (default: 1000)
`lastUsedAt`	`string`	No	ISO 8601 timestamp of last API call using this key (null if never used)
`expiresAt`	`string`	No	ISO 8601 expiration timestamp (null if no expiration)
`createdAt`	`string`	No	ISO 8601 timestamp of key creation

Create API Key

Generate a new API key with specified scopes and optional expiration.

POST /api/v1/keys

Request Body

Parameter	Type	Required	Description
`name`	`string`	Yes	Human-readable name for the key (max 100 characters)
`scopes`	`array`	No	Array of scopes to grant (default: ["read"])
`expiresInDays`	`number`	No	Number of days until expiration (1-365, default: never expires)

Example Request

curl -X POST "https://rhumby.com/api/v1/keys" \
  -H "Cookie: session=..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key",
    "scopes": ["read", "write", "results"],
    "expiresInDays": 365
  }'

Example Response

{
  "data": {
    "id": "key_abc123",
    "name": "Production API Key",
    "keyPrefix": "rhb_sk_1a2b3c",
    "scopes": ["read", "write", "results"],
    "expiresAt": "2027-03-29T16:00:00Z",
    "createdAt": "2026-03-29T16:00:00Z",
    "apiKey": "rhb_sk_1a2b3c4d5e6f7g8h9i0j"
  },
  "message": "Save this API key now — it won't be shown again."
}

The full apiKey value is returned only in this response. Store it securely. You cannot retrieve it later.

Revoke API Key

Permanently revoke an API key. Revoked keys cannot be reactivated.

DELETE /api/v1/keys?id=:id

Query Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	The key ID to revoke

Example Request

curl -X DELETE "https://rhumby.com/api/v1/keys?id=key_abc123" \
  -H "Cookie: session=..."

Example Response

{
  "message": "API key revoked"
}

Revoking a key takes effect immediately. Any in-flight requests using that key will fail on the next API call.

Best Practices

Security

Never commit keys to version control. Use environment variables or secret managers.
Rotate keys regularly, especially for production services (every 90-365 days).
Use minimal scopes. Grant only the permissions your application needs.
Revoke unused keys immediately to reduce attack surface.

Development Workflow

Separate keys for dev/staging/prod. Use different keys per environment.
Name keys descriptively. Include environment and purpose (e.g., "Production Results Upload").
Monitor lastUsedAt. Identify and revoke stale keys that haven't been used in months.

Rate Limiting

All API keys default to 1,000 requests/hour. If you exceed this limit, requests return 429 Too Many Requests. Contact support for higher limits if needed.

Authentication Guide — How to use API keys in requests
Webhooks — Subscribe to real-time event notifications (requires admin scope)
Embed Tokens — Generate tokens for public widget embeds (requires organization membership)

API Keys

On this page

API Keys

On this page