> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Service keys

> 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.

## 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

<Steps>
<Step title="Open key settings">

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

</Step>
<Step title="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.

</Step>
<Step title="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.

</Step>
<Step title="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:

```sh
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:

```sh
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](/docs/cli/authentication) for credential precedence.

</Step>
</Steps>

## 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.

<a id="the-settings-page-is-missing"></a>

<Accordion title="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.

</Accordion>

<a id="the-request-is-rejected"></a>

<Accordion title="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](/docs/developers/authentication/permissions).

</Accordion>

<a id="you-lost-the-key-value"></a>

<Accordion title="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.

</Accordion>