Skip to content
  • There are no suggestions because the search field is empty.

API Service Keys

Service Keys let organizations create and manage shared API keys at the organization level, instead of relying on individual user keys. Each integration can have its own key, so teams own their integrations independently and one failing key doesn't take down the others.

Plan / tier availability

  • Available to Workspace Admins on all plans.

Integrations or dependencies

  • Organizations can have up to 20 Service Keys (the limit is configurable per organization).
  • Workspace Admins can only create and manage keys for their own Workspace(s).

How to Use It

1. View Service Keys

View and manage all Service Keys associated with your Organization in the Service Keys tab within the Organization Settings.

Follow these steps:

  1. Log into VNTANA.
  2. If you are a Workspace Admin or above, open the User Profile Menu.
  3. Select Settings.
  4. You will be redirected to the Organization General Information page.
  5. Toggle to the Service Keys tab.
  6. You will see a list of all Service Keys created for your Organization.
    1. Create a new key.
    2. Expand an existing key to view its details and manage it.

Important: Workspace Admins will only see Keys associated with Workspaces they have access to.

 

2. Create a Service Key

Create one key per integration so each integration can be managed, rotated, or removed without affecting the others.

Follow these steps:

  1. Open the Service Keys tab.
  2. Click + Add Service Key.
  3. You will be redirected to the Create Service Key form.
  4. Complete the form:
    • Name* — a title for the key (up to 255 characters). Tip: name it after the integration, e.g. "Vibe IQ." The name must be unique.
    • Description — optional; describe how the key will be used (up to 500 characters).
    • Access Level* — Organization (default) or Workspace.
    • Role* — set by the Access Level (see table below).
    • Workspaces* — required only for Workspace access. Select every Workspace the key should reach.
    • To stop at any point, click Cancel. The in-progress key is discarded, and you return to the Service Keys list.
  5. Click Create.
  6. You will be returned to the Service Keys list. The new key is expanded, scrolled into view, and fully visible.
  7. Click Copy to copy the key to your clipboard, then share it with the developer who needs it.
    Important: The full key is only visible right after creation. It becomes encrypted when you click Hide, collapse the accordion, refresh, or leave the page. Copy it before then. If it's lost, rotate the key to get a new one.

How Access Level and Role Work Together

Access Level

Available Roles

Workspaces

Organization

Organization Admin (set automatically, can't be changed)

Not required — the key acts on the whole organization

Workspace

Workspace Admin, Workspace Content Manager, or Workspace Guest

Required — select one or more

Important: Workspace Admins can only create Workspace-level keys for the Workspaces they manage.

 

3.Show / Hide a Key Hint

For security, an existing key can't be viewed in full. Show reveals a short hint so you can confirm which key an integration is using.

Follow these steps:

  1. Open the Service Keys tab.
  2. Expand a key by clicking its title or chevron.
  3. In the key details, the key is shown encrypted, with action buttons to the right.
  4. Click Show.
  5. A hint is revealed (for example vntsk_...LeMj).
  6. The hint stays visible until you click Hide, collapse the accordion, refresh, or leave the page.

The Copy button only appears right after a key is created or rotated. It is not available for existing keys.

 

4. Rotate a Key

Rotating generates a new key and immediately invalidates the old one. Use it when a key is lost, exposed, or due for a refresh.

Follow these steps:

  1. Open the Service Keys tab.
  2. Expand the key you want to rotate.
  3. Click Rotate, to the right of the key field.
  4. A confirmation pop-up opens.
  5. Select the appropriate action:
    1. Cancel or X: the modal closes and nothing changes.
    2. Rotate: the pop-up closes, a success message appears, and the new key is shown in the key field.
  6. Click Copy to copy the new key, then update every integration that used the old key.
  7. The new key becomes encrypted when you click Hide, collapse the accordion, refresh, or leave the page.

Important: Any integration using the old key stops working immediately. Coordinate with the developer before rotating.

 

5. Edit a Key

You can update a key's Name and Description. Editing does not change the key itself, so connected integrations keep working.

Follow these steps:

  1. Open the Service Keys tab.
  2. Find the key and click the Edit (pencil) button on its accordion header.
  3. You will be redirected to the Edit Service Key form, pre-filled with the saved details.
  4. Update the Name and/or Description.
  5. Click Save in the upper right, or Cancel to discard changes.
  6. A success message appears and you return to the Service Keys list.

 

6. Delete a Key

Deleting permanently removes the key and its settings. Any integration using it stops working immediately.

Follow these steps:

  1. Open the Service Keys tab.
  2. Find the key and click the Delete (trashcan) button on its accordion header.
  3. A confirmation pop-up opens.
  4. Click Delete to confirm, or Cancel / X to keep the key.
  5. A success message appears and the key is removed from the list.

 
7. Use a Service Key in an Integration

Developers use the key to authenticate with the VNTANA Admin API, plugins, or apps. The key works independently of any user's permissions.

How it works:

  1. Send the key on every request in place of a user token:
    • X-AUTH-TOKEN: Bearer vntsk_...
  2. Organization-level keys act on the key's organization.
  3. Workspace-level keys also need the clientUuid header to act on one of the key's Workspaces, for example clientUuid: 6c1e9f2a-3b7d-4e58-a0c4-9d2f81b7e563.
  4. Always send keys over HTTPS, in a header — never in a URL.

Good to know:

  • /v1/auth/refresh-token and /v1/auth/logout do not apply to Service Keys.
  • Operations marked Not available to service keys return a 403.
  • A rotated or deleted key stops working immediately.

Troubleshooting Basics 

Issue

Quick Check

Service Keys tab is not visible

Confirm you have Workspace Admin access or above.

Create button is disabled

Complete all required fields: Name, Access Level, Role, and Workspaces (if Workspace access is selected).

+ Add Service Key doesn't create a new key

The organization may have reached its key limit (20 by default). Delete unused keys or contact support.

Copy button is missing

Copy only appears right after a key is created or rotated. To get a usable key again, rotate it.

Show only displays part of the key

This is expected. Show reveals a hint (e.g. vntsk_...LeMj), not the full key.

Key was lost before it was copied

Rotate the key to generate a new one, then update the integration.

API returns 401

Check the error: INVALID_SERVICE_KEY (wrong or mistyped key), SERVICE_KEY_REVOKED (rotated, revoked, or deleted), or SERVICE_KEY_EXPIRED.

API returns 403

The operation is marked Not available to service keys, or the key's Role doesn't allow it.

Workspace-level key returns errors or no data

Confirm the clientUuid header is sent and matches one of the key's selected Workspaces.