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.

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