API Credentials

API keys let your own applications, scripts, and automations call the VIVI API securely, without a person having to log in. In the portal they’re called API Credentials, and they come in two types: Account API keys and Workspace API keys. This guide explains the difference between them, when to use each, and exactly how to create and use one.

API keys are not the same as the vivi-api-key header. The vivi-api-key is generated by an API channel and is used to send messages to one specific agent. The API keys on this page authenticate you to the VIVI platform API (managing agents, workspaces, knowledge bases, and more) and use an Authorization: Bearer token instead. If you only want to chat with a single agent, use an API channel.

Account vs. Workspace API keys

Both kinds of keys work the same way technically. The difference is how much they can access.

Account API key

Acts as an account administrator with access to every workspace in your account. Best for organization-wide automation and managing multiple workspaces from one place.

Workspace API key

Limited to one workspace and to a role you choose (for example, Content Manager). Best for integrations tied to a single team, client, or project.

	Account API key	Workspace API key
Access scope	The entire account (all workspaces)	A single workspace
Permissions	Full account admin	A workspace role you select (e.g. Workspace Admin, Content Manager, Chat User)
Where you create it	Manage Account → API Credentials	Workspace → Users → API Credentials
Who can create it	Account admins	Account admins or that workspace’s admins
Change the role later	No (always account admin)	Yes, you can update the assigned role anytime
Best for	Org-wide automation, provisioning, multi-workspace tools	Per-team integrations, least-privilege access, isolation

Rule of thumb: start with a Workspace API key and the narrowest role that does the job. Only reach for an Account API key when an integration genuinely needs to act across multiple workspaces. Smaller scope means less risk if a key is ever exposed.

For more on how accounts and workspaces relate, see Accounts & Workspaces.

How API keys work

A VIVI API key isn’t a single password you paste into one field. It’s a set of credentials your app exchanges for a temporary access token. When you create one, VIVI gives you four values to copy:

clientId

string

required

The public identifier for your API key. Sent as client_id when requesting an access token.

clientSecret

string

required

The secret half of the key, sent as client_secret. Shown only once, at creation, so store it somewhere safe.

audience

string

required

Tells VIVI which API the token is for (for example, https://vivi-cxp-api/). Copy it exactly as shown in the portal.

tokenUrl

URL

required

The endpoint where you exchange your credentials for an access token.

Using a key is a two-step process:

Exchange your credentials for an access token

Send your clientId and clientSecret to the tokenUrl. VIVI returns a short-lived access token (a JWT) that’s valid for about 24 hours.

Call the VIVI API with that token

Include the token on every request as Authorization: Bearer <access_token>. When it expires, repeat step 1 to get a new one.

Your app should save the access token and reuse it until it’s close to expiring, rather than requesting a new one on every call.

Create an API key

Open the right page

Account API key: go to Manage Account and open the API Credentials tab.
Workspace API key: open your workspace, go to Users, and open the API Credentials tab.

Create a new credential

Click Create and give it a clear name that explains what will use it (for example, Zapier integration or Nightly report job). For a Workspace key, also pick the role it should have.

Copy your four values immediately

VIVI shows your clientId, clientSecret, audience, and tokenUrl once, each with a copy button. The dialog also includes a ready-to-run curl example and a link to the API reference. Save the values in your secrets manager now.

The clientSecret is shown only once. After you close this dialog you’ll only ever see the last 4 characters. If you lose it, you’ll need to rotate the key (see below).

Start using it

Use the values to request a token and call the API, as shown in the next section.

API keys are available on eligible plans (such as Pro or Enterprise) and can only be created by a human administrator. If you don’t see the API Credentials tab, check your subscription or ask your account admin.

Use an API key

Replace the placeholders below with the values from the portal. The audience and tokenUrl must match exactly what VIVI showed you.

Step 1: Get an access token

curl -X POST "YOUR_TOKEN_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "YOUR_AUDIENCE",
    "grant_type": "client_credentials"
  }'

A successful response includes an access_token and how long it’s valid (in seconds):

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
  "token_type": "Bearer",
  "expires_in": 86400
}

Step 2: Call the VIVI API

Send the token as a Bearer token on the Authorization header. The example below lists the workspaces in your account.

curl "https://api.vivi.bot/accounts/YOUR_ACCOUNT_ID/workspaces" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Explore every available endpoint in the VIVI API Reference.

Never send your clientSecret to VIVI API endpoints. It’s used only at the tokenUrl to request an access token.

Acting on behalf of a user (optional). With an Account API key, you can add an X-User-Id: <user-id> header so new records are attributed to that specific VIVI user. This affects ownership only and never grants extra permissions.

Permissions

API keys don’t have their own separate permissions. They inherit them from the role described in the comparison above: an Account API key acts as an account admin, while a Workspace API key uses the role you assigned it (which you can change later). For details on the available roles, see Users.

Manage existing keys

All of these actions live on the same API Credentials tab where you created the key.

Rotate the secret

Generates a new clientSecret (shown once) and retires the old one. Use it if a secret may have leaked, or on a regular schedule. Tokens already issued stay valid until they expire (~24 hours), so update your app promptly.

Deactivate the key

Permanently disables the key. Any app using it will start receiving 401 Unauthorized errors. Use this when an integration is retired or a key is compromised.

Change the role

For Workspace API keys, you can assign a different workspace role after creation. Account API keys are always account admin and can’t change roles.

Identify a key

Each key shows the last 4 characters of its secret. Use this to tell which key is installed in which external system.

Troubleshooting

I get 401 Unauthorized when calling the API

Common causes: the token has expired (request a new one), the Authorization header isn’t formatted as Bearer <token>, or the key was deactivated. Request a fresh token and try again. (Rotating a secret doesn’t invalidate tokens that were already issued, so it won’t cause this on its own.)

I get 403 Forbidden

The key authenticated successfully but doesn’t have permission for that resource. A Workspace API key can only act inside its own workspace and within its assigned role. If you need broader access, raise the workspace role or use an Account API key.

My token request fails (invalid_client / invalid_request)

Check that you’re posting to the correct tokenUrl with Content-Type: application/json, and that clientId, clientSecret, and audience are copied exactly as shown in the portal (no extra spaces). The grant_type must be client_credentials. If the secret was lost, rotate the key to get a new one.

I closed the dialog and lost my client secret

Secrets can’t be recovered. VIVI only stores the last 4 characters. Open the API Credentials tab, rotate the key, and copy the new secret immediately.

I don't see the API Credentials tab

API keys require an eligible plan (such as Pro or Enterprise) and administrator permissions. For account keys you must be an Account Admin; for workspace keys, an Account Admin or that workspace’s admin. Confirm your subscription, or ask an account admin to create the key for you.

Should I use vivi-api-key instead?

Only for an API channel, which sends messages to a single agent. For everything else on the main VIVI API, use the API keys on this page with an Authorization: Bearer token.

Best Practices

Use the least privilege that works. Prefer a Workspace API key with a narrow role over an Account API key whenever possible.
Store secrets safely. Keep the clientSecret in a secrets manager or environment variable, never in source code, spreadsheets, or chat messages.
One key per integration. Give each app or job its own key with a descriptive name, so you can rotate or deactivate it without affecting anything else.
Cache and refresh tokens. Reuse the access token until it nears expiry instead of fetching a new one on every request.
Rotate regularly. Rotate secrets on a schedule, and immediately if you suspect exposure.
Deactivate what you don’t use. Disable keys for retired integrations or departed team members.

​Account vs. Workspace API keys

Account API key

Workspace API key

​How API keys work

​Create an API key

​Use an API key

​Step 1: Get an access token

​Step 2: Call the VIVI API

​Permissions

​Manage existing keys

Rotate the secret

Deactivate the key

Change the role

Identify a key

​Troubleshooting

​Best Practices

Account vs. Workspace API keys

How API keys work

Create an API key

Use an API key

Step 1: Get an access token

Step 2: Call the VIVI API

Permissions

Manage existing keys

Troubleshooting

Best Practices