Authentication

How to authenticate API requests

All API requests require authentication using an API key.

API Keys

API keys are created in the Control Plane under Settings → API Keys.

Authentication Header

Include your API key in the Authorization header:

Authorization: Bearer sk_api_abc123xyz

Example Request

curl -X GET https://api.valmi.io/v1/agents \
  -H "Authorization: Bearer sk_api_abc123xyz" \
  -H "Content-Type: application/json"

API Key Types

SDK Keys

Used by SDKs to send metering events:

• Format: sk_live_... or sk_test_...
• Permissions: Send actions, send outcomes, read usage

API Keys

Used for direct API access:

• Format: sk_api_...
• Permissions: Configurable (read-only, read-write, admin)

Base URL

All API requests go to:

https://api.valmi.io/v1

Rate Limiting

API requests are rate-limited:

• SDK Keys: 10,000 requests per minute
• API Keys: 1,000 requests per minute

Rate limit headers are included in responses:

• X-RateLimit-Limit: Request limit
• X-RateLimit-Remaining: Remaining requests
• X-RateLimit-Reset: When limit resets

Error Responses

Invalid authentication returns 401 Unauthorized:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}