API keys

Overview

The API key endpoints manage the credentials for a project. An API key and its secret let your own server sign access tokens, which clients use to join rooms. You can also skip the secret and have LiveKit create a token for you.

A project has the following kinds of key. They grant the same full access to the project, and differ only in who owns them:

A personal key belongs to the member who generated it. When you generate a key, you get a personal key by default.
A service account key has no owner. Set isServiceAccount to true when you generate it.
An agent key belongs to a cloud agent. LiveKit creates these for you, and listing keys leaves them out unless you set includeAgentKeys.

Key ownership determines what happens when someone loses access. Removing a member revokes the personal keys they own, but service account and agent keys remain valid. Use a service account key for a production server, CI, or anything else that must keep running after a person leaves. To learn more, see Project members.

When you generate a key, the response includes the secret only once. Store it right away. To replace a lost secret, delete the key and generate another. To list the keys of one member, set ownerId to their user ID.

When you create a token, LiveKit signs it with the oldest key of the project that isn't an agent key. If the project has no such key, the request returns 400. A token lasts 10 minutes by default, and 24 hours at most.

Listing, generating, and deleting keys need the Admin role on the project.

To create a token, your role must permit every grant in the request. When the grants need different roles, you need the highest one:

Grants	Required role
Inference	Read
Room, room management, agent dispatch, agent endpoint, agent thread, SIP, and simulation	Write
Recording, ingress, `agent.admin`, `agent.databaseAdmin`, and observability	Admin

To call these endpoints from the CLI, use the lk project key commands, for example lk project key list --user-auth. The lk token create --user-auth command creates a token the same way.

The access key object

The metadata of a project API key. A list never includes the secret. Only GenerateKey returns it.

apiKeystring

The API key ID (API...). The secret is returned only when the key is generated.

createdAttimestamp

When the key was generated.

updatedAttimestamp

When the key was last changed.

descriptionstring

A label for the key.

ownerIdstring

The user who owns the key. Empty for a key with no owner, such as a service account key.

ownerEmailstring

The email address of the owner. Empty for a key with no owner.

agentIdstring

The cloud agent that the key belongs to. Set only for agent keys.

The access key object

{
  "apiKey": string,
  "createdAt": timestamp,
  "updatedAt": timestamp,
  "description": string,
  "ownerId": string,
  "ownerEmail": string,
  "agentId": string
}

List keys

GET

/v0/projects/{projectId}/keys

Lists the API keys of a project, oldest first. The list does not include the secrets.

Returns a list of AccessKey objects, with a pageInfo cursor.

Path parameters

projectId

Required

string

The project ID (p_...).

Query parameters

includeAgentKeysboolean

When true, the list includes the keys of cloud agents. By default, the list does not include them.

page.cursorstring

The cursor of the page to return: the nextCursor of the previous page. When empty, the list starts at the first item.

page.pageSizeint32

The maximum number of items to return. When 0, the list uses its default page size.

ownerIdstring

The ID of a user. Returns only the keys that this user owns. When empty, returns the keys of every owner and the keys with no owner.

Request

curl -X GET "https://beta-api.livekit.cloud/v0/projects/${PROJECT_ID}/keys" \
  -H "Authorization: Bearer $LIVEKIT_SESSION_TOKEN"

Response

{
  "items": [
    {
      "apiKey": "APIeU7rRlbo7Xp1",
      "createdAt": "2025-11-04T15:02:11Z",
      "updatedAt": "2025-11-04T15:02:11Z",
      "description": "Server-side token minting",
      "ownerId": "",
      "ownerEmail": "",
      "agentId": ""
    }
  ],
  "pageInfo": {
    "nextCursor": "",
    "hasMore": false
  }
}

Generate key

POST

/v0/projects/{projectId}/keys

Creates an API key and secret for the project. The response includes the secret. You cannot read the secret again.

Path parameters

projectId

Required

string

The project ID (p_...).

Request body

descriptionstring

A label for the key.

isServiceAccountboolean

When true, the key has no owner, and it belongs to the project. ListKeys with an ownerId does not return it, and it stays when the user who created it leaves the project.

Response fields

apiKeystring

The apiKey value.

secretstring

The secret value.

Request

curl -X POST "https://beta-api.livekit.cloud/v0/projects/${PROJECT_ID}/keys" \
  -H "Authorization: Bearer $LIVEKIT_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Server-side token minting",
    "isServiceAccount": true
  }'

Response

{
  "apiKey": "APIeU7rRlbo7Xp1",
  "secret": "Xk7pQ2mRvN9wLz4tYb8sHc3jFd6gKe1aUq5oWi0rEn"
}

Delete key

DELETE

/v0/projects/{projectId}/keys/{apiKey}

Path parameters

projectId

Required

string

The project ID (p_...).

apiKey

Required

string

The API key ID (API...).

Request

curl -X DELETE "https://beta-api.livekit.cloud/v0/projects/${PROJECT_ID}/keys/${API_KEY}" \
  -H "Authorization: Bearer $LIVEKIT_SESSION_TOKEN"

Response

{}

Create token

POST

/v0/projects/{projectId}/tokens

Creates a short-lived LiveKit access token for the project. The API signs the token, so a signed-in user can call the LiveKit server APIs, such as rooms, SIP, and egress, or join a room without an API secret.

Path parameters

projectId

Required

string

The project ID (p_...).

Request body

grantsTokenGrants

The grants of the token. Your project role must cover every grant that you request.

To learn more, see TokenGrants.

ttlSecondsinteger

The token lifetime, in seconds. 0 means the default, 10 minutes. The maximum is 86400 (24 hours). A larger value returns InvalidArgument.

Response fields

tokenstring

The signed JWT. Depending on the grants, send it as Authorization: Bearer to the server APIs of the project, or use it to join a room.

expiresAttimestamp

The expiresAt value.

Request

curl -X POST "https://beta-api.livekit.cloud/v0/projects/${PROJECT_ID}/tokens" \
  -H "Authorization: Bearer $LIVEKIT_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "grants": {
      "identity": "caller-4821",
      "name": "Alex Rivera",
      "video": {
        "room": "support-4821",
        "roomJoin": true,
        "canPublish": true,
        "canSubscribe": true
      }
    },
    "ttlSeconds": 3600
  }'

Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiQWxleCBSaXZlcmEiLCJ2aWRlbyI6eyJyb29tIjoic3VwcG9ydC00ODIxIiwicm9vbUpvaW4iOnRydWUsImNhblB1Ymxpc2giOnRydWUsImNhblN1YnNjcmliZSI6dHJ1ZX0sImlzcyI6IkFQSWVVN3JSbGJvN1hwMSIsImV4cCI6MTc2ODQ0NDIxNSwibmJmIjoxNzY4NDQwNjE1LCJzdWIiOiJjYWxsZXItNDgyMSJ9._NP884k2BSh6VMYuOSOVjchU87rVN1TP8zHP1pUQ7PU",
  "expiresAt": "2026-01-15T02:30:15Z"
}

Types

Types used by these endpoints, alongside the access key object.

Agent

The permissions for the agent server API.

adminboolean

Create, update, and delete cloud agents.

simulationAdminboolean

Manage the simulations and scenarios that evaluate an agent.

databaseAdminboolean

Reach the agent databases of the project.

dispatchAdminboolean

Manage the agent dispatch queue of the project.

AgentEndpoint

The permission to call the non-public HTTP endpoints of an agent.

callboolean

Call the endpoints.

agentNamestring

The name of one agent. When empty, the grant applies to every agent of the project.

deploymentstring

One deployment of the agent. When empty, the grant applies to every deployment.

AgentThread

The permissions of a thread token. The token can list and create threads in scope. It can read, write, and delete the threads in threadIds, for example for a frontend that shows one conversation. When all is true, the token can act on every thread of the project. The action flags still apply.

scopestring

The scope the list and create permissions apply to.

threadIdsArray<string>

The threads the read, write, and delete permissions apply to.

listboolean

List the threads in scope.

createboolean

Create a thread in scope.

writeboolean

Write the threads in threadIds.

readboolean

Read the threads in threadIds.

deleteboolean

Delete the threads in threadIds.

allboolean

Extend the read, write, and delete permissions to every thread of the project.

Inference

performboolean

Every inference feature: LLM, STT, and TTS.

Observability

writeboolean

Publish observability data.

Sip

The permissions for the SIP server API.

adminboolean

Every SIP feature.

callboolean

Make outbound SIP calls.

TokenGrants

The claims of a LiveKit access token. The field names match the JSON claims of the token, so the claims JSON of a token is a valid TokenGrants.

identitystring

The identity of the participant: the subject of the token.

namestring

The display name of the participant.

kindstring

The kind of participant: standard, ingress, egress, sip, or agent.

kindDetailsArray<string>

The kindDetails value.

videoVideo

Room and participant permissions.

To learn more, see Video.

sipSip

SIP server API permissions.

To learn more, see Sip.

agentAgent

Agent server API permissions.

To learn more, see Agent.

inferenceInference

Inference permissions.

To learn more, see Inference.

observabilityObservability

Observability permissions.

To learn more, see Observability.

roomConfigRoomConfiguration

The configuration of a room that this participant creates when it joins, with its agent dispatches.

To learn more, see RoomConfiguration.

roomPresetstring

The name of a LiveKit Cloud room configuration preset. The fields in roomConfig override it.

metadatastring

Metadata carried on the participant.

attributesMap<string, string>

Attributes carried on the participant.

agentEndpointAgentEndpoint

Permission to call an agent's non-public HTTP endpoints.

To learn more, see AgentEndpoint.

agentThreadAgentThread

Agent thread permissions.

To learn more, see AgentThread.

Video

The room and participant permissions.

roomCreateboolean

When true, the token can create rooms with the server API.

roomListboolean

When true, the token can list rooms with the server API.

roomRecordboolean

When true, the token can start and manage egress with the server API.

roomAdminboolean

When true, the token can manage room with the server API. When room is empty, the token can manage every room.

roomJoinboolean

When true, the participant can join room.

roomstring

The room the join and admin permissions apply to. Required when either is set.

canPublishboolean

When true, the participant can publish tracks. Unset means true.

canSubscribeboolean

Subscribe to tracks. Unset means allowed.

canPublishDataboolean

Publish data to the room. Unset means allowed.

canPublishSourcesArray<string>

The sources that the participant can publish, such as camera and microphone.

canUpdateOwnMetadataboolean

Update the participant's own metadata. Unset means allowed.

ingressAdminboolean

When true, the token can manage ingress with the server API.

hiddenboolean

Hide the participant from the others in the room.

recorderboolean

Tell the room the participant is a recorder.

agentboolean

canSubscribeMetricsboolean

Subscribe to metrics.

canManageAgentSessionboolean

Manage an agent session through RemoteSession.

destinationRoomstring

The room to move or forward participants to.

Overview

The access key object

List keys

Generate key

Delete key

Create token

Types

Agent

AgentEndpoint

AgentThread

Inference

Observability

Sip

TokenGrants

Video

Ask LiveKit

Keep in touch