API keys

#Overview

An API key lets a program or an MCP client act as you: the REST API, your scripts outside the app, and AI assistants connected over MCP all use one. A key carries your company, your role and permissions, and your licence seats. It never has more access than you do.

You manage keys on Integrations > API keys. Keys need your company's Integrations licence.

#Create a key

1. Open Integrations > API keys and click Create key.
2. Enter a Name (1 to 80 characters), for example "Nightly decline run".
3. Under What it can do, tick the scopes the program needs.
4. Choose when it expires.
5. Click Create key.
6. Copy the key from Copy your API key now and store it in a secret store or an environment variable (CONVERGE_API_KEY). Click I have stored it.

Creating a key needs the Manage API keys permission and a plan or licence that includes API access. Without the permission you can still see and revoke your own keys. You can hold up to 25 active keys; revoke one you no longer use to make room.

#Scopes

New keys get engine:run and projects:read unless you change them. A key with no valid scope cannot be created.

Some calls need two scopes: the project fluid-model tools (eos.model.*) run on a saved project, so they need engine:run and projects:read.

GET /v1/me and the function list (GET /v1/engine/functions) work with any valid key.

#Expiry

An expired key is refused with 401 and the message to create a new one.

#How keys are stored

• A key is cvg_ followed by 43 base64url characters: 32 random bytes.
• Converge stores only the SHA-256 hash of the whole key, plus a 10-character display prefix (cvg_ and the next six characters) so you can tell keys apart.
• On each request the presented key is hashed and looked up by hash, so the secret itself is never compared or stored.
• The create response is sent with Cache-Control: no-store, and the app forgets the key when you close the dialog.

#What a key can and cannot do

A key works only on the endpoints programs need: /v1/me (read), /v1/engine/functions, /v1/projects and /v1/mcp. Every other endpoint refuses it with 403, including team management, seats, the AI Engineer chat, roles, review and sign-off, admin, and key management itself. A key cannot list, create or revoke keys.

Within those endpoints the usual checks still apply: the member's permissions, the company's licences, and the module's floating seats. See Seats.

A key stops working at once when:

• it is revoked,
• it expires,
• the member who created it is disabled,
• the company account is suspended,
• the member's email is not verified.

#Revoke a key

On API keys, click Revoke on the key's row and confirm with Revoke key. The key stops working immediately for every program and assistant using it, and this cannot be undone.

• You can always revoke your own keys.
• With the Manage API keys permission you can switch Whose keys to Company and see and revoke every member's keys, with the owner shown.

#Audit

Converge writes to the company audit log when a key is created (name, prefix, scopes, expiry), when it is revoked, and when it is used: on first use and then at most once an hour per key, with the method and path. The key list shows when each key was last used. See Audit log.

Failed key attempts are rate limited to 20 a minute per client address.

#Related

• REST API
• MCP
• Team and roles
• Security