How do I create and manage API keys?

Short answer

Owners and admins open Configuration › Settings › API keys, click Create, give the key a name, choose its scopes and an expiry, and create it. The key starts with wck_ and its full value is shown only once, so copy it into your secret manager right away. Send it in the Authorization: Bearer header from your server.

You only need a key for server-side events and log import. The website script does not use one: it carries the public site key, which is safe to expose.

Create a key

1. Go to Configuration › Settings and open the API keys tab. Creating and revoking keys needs the owner or admin role.
2. Click Create and enter a name that says where the key is used, for example order-service or nginx-importer.
3. Choose the scopes (see below). Pick only what this integration needs.
4. Choose an expiry: never, 30, 90 or 365 days.
5. Click Create and copy the key from the dialog. After you close it, only the prefix is shown.

Each key is bound to the project it was created in. Events sent with it land in that project, so requests do not carry a project ID.

Choose scopes

The list also offers Read stats, Manage definitions and Issue embed, which specific integrations use. Grant them only when a guide asks for them. A request without the required scope returns 403.

Use one key per service and purpose. An order service needs only Server track; a log shipper needs only Import logs. If one key leaks, you revoke one integration, not all of them.

Use the key

Send the key in either header:

Authorization: Bearer wck_xxxxxxxxxxxxxxxx

X-Api-Key: wck_xxxxxxxxxxxxxxxx

With a server SDK, pass it as apiKey from an environment variable, for example TAPCUB_API_KEY. See Send events from your server and Send events with the HTTP API.

Never put a key in a query string, in front-end code, in a mobile app bundle or in a repository. Anyone with the key can write data into your project.

Rotate and revoke keys

The key list shows each key's name, prefix, scopes, expiry and when it was last used.

• Rotate regularly: create a new key with the same scopes, deploy it, check that Last used has moved to the new key, then revoke the old one.
• Revoke at once if a key may have leaked. Requests with a revoked or expired key return 401.
• Clean up keys that have not been used for months.

When asking support for help, share only the prefix, never the full key.

FAQ

I lost the key. Can I see it again? No. The full value is shown once. Create a new key and revoke the old one.

Which errors mean a key problem? 401 NO_API_KEY (no key in the header), 401 BAD_API_KEY (wrong, revoked or expired key) and 403 (key lacks the scope).

Can one key write to several projects? No. Create a key in each project.

Related

• Send events from your server
• Import server logs
• Team and roles