API keys are credentials that let external systems authenticate to the Nuvia API on behalf of your company. Each key has its own permission scopes and can be revoked whenever you want.
Available on: All plans.
Who can do it: Account administrators.
Before you start
-
Make sure your profile has administrator access.
-
Have a secure place to store the token, such as a secrets manager. The token is shown only once, when it's created; after that, there's no way to view it again.
Open the API keys page
-
In the Side menu, click the 3 dots next to the profile icon
-
Click Settings
-
In the Side menu, click API Keys
The list shows all your company's API keys, with name, scopes, token preview (last 4 characters), creation date, expiration, last used and status.
Create a new API key
-
On the API Keys page, click New API Key.
-
Fill in the Name; use something descriptive that identifies the integration (e.g. “CRM Integration”, “BI Dashboard”).
-
Select the Scopes this key can access (see the full list in the Available permission scopes section below).
-
(Optional) Set an Expiration by picking a future date on the calendar. If you leave it blank, the key doesn't expire.
-
Click Create API Key.
-
Click Copy token to copy the JWT to the clipboard.
-
Store the token in a secure place.
-
Click Close.
Available permission scopes
Each scope unlocks a set of actions on an API resource. You choose the scopes when you create the key.
| Resources | Available actions |
|---|---|
| Agents | Read, Create, Update, Delete |
| Contacts | Read, Create, Update, Delete |
| Conversations | Read, Create, Update |
| Campaigns | Read, Create, Update, Delete |
| Messages | Read, Send |
| Inboxes | Read, Create, Update, Delete |
| Tables | Read, Create, Update, Delete |
| Agent tools | Read, Create, Update, Delete |
| Agent follow-ups | Read, Create, Update, Delete |
| Contact notes | Read, Create, Update |
| Campaign enrollments | Read, Create |
| Custom fields | Read, Update value |
| Knowledge base | Read, Create, Update |
| Webhooks | Read, Create, Update, Delete |
| Search | Query, Enrich and save |
| LinkedIn search | Query, Save |
| Enrichment | Query, Run |
| Campaign triggers | Trigger |
What the Custom fields scopes unlock
The Custom fields scopes let an integration write values to fields that already exist, not create or delete the field definition.
| Scope | What the key can do |
|---|---|
| Custom fields — Read | List the company's custom fields (to find each one's identifier) and list the active options of a dropdown or multiple-choice field |
| Custom fields — Update value | Write the value of a custom field on a conversation, on its contact or on the contact's company |
When writing values, keep in mind:
-
The field is identified by its slug (the identifier shown in the field list), not by the internal ID.
-
The conversation is required in the call, even when the field is a contact or company field: Nuvia uses the conversation to find the contact and the company.
-
Text, number and date fields take the value directly. Dropdown and multiple-choice fields take the option identifier, which comes from the field's option list.
-
A value outside the accepted options is rejected, and the response includes the list of valid values.
-
A field or conversation from another company is rejected.
Trigger campaigns from your own CRM (Campaign triggers scope)
The Campaign triggers — Trigger scope unlocks the endpoint that lets your own CRM or an automation (n8n, Zapier or a direct API call) trigger campaigns in Nuvia from events in your CRM: contact created or updated, deal created or updated, and lead created or updated.
Use it when your CRM isn't one of the native integrations (HubSpot or RD Station) and you want it to trigger campaigns in Nuvia. The automation sends the contact (with phone) and the event data, and Nuvia enrolls the contact in the configured campaigns.
Filter and search API keys
Use the filters in the top right corner of the page to switch between:
-
Active: keys that can authenticate requests (default view).
-
Revoked: permanently disabled keys.
-
All: shows active and revoked keys.
You can also find a key by name using the search field.
Revoke an API key
Revoking permanently disables the key. Use it when an integration is discontinued, when you're rotating credentials or when you suspect a leak.
-
In the list, find the API key you want to revoke.
-
Click the actions menu (⋮) on the right of the row.
-
Click Revoke.
-
In the confirmation modal, fill in the Reason (e.g. “integration discontinued”, “leaked key”, “credential rotation”).
-
Click Revoke API Key.
-
The key stops authenticating requests immediately.
API key status
| Status | Color in the interface | What it means |
|---|---|---|
| Active | Green | The key is working and authenticates requests normally. |
| Expired | Red | The configured expiration date has passed; the key no longer authenticates. Create a new one to continue. |
| Revoked | Gray | The key was permanently disabled by a user and no longer authenticates. |