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:

  • Rotate a key — issue a fresh secret while the old one keeps working for a short grace period (24 hours), so you can roll the new key out with no downtime. After the grace window the old key stops automatically.
  • 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.

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, rotate, 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