Skip to main content
IntroductionBuild AgentsAgent FrontendsTest & EvaluateTelephonyRoboticsWebRTC TransportManage & DeployReferences
XYouTubeSlack

Authentication

Reference for the LiveKit CLI commands that sign in to LiveKit Cloud with your user account or a project API key.

On this page

Overview

The LiveKit CLI signs in to LiveKit Cloud with user authentication or API key authentication. User authentication uses your LiveKit Cloud account, and commands run with your role in each project. Use it for your own work in a terminal, and for work by your coding agents. API key authentication uses the API key and secret of one project, and commands run in that project only. Use it for automation that runs without you, such as CI, and for self-hosted servers. To install the CLI, see Install the CLI.

User authentication (beta)API key authentication
Use it forYour work in a terminal, and work by your coding agentsCI, servers, and other automation that runs alone, and self-hosted servers
Commands run inEach project that you can access, with your roleOne project
CredentialsA session that you renew in a browserAn API key and secret for the project
CommandsMost commands, including the commands for sessions, LiveKit Cloud projects, members, API keys, and webhooksMost commands, but not the commands for sessions, LiveKit Cloud projects, members, API keys, or webhooks

User authentication

Available in
Beta

User authentication uses your LiveKit Cloud account. Use it to read the observability data of your agent's sessions, such as transcripts, logs, traces, and metrics, and to manage LiveKit Cloud projects, members, API keys, and webhooks. These commands work only with user authentication.

User authentication requires LiveKit CLI v2.19.4 or later. To update the CLI, see Updates.

Sign in and renew

The lk cloud auth --user-auth command asks for a device name and opens a browser page for you to confirm. It stores the session in ~/.livekit/cli-config.yaml, with a list of your projects so that you can refer to them by name. It needs an interactive terminal.

lk cloud auth --user-auth

A session lasts 30 days and doesn't refresh. To renew it, sign in again.

Sign out

The lk cloud auth --revoke --user-auth command ends your session and removes it from your CLI configuration. The short-lived tokens that the CLI already got for the session stay valid until they expire. Signing out doesn't revoke the service account keys that the CLI created for your agents and apps.

lk cloud auth --revoke --user-auth

Run commands

Pass --user-auth to each command. No setting turns it on for every command. The CLI help shows the commands and options for user authentication only after you sign in.

lk project list --user-auth

A command that works with both authentication methods uses an API key when you leave out --user-auth. For example, the command lk project list --user-auth shows every LiveKit Cloud project that you can access. With API key authentication, lk project list shows only the projects in your CLI configuration.

With user authentication, the room, token, dispatch, telephony, egress, ingress, and agent deployment commands don't need an API key on your machine. For each request, the CLI gets a short-lived token for the project from the LiveKit Cloud API. A command takes its project from the --project option, or from your default project if you don't name one. Both authentication methods share one default project.

To call the LiveKit Cloud API from your own code with the same session, see Use a token in a script.

Limits

User authentication doesn't support the deployment of a prebuilt image yet. To deploy an image with the --image or --image-tar option of lk agent create or lk agent deploy, use API key authentication.

API keys for agents and apps

Your user authentication session signs in the CLI, but an agent or app needs an API key of its own. The CLI gets one for you:

  • If the .env.local or .env file of the agent or app has a key for the project, the CLI uses it.
  • Otherwise, the CLI uses a key that it saved for the project in your CLI configuration, or creates a service account key and saves it there. A service account key keeps working after you lose access to the project. To create a key, you need the Admin role. If you don't have it, the CLI asks you to enter a key.

The CLI doesn't write a key into the agent's directory when it runs the agent. Only lk agent init, lk app create, and lk app env --write write a .env file.

To run an agent with a different key, pass --api-key and --api-secret. lk agent console and lk agent debugger start the agent without a key if they don't find one, but an agent that uses LiveKit Inference needs a key.

API key authentication

API key authentication uses the API key and secret of one project. Use it for CI, servers, and other automation that runs without you, and for a self-hosted LiveKit server.

To link a LiveKit Cloud project, run lk cloud auth. The command opens a browser page to sign in to LiveKit Cloud and select one project. LiveKit Cloud creates an API key for your CLI, and the CLI adds the project to your configuration. To link more projects, run the command again.

lk cloud auth

To add a self-hosted server, or a project with an API key that you already have, use lk project add. You can also pass the credentials with the global --url, --api-key, and --api-secret options, or with the LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET environment variables. User authentication ignores these options and environment variables, except in the commands that run an agent or a simulation. To learn more, see API keys for agents and apps.

Revoke

Revoking an authorization revokes the API keys that lk cloud auth created for a project, and removes the project from your CLI configuration. To revoke a project other than the default, pass its name with --project:

lk cloud auth --revoke --project my-project

This also revokes the keys that lk agent init, lk app create, and lk app env copied into .env files with API key authentication. Agents and apps that use those keys stop working. It doesn't revoke the service account keys that these commands create with user authentication.

Command reference

These are the options for the lk cloud commands.

Sign in 

lk cloud auth [options]

Options for auth:

  • --revoke (alias -R): Revoke an authorization for an existing project, selected with --project or the default project. This revokes the API keys that were issued with lk cloud auth, and then removes the project from the CLI. With --user-auth, it signs a user out instead: the user selected with --user, or the default user. It revokes their session and removes them from the CLI. Access tokens that lk already fetched for that session stay valid until they expire.
  • --timeout SECONDS (alias -t): Number of SECONDS to attempt authentication before giving up. Default: 900.
  • --poll-interval SECONDS (alias -i): Number of SECONDS between poll requests while waiting. Default: 4.

Show the current user

Show the user that you're signed in as with user authentication.

lk cloud whoami --user-auth

Options for whoami:

  • --json (alias -j): Output as JSON.