Convilyn User Manual

API keys

An API key lets another app — the Ainalyn desktop app, the command line, or your own integration — act on your Convilyn account. You manage keys in Settings → API in the web app, or in the full API console.

What an API key is for

A key authenticates calls made on your behalf, so you can use Convilyn outside the browser:

  • The Ainalyn desktop app — paste a key to connect the app to your account (see Convilyn & Ainalyn).
  • The command line — the convilyn CLI reads the key from your environment.
  • Your own integrations — any script or service that calls the Convilyn API.

A key acts on your behalf, so treat it like a password. Anyone who has it can spend your credits.

Create a key

  1. Open Settings → API (sign in first).
  2. Choose Create key and give it a name you'll recognize later — for example, "My desktop".
  3. Pick the key's scopes and, optionally, an expiry (both described below). The defaults — full access, no expiry — suit a personal key.
  4. Copy the full key. It starts with ck_ and is shown only once — store it somewhere safe, because you won't be able to see it again.

Scopes

Scopes limit what a key can do:

  • Read — read-only access: list workflows, check status, download results, read usage.
  • Write — run workflows that spend credits.

A new key defaults to full access (read + write). For a key used only for reporting or read-only automation, choose Read alone — it can't spend credits, so a leaked read-only key can't run up a bill.

Expiry

Give a key an optional expiry date. Once it passes, the key stops authenticating automatically. Leave it blank for a key that never expires.

Use a key

Send the key in the Authorization header as a Bearer token:

curl https://convilyn.corenovus.com/api/v1/workflows/catalog \
  -H "Authorization: Bearer ck_your_key"

Replace ck_your_key with the key you created. For the full programmatic surface — the Python SDK, the convilyn CLI, and the REST API — see the developer documentation.

Manage your keys

From Settings → API you can:

  • Revoke a single key — it stops working immediately. There is no undo.
  • Revoke all keys at once — an incident-response control for when you suspect a key has leaked.

Replacing a key without downtime

There is no rotate button, and you do not need one:

  1. Create a second key with the same scopes.
  2. Deploy it wherever the old one is used.
  3. Revoke the old key.

You decide how long both keys stay valid, and the old one stops the moment you revoke it — not when a timer expires. If a key has leaked, go straight to Revoke: that is the only step that actually cuts an attacker off.

Monitor usage

Each key's activity is tracked so you can keep an eye on cost and health:

  • Usage — requests, errors, and credits used per key, over a preset or custom date range.
  • Request logs — inspect recent API calls (method, endpoint, status, duration, cost).
  • Rate limits — the per-key request limits enforced on each endpoint category.

Plans and availability

API access is included on every plan, Free included — plans differ in credits and limits, never in features. Cloud calls made with a key draw on the same credit balance as the web app.

Webhooks

Register an HTTPS endpoint and Convilyn POSTs to it when a job finishes, so your integration reacts to results without polling.

  • Events — job.completed and job.failed.
  • Signed — every delivery carries an X-Convilyn-Signature header (HMAC-SHA256 over the payload) so your receiver can verify it came from Convilyn. The signing secret is shown only once, when you create the hook.
  • Reliable — failed deliveries retry with exponential backoff and move to a dead-letter queue after repeated failures. Delivery is isolated from your job, so a slow or failing receiver never delays it.
  • Testable — send a sample event to a hook to check your endpoint before you rely on it.

Create and manage webhooks — reveal the secret, enable or disable a hook, or send a test event — in the API console.

The API console

For the complete management surface, use the standalone API console — sign in with your Convilyn account. It gathers everything above in one place, with deeper views:

  • Keys — create and revoke; set scopes and expiry.
  • Usage — analytics over a preset or custom date range, with a per-key breakdown.
  • Request logs — page through recent API calls.
  • Rate limits — the per-key limits for each endpoint category.
  • Webhooks — register, test, and manage outbound webhooks.

Settings → API in the web app is a quick-view of the essentials (keys, usage, and the desktop app); the console is the full experience.

Where to go next