obscyro

Getting Started / Authentication

Authentication

All Obscyro API calls are authenticated with a Bearer API key. Mint one from the dashboard or via the create-key CLI.

API keys

Every authenticated request carries an Authorization: Bearer obs_live_… header. Keys are 192-bit, prefixed obs_live_, and shown to you exactly once at creation time. Obscyro stores only a SHA-256 hash, so a leaked database is not a leaked key.

GET/v1/concepts/{code}
curl https://api.obscyro.com/v1/concepts/22298006 \
  -H "Authorization: Bearer obs_live_AbCDef12_GhIjKl34..."

Minting a key

In production, mint keys via self-serve sign-up. For local development, use the CLI bundled with the backend:

npm run create-key -- --name "dev" --email "you@example.com" --plan starter

The output prints the raw key once. Save it to your secret manager immediately.

Public routes

A small number of routes are intentionally unauthenticated so you can probe liveness and read OpenAPI without a key:

  • /health

    Liveness probe — returns ok if the API process is running.

  • /v1/health

    Readiness probe — verifies the database is reachable.

  • /documentation

    Interactive Swagger UI.

Failure modes

Hitting any other endpoint without a valid key returns:

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Missing or invalid API key. Send `Authorization: Bearer obs_live_...`."
  }
}

with HTTP status 401. See Errors for the full envelope contract and Rate limits for 429 responses.

Key rotation

To revoke a key, contact us at obscyro-team@obscyro.com. Self-serve revocation in the dashboard is coming soon. Active sessions tolerate a soft 60-second TTL while the in-memory cache expires; after that, requests return 401 INVALID_API_KEY.