API keys

An API key lets a script or integration call Nuvelics without a person signing in. This page explains what a key is and how to handle one. The steps to create and revoke one are in API keys.

What a key isCopy Anchor Link

The keys you create are service keys. A service key acts for the organization, not for a person, so its access does not depend on anyone's role. A key starts with nvs_. You cannot create a key for a person: the web app and the API create service keys only.

What a key can holdCopy Anchor Link

Every key carries its own list of permissions, chosen when it is created. The rules:

• At least one permission, and each must be one the creator holds. A key can never do more than the person who made it could at that moment.
• Fixed after creation. A key is not edited. Its permissions are used as they are, so changing the creator's role later does not change the key.
• An optional expiry. A key created with the API can carry an expiry (the web form sets none), and an expired key is refused.
• Tenant permissions only. Keys can hold the permissions on the permission matrix, and nothing else.

Give a key only the permissions its job needs. A key that reads stories does not need Edit stories. Creating a key needs Manage API keys (apikey:manage), held by owners and admins.

Some operations record who acted, and a service key is not a person. Several MCP tools refuse a key for that reason; they are listed in Use an API key.

Where each surface takes a keyCopy Anchor Link

• API. Send the key in an x-api-key header, or as Authorization: Bearer <key>. See the API reference.
• MCP. Send it as an x-api-key header to the MCP server. The organization's MCP switch still applies. See Use an API key.
• Command line. nuvelics login --manual stores a key you already have, which then works until it is revoked or expires. See Sign in to the command line.
• The web app does not accept a key; people sign in there.

Creating, rotating and revokingCopy Anchor Link

You create a key in the web app or with the API (POST /api/tenant/v1/api-keys). The key is shown once and cannot be shown again. The CLI lists keys (nuvelics api-key list) but does not create or revoke them.

Nuvelics has no rotate action. To replace a key, create a new one with the permissions you need, switch the systems that use it, then revoke the old one. Revoking, in the web app or with DELETE /api/tenant/v1/api-keys/{id}, takes effect immediately: anything still using the key loses access. Revoking needs Manage API keys, and the key's Last used time helps you confirm that nothing depends on it before you do.

The API reference is API keys.