API Keys#

API keys let developers call the platform API from their own programs, scripts, or services, acting as a given user — without going through the username/password login flow. Each key maps uniquely to one user account; just include it in the request to authenticate.

1. Create a key#

1. After signing in, go to Developer → API Keys.
2. Click Create key, give it a name (to tell keys apart), and optionally set an expiry.
3. A key starting with sk_live_ is generated.

The key is returned in full only once, at creation — save it immediately. It cannot be recovered if lost; you can only delete and recreate. You can rename or revoke a key anytime in the list; revoking takes effect immediately.

2. Authentication#

For any authenticated endpoint, include the key in the request headers. Two forms are supported, use either one:

httpAuthorization: Bearer sk_live_xxxxx

httpx-api-key: sk_live_xxxxx

Authorization: Bearer takes precedence if both are present.

3. Examples#

curl#

bashcurl https://your-app.com/v1/api-keys/verify \
  -H "Authorization: Bearer sk_live_xxxxx"

JavaScript / TypeScript#

tsconst res = await fetch("https://your-app.com/v1/api-keys/verify", {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
})
const json = await res.json()
console.log(json.data) // { user_id, email, role }

Python#

pythonimport requests

res = requests.get(
    "https://your-app.com/v1/api-keys/verify",
    headers={"Authorization": f"Bearer {API_KEY}"},
)
print(res.json()["data"])

4. Verify a key / get identity#

GET /v1/api-keys/verify validates a key and returns the associated user identity — useful for checking auth state.

Success response:

json{
  "success": true,
  "message": "success",
  "data": {
    "user_id": "607a92ab-...",
    "email": "you@example.com",
    "role": "member"
  }
}

Once you have the user_id, all subsequent business endpoints (credits, subscriptions, etc.) run in that user's context.

5. Response format#

Every endpoint returns a unified shape:

json{ "success": true, "message": "...", "data": {} }

On auth failure, success is false. Common messages:

6. Security tips#

• Never hard-code keys — use environment variables or a secrets manager.
• Don't commit them to Git or ship them in frontend code (a key equals account access).
• Create separate keys per use case so they can be revoked individually.
• Set an expiry and rotate keys regularly.
• If leaked, revoke it immediately under Developer → API Keys and recreate.

7. Command-line tool#

If you just want to use this from the terminal, the project ships a CLI built on top of these APIs — login once and it stores the key for you, no manual headers needed. See Command-Line Tool (CLI).