1. [Help](https://nuvia.ai/en/docs) 2. [Account Settings](https://nuvia.ai/en/docs/colecoes/19430666-account-settings) # How to manage API keys in Nuvia Create, organize and revoke API credentials to connect external systems to Nuvia, with granular permission scopes and instant revocation at any time. Available on All plans. Who can do it Account administrators Updated on September 9, 2026 [Account Settings](https://nuvia.ai/en/docs/colecoes/19430666-account-settings) 1. [How to turn on two-factor authentication (MFA)](https://nuvia.ai/en/docs/artigos/18174510-how-to-turn-on-two-factor-authentication-mfa) 2. [How to set your availability (Away or Unavailable)](https://nuvia.ai/en/docs/artigos/18174522-how-to-set-your-availability-away-or-unavailable) 3. [How to manage API keys in Nuvia](https://nuvia.ai/en/docs/artigos/15230128-how-to-manage-api-keys-in-nuvia) 4. [How to deactivate and reactivate a user](https://nuvia.ai/en/docs/artigos/16497565-how-to-deactivate-and-reactivate-a-user) 5. [Security, privacy, and LGPD at Nuvia](https://nuvia.ai/en/docs/artigos/14576039-security-privacy-and-lgpd-at-nuvia) 6. [How to create and manage teams in Nuvia](https://nuvia.ai/en/docs/artigos/15649230-how-to-create-and-manage-teams-in-nuvia) 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 1. In the **Side menu**, click the 3 dots next to the profile icon 2. Click **Settings** 3. 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 1. On the API Keys page, click **New API Key**. 2. Fill in the **Name**; use something descriptive that identifies the integration (e.g. “CRM Integration”, “BI Dashboard”). 3. Select the **Scopes** this key can access (see the full list in the **Available permission scopes** section below). 4. (Optional) Set an **Expiration** by picking a future date on the calendar. If you leave it blank, the key **doesn't expire**. 5. Click **Create API Key**. 6. Click **Copy token** to copy the JWT to the clipboard. 7. Store the token in a secure place. 8. Click **Close**. The token is shown **only once**. After you close the modal, you can't view it again; the only reference in the list is the 4-character suffix (**Preview** column). If you lose the token, you'll need to revoke the key and create a new one. **Tip:** If you try to close the modal without copying the token, Nuvia shows a confirmation warning. Go back and copy it before continuing. ### Available permission scopes Each scope unlocks a set of actions on an API resource. You choose the scopes when you create the key. ResourcesAvailable 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 Important scopes are set at creation and can't be changed later. If you need different permissions, create a new key with the scopes you want and revoke the old one. ### 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. ScopeWhat 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 Important creating, editing or deleting a custom field's **definition** (and its options) is still an action for a user logged in to the platform, with the Custom fields permission. An API key can't do it, even with both scopes checked. That's why the “Custom fields — Create” and “Custom fields — Delete” scopes, which were on the list with no operation behind them, were removed. 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. Important when triggering through this endpoint, the contact is found by **phone** and its CRM link starts pointing to the integration that triggered it. If the contact already belonged to another integration (for example, HubSpot), the previous sync no longer applies to it. Use a phone in international format (E.164, e.g. +5511999999999). Tip to avoid duplicate triggers when your automation retries the call, send an **idempotency key** — repeats within 24 hours are ignored. ### 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. 1. In the list, find the API key you want to revoke. 2. Click the actions menu (**⋮**) on the right of the row. 3. Click **Revoke**. 4. In the confirmation modal, fill in the **Reason** (e.g. “integration discontinued”, “leaked key”, “credential rotation”). 5. Click **Revoke API Key**. 6. The key stops authenticating requests immediately. Important revocation is **permanent and can't be undone**. The key goes on a blacklist and no system using it will be able to authenticate anymore. Update the token in the external system **before** revoking the old key. ### API key status StatusColor in the interfaceWhat 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. Note If the account is in its **trial period** and the trial expires, every API key in the company stops authenticating — even if it shows as **Active** in the list and has no expiration date set. The block follows the **subscription status in real time**, not a date saved on the key: it goes away automatically as soon as the account is active again (when you sign up for a plan). ## Frequently asked questions ## Frequently asked questions **How many API keys can I create per company?** There's no limit. Create as many as you need. We recommend using **one key per integration or external system**, which makes management and traceability easier. **I lost the JWT token. Can I recover it?** No. For security, Nuvia doesn't store the full JWT. The only option is to revoke the current key and create a new one. Use the 4-character suffix (**Preview** column) to identify which key needs to be replaced. **Can I edit the scopes of an existing API key?** No. Scopes are set at creation and can't be changed later. If you need different scopes, create a new key with the permissions you want and revoke the old one. **The “Custom fields — Create” and “Custom fields — Delete” scopes disappeared from the list. Where did they go?** They were removed because there was no API operation behind them: they were scopes you could check that didn't unlock anything. Creating and deleting a custom field (and its options) is a user action in the platform, not an API key action. If you had a key with these scopes checked, nothing changes in practice — the integration was never able to create or delete fields with them. **New Knowledge base and Webhooks scopes showed up. Are these new features?** No. These endpoints already accepted API keys; the scope list on the screen just didn't show it, so no one knew they could request them. Now they appear grouped under **Knowledge base** and **Webhooks** when you create the key. The same goes for the Agent tools, Agent follow-ups, Contact notes and Inboxes — Delete scopes. **What happens to in-progress requests when I revoke a key?** Revocation is immediate: any request using the revoked token is rejected from that moment on. Update the token in the external system before revoking the old key. **The “Last used” column shows no date. What does that mean?** It means the key hasn't been used in any request since it was created. The date is filled in automatically after the first use. **What is the “Campaign triggers” scope for?** It unlocks triggering campaigns from your own CRM or an automation (n8n, Zapier or a direct call), without relying on the native integrations. When it receives an event (contact, deal or lead created/updated), Nuvia finds the contact by phone and enrolls it in the configured campaigns. Only grant this scope to the key used by that automation. **Are an API key and the MCP connection the same thing?** No. An **API key** is a credential (JWT token) for system-to-system integrations with the Nuvia API. The **MCP** connects AI apps (such as Claude and Cursor) through OAuth authorization, with login on Nuvia's own screen (without generating an API key). Use an API key to integrate servers and systems; use MCP to connect AI clients. **My integration suddenly stopped working, but the key shows as Active. Why?** The most common reason is the end of the account's trial period: while the trial is expired, no API key in the company authenticates, regardless of the status shown in the list or the expiration set. Sign up for a plan to reactivate the account — the key's access comes back on its own, without having to recreate it. [PreviousHow to set your availability (Away or Unavailable)](https://nuvia.ai/en/docs/artigos/18174522-how-to-set-your-availability-away-or-unavailable) [NextHow to deactivate and reactivate a user](https://nuvia.ai/en/docs/artigos/16497565-how-to-deactivate-and-reactivate-a-user) Was this article helpful? ## Related articles - [How to connect WhatsApp to Nuvia](https://nuvia.ai/en/docs/artigos/14489425-how-to-connect-whatsapp-to-nuvia) - [How to create custom skills for the AI agent](https://nuvia.ai/en/docs/artigos/14590394-how-to-create-custom-skills-for-ai-agent) - [Nuvia MCP tools reference](https://nuvia.ai/en/docs/artigos/16074574-nuvia-mcp-tools-reference) - [What Nuvia syncs with HubSpot and when](https://nuvia.ai/en/docs/artigos/16473526-what-nuvia-syncs-with-hubspot-and-when) [Account Settings](https://nuvia.ai/en/docs/colecoes/19430666-account-settings) 1. [How to turn on two-factor authentication (MFA)](https://nuvia.ai/en/docs/artigos/18174510-how-to-turn-on-two-factor-authentication-mfa) 2. [How to set your availability (Away or Unavailable)](https://nuvia.ai/en/docs/artigos/18174522-how-to-set-your-availability-away-or-unavailable) 3. [How to manage API keys in Nuvia](https://nuvia.ai/en/docs/artigos/15230128-how-to-manage-api-keys-in-nuvia) 4. [How to deactivate and reactivate a user](https://nuvia.ai/en/docs/artigos/16497565-how-to-deactivate-and-reactivate-a-user) 5. [Security, privacy, and LGPD at Nuvia](https://nuvia.ai/en/docs/artigos/14576039-security-privacy-and-lgpd-at-nuvia) 6. [How to create and manage teams in Nuvia](https://nuvia.ai/en/docs/artigos/15649230-how-to-create-and-manage-teams-in-nuvia) ## Still need help? Customers reach support through the chat inside the platform. Not a customer yet? Talk to our team. [Talk to support in the platform](https://app.nuvia.ai) [I'm not a customer yet](https://nuvia.ai/en/contact) --- Source: https://nuvia.ai/en/docs/artigos/15230128-how-to-manage-api-keys-in-nuvia