Authentication

Convilyn uses two distinct credential families: API keys that you send to the platform, and an HMAC secret the platform uses to sign requests it sends to your tool server. Which one you need depends on whether you're calling the API or extending it.

Key types at a glance

Consumer API keys (ck_)

Mint a key on your Settings → API page (auth-gated; also where billing and quota live). It's shown once — store it securely. Every consumer SDK reads CONVILYN_API_KEY from the environment when you don't pass it explicitly:

from convilyn import Convilyn
 
client = Convilyn()                    # reads CONVILYN_API_KEY
client = Convilyn(api_key=my_key)    # or pass it explicitly

The key is sent as Authorization: Bearer ck_.... The SDKs mask it in every log line and error message (and in Go, in every fmt verb) so it never leaks into stack traces or telemetry.

Scopes: what a key is allowed to do

Every ck_ key carries scopes, chosen when you mint it:

A new key gets both. Choose read-only for anything that only reports — a dashboard, a nightly export, a CI job that checks status — and a leaked key of that kind cannot start a workflow or run up a bill.

The rule is the HTTP method, not a list of endpoints: any request that changes state needs write. A read-only key issuing one gets 403 with a structured body you can branch on:

{
  "detail": {
    "code": "insufficient_scope",
    "required_scopes": ["write"],
    "granted_scopes": ["read"],
    "message": "This API key is read-only. Required scope(s): ['write']. Mint a key with write access."
  }
}

A handful of POST endpoints read rather than write — cost previews, price quotes, and batch downloads that take a list of ids in the body — and those stay available to a read-only key.

Scopes are fixed at mint time. To change them, create a new key and revoke the old one; see replacing a key for the no-downtime sequence.

Author & deploy tokens (cvl_ / cvi_)

The Author SDK's platform client (ConvilynClient) authenticates to the authoring endpoints with your platform token. These let you register and verify your own tool servers — workflow authoring lives in the Convilyn chat Builder — and should never be used for consumer API calls. See the Author SDK overview for the publishing flow.

Inbound HMAC (gateway → your tool server)

When you author tools, the gateway calls back into your server over HTTPS. Every such call is HMAC-signed so you can reject forgeries. The signature travels in two headers over the raw request body:

• x-convilyn-signature — HMAC of the timestamp + body, keyed by your shared secret
• x-convilyn-timestamp — Unix seconds, checked against a freshness window

The SDK runtimes verify this for you (serve in Python/TS, the HTTP middleware in Go). Verify manually only if you run your own HTTP framework:

from convilyn_author import verify_signature, InvalidSignatureError
 
try:
    verify_signature(secret, raw_body, headers)
except InvalidSignatureError:
    return Response(status_code=401)

A mismatch reports a precise reason (missing_secret, missing_header, invalid_timestamp, timestamp_out_of_range, signature_mismatch) so you can distinguish a clock-skew problem from a forged request.

Secrets used by a tool server

Where to go next