Authenticate an automation

Create a service key for ongoing API or CLI automation. It uses a separate service-account identity, with access selected when you create the key.

Before you begin

You need permission to manage your organization and access to Settings → Service keys. Decide which workspaces, projects, and actions the automation needs. Key management happens in the Voiceflow GUI.

Create and use a key

Open key settings

Open Settings → Service 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. Choose Grant access to these workspaces, Grant access to these projects, and With these permissions. Select only the resources and actions your automation needs.

Choose an expiration date. Service keys also offer Never; use an expiry appropriate to your automation and plan replacement before it lapses.

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.