Authenticate Platform API requests with a personal or service key. Use browser sign-in for the CLI and supported MCP clients, or configure a personal key when the client supports it. This reference covers credential selection, access, setup and rotation.
Choose a credential
Keep personal and service keys in server-side secrets or local development credentials. A client key is intended for the widget’s website installation code.
Personal keys
A personal key acts as your user account. Its access cannot exceed your account’s permissions. The full key is displayed once, when you create it.
- Expiry: the creation form offers 1, 7, 30, 90 or 365 days; 30 days is selected initially.
- Scoped access: when the access selector is available, choose the workspaces, projects and actions the key needs. Existing keys created without explicit scopes retain the user’s access until they expire or are deleted.
- Storage: copy the value to your secret manager before closing the confirmation dialog. A masked listing cannot recover the full value.
Create a personal key
Create a credential for API requests made on your behalf.
Open personal-key settings
Open Voiceflow and select your workspace. From the workspace dashboard, click Settings at the bottom left, then Personal keys. Click New key, or Create key if the list is empty.
Choose access and expiry
Give the key a recognizable name, such as Local development, and choose its expiry. When the access controls are available:
- Grant access to these workspaces: select the workspaces the key needs.
- Grant access to these projects: narrow access to specific projects within those workspaces.
- With these permissions: choose Read-only for inspection, Read & write for changes, or Custom for individual actions.
Click Create.
Copy the key
Copy the full value from the confirmation dialog and store it as a secret. Use it in the Authorization header or configure it for the CLI.
Service keys
A service key gives an automation its own service-account identity. An organization administrator with organization-management permission creates and deletes these keys in Settings → Service keys.
- Access: select the workspaces, projects and action permissions needed by the automation.
- Expiry: choose 1, 7, 30, 90 or 365 days, or Never. The form initially selects 30 days.
- Visibility: the full key is displayed once at creation.
- Supported clients: use service keys for Platform API requests and the CLI. For Voiceflow MCP, use OAuth or a personal key instead.
Create a service key
Give an automation selected access to organization resources.
Open service-key settings
Return to the workspace dashboard and click Settings at the bottom left. Select Service keys, immediately below Personal keys, then New key. An empty list shows Create key instead. The Service keys settings item is disabled without organization-management permission.
Set the access boundary
Name the automation, such as Release automation. Choose Grant access to these workspaces, Grant access to these projects and With these permissions for the resources and operations it needs. Set an expiry; use Never only when you intend to manage rotation yourself.
Click Create.
Store and verify the key
Copy the full value to the automation’s secret store. Make a permitted read request against the intended project before using the credential for writes.
Client keys
A client key authorizes the web widget for one project. It does not authorize Platform API resource management. You can copy its full value again from the project settings.
Find and install a client key
Use the project’s client key in your web widget installation.
Open the project’s Client key settings
Open the project that will power the widget. In its left sidebar, open Settings → Client key. You need permission to update the project’s API keys. Voiceflow creates the key on its first read if the project does not have one.
Use the generated installation code
Open Widget → Installation and copy the generated snippet. It includes the key in verify.clientKey. Add the snippet to your website and publish the change. Follow Install widget for the complete procedure.
Check the deployed widget
Open the published website and start a new conversation. Confirm that it reaches the intended Voiceflow project. This checks the installation; it does not grant Platform API management access.
Regenerating a client key invalidates the old value. Every widget using it stops working until you replace its installation code and republish the website.
Permissions
Authentication identifies the caller; authorization checks whether that identity can perform the requested action on the requested resource.
Selecting a project does not grant every operation on it. For example, listing Functions and executing a Function have separate permissions. Check the resource reference for the action you will call. See Run tools without a conversation for schema and execution access.
API requests
For Platform API requests, send the personal or service key as a Bearer token:
This read-only example lists Functions. Set VF_TOKEN from your secret store and VF_PROJECT_ID to a project the key can access. It requires Function list permission for the selected Environment.
Runtime requests have their own credential stages: Chat actions use the sessionKey returned from session creation. Read Chat credentials and the Voice connection contract for their exact authentication fields.
CLI
Sign in through the browser
Install the current Voiceflow CLI, then run:
Complete the Voiceflow sign-in opened by the CLI and return to your terminal.
Verify access to a project
Set VF_PROJECT_ID to the project you intend to use and make a permitted read request:
A successful response, including an empty list, verifies that this credential can list Functions for that project and Environment. It does not prove access to other operations.
The CLI stores the resulting access and refresh tokens in the OS keychain, with an owner-only file fallback. For CI, set VF_TOKEN to a personal or service key in your CI secret store; no interactive login is needed.
Credential priority is --token, then VF_TOKEN, then the stored OAuth session, then a static token in the OS keychain, then the configuration file. The CLI refreshes the OAuth session when needed; an explicit flag or environment variable overrides it.
- Check configuration:
vf auth whoamishows masked credential values and their source. It runs offline and does not prove that the server accepts the token or permits an operation. - Use an existing key interactively:
vf auth login --manualprompts for a Bearer token instead of opening browser sign-in. - Sign out locally:
vf auth logoutremoves the stored key and OAuth session. It does not unsetVF_TOKENin your shell or revoke a personal or service key on the server.
See the auth command reference for command options.
MCP
Add https://mcp.voiceflow.com/mcp to a supported MCP client, sign in to Voiceflow and approve the connection. Follow MCP client setup for client-specific configuration.
The server advertises the OAuth scopes universal.workspace.read and universal.workspace.write. These OAuth scope names are separate from the resource and action selections used when creating keys. Your account’s resource access still applies.
A client that supports custom Authorization headers can instead send a personal key as Authorization: Bearer <personal-key>. The current MCP authentication gate does not accept service keys. Removing the server from a client does not delete a personal key; delete it in Settings → Personal keys to revoke it.
Rotate or replace a key
For personal and service keys, create a replacement with the required access, update each consumer and verify its actual operations. Then delete the old key in its settings list. An expired or deleted key cannot authenticate requests.
Migrate a project API key
Replace a server-side project credential with a personal or service key.
Inventory the consumers
Identify the applications, CI secrets and Environments using the old value. Confirm that each endpoint accepts the replacement credential. Widget installations use client keys instead.
Create and test the replacement
Create a personal or service key with the needed resource and action access. Update a test configuration. Check for --token or VF_TOKEN values that override stored CLI credentials, then verify the actual operations in a test project.
Switch the consumers
Update every application and deployment, verify each one and then retire the old key through its existing key-management controls.
Troubleshooting
- Expired, deleted or lost key: create a replacement and update its consumers. Personal and service keys cannot be recovered from their masked listings.
- A permitted identity cannot perform an operation: check the selected resource, Environment and action permission. A successful read does not prove write or execute access.
- CLI still uses an old value: inspect
vf auth whoami, then check explicit flags andVF_TOKENbefore changing the stored credential. - Widget fails after regeneration: replace the old client key in every installation, publish each website and start a fresh conversation.