Clavem

API key

An API key is a secret string that a program sends with every request to an API, so the server can identify the caller and decide what that caller is allowed to do.

How it works

The API provider creates a random secret and shows it to you, usually once. You store it and send it with each request, most often in a header. The server hashes what it receives, looks the hash up, and finds the account the key belongs to. That is authentication: it names the caller. A key stands for an account or an integration, not for a person.

Because anyone holding the string can act as the account, the main rule is keeping it off every machine you do not control. That includes customer devices, browsers, public repositories and client-side code.

An example from the Clavem management API

Clavem management API keys go in the Authorization header as a bearer token. A request with a key that is invalid or revoked gets this real response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"error":{"code":"unauthorized","message":"This API key is not valid or has been revoked."}}

A request with no key gets the same shape and a hint in the message:

{"error":{"code":"unauthorized","message":"Send your API key as `Authorization: Bearer sk_clavem_...`."}}

Branch on code, which is stable. The message is for people.

Where the key must never go

Suppose you put a management key in your Electron app so it can create licenses. Every customer who unpacks the app now holds your account access. They can create licenses without paying, look up other buyers’ emails, and disable licenses. The fix is a small server you run: the app talks to your server, and your server holds the key. The same reasoning applies to browser extensions, mobile apps and plugins.

API key versus license key

API key License key
Held by You, the developer, on your server The buyer, on their device
Grants Control of your account’s data The right to use one purchase
Secret from users Yes No, the user types it in
If it leaks Revoke and replace it Disable the license, or rely on the device limit
Checked by The vendor’s API Your app, through the license service

The two are easy to mix up because both are random strings. A license key is meant to reach your customers. An API key never is.

How Clavem handles it

Management API keys start with sk_clavem_. You create them under Developers in the dashboard. Each is shown once, stored hashed on Clavem’s side with a visible prefix, and can be revoked at any time. Send it as Authorization: Bearer sk_clavem_... from your server only. The management API sends no CORS headers, so a browser cannot call it by design. It allows 300 requests per 60 seconds per key, and past that it answers 429 (rate limiting). The management API creates, looks up, changes and disables licenses.

The License API your app calls needs no API key. The license key is the credential, so nothing secret ships in the app. The API reference lists every endpoint. An MCP server for managing licenses from an AI assistant is being added and also uses a management API key.

Questions

Can I put an API key in my desktop app?

No. Anything shipped inside an app can be extracted by the person who runs it. Keep API keys on your own server and call the API from there.

What should I do if an API key leaks?

Revoke it and create a new one. Then look at what the key could do and check the account's activity for anything you did not make.