Authenticate as yourself

Create a personal key to use the API or CLI as yourself. Your account’s permissions and the key’s selected access determine what requests it can make.

Before you begin

Sign in to Voiceflow and open Settings → Personal keys. Identify the projects and actions you need. A personal key does not elevate your user account’s permissions.

Create and use a key

Open key settings

Open Settings → Personal keys and choose the create-key action. On a populated list, this is New key.

Choose access and expiry

Give the key a recognizable name. Where the access controls are available, select workspaces, projects, and permissions. Older personal keys can have unrestricted scope within your account’s access; do not assume an existing key is narrowly scoped.

Choose an expiry: one day, one week, one month, three months, or one year. Personal keys expire; there is no Never option.

Create and store the key

Submit the form and copy the key from the confirmation dialog. The full value is shown only once. Store it in your secret manager or local development environment; never commit it or include it in browser code.

Make an authenticated request

Use a read operation for a project the key can access. This example requires function read permission. Set VF_TOKEN in your shell or secret manager, and replace the project ID and environment alias:

curl --get 'https://realtime-api.voiceflow.com/v1/stable/function' \
  --header "Authorization: Bearer $VF_TOKEN" \
  --data-urlencode "projectID=$VF_PROJECT_ID" \
  --data-urlencode 'environmentAlias=main'

For CLI use, the same environment variable is supported:

vf function list --project-id "$VF_PROJECT_ID" --environment-alias main

Choose an operation your key is permitted to perform; a restricted key does not need access to list every workspace. See CLI authentication for credential precedence.

Verify access

Confirm that the read request succeeds for the intended project. If it is rejected, check the key’s permissions rather than widening access to every resource. vf auth whoami reports configured credentials; it does not validate them against the API.

Replace, revoke, and troubleshoot

Replace a key

Create a replacement with the required access, update every application using the old value, and verify those applications. Then open the old key’s options and choose Delete. Applications still using a deleted or expired key cannot authenticate with it.

The settings page is missing

Your account must have access to the settings shown in this guide. For service keys, an organization administrator with permission to manage the organization must create the key. Use only the credential options available in your account.

The request is rejected

Check that the credential has not expired or been deleted, that the header includes Bearer , and that the project and environment are correct. Then check both the selected resources and permissions. A personal key cannot grant access your account does not have. See Permissions and scopes.

You lost the key value

The full personal or service key is displayed once. Create a replacement, update the application, verify it, and delete the old key. Do not attempt to recover a value from its masked listing.