---
title: Authentication
seoTitle: "Langfuse AI Gateway API keys: user and service account keys (beta)"
description: Gateway API keys authenticate clients to the Langfuse AI Gateway. Learn the difference between user keys and service account keys, who can create them, when they stop working, and how they set the trace user.
---

# Authentication

  **Beta.** The Langfuse AI Gateway is in public beta and can still change.

Clients authenticate with the Langfuse AI Gateway by using API keys. The gateway then maps the user and its request content to organization settings, model provider API keys, and request routes. See the [Concepts page](/docs/gateway/concepts#architecture) for more detail.

## User and service account keys [#key-types]

Every key is either a user key, which belongs to the person who creates it, or a service account key, which belongs to the organization:

|                       | User key                                                              | Service account key                                                                     |
| --------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| **Use for**           | Coding agents, local development                                      | CI, shared services                                                                     |
| **Who can create it** | Any gateway user                                                      | Admins/owners                                                                           |
| **Trace user**        | The key owner's email                                                 | The client's `langfuse-user-id`, otherwise the key name. See [trace user](#trace-user). |
| **When it stops**     | When it is revoked or expires, or when its owner loses gateway access | When it is revoked or expires. Membership changes don't affect it.                      |

Both key types can call every model the organization's [provider credentials](/docs/gateway/features/models) allow.

## Create a key [#create-a-key]

1. Go to **Organization settings → AI Gateway → Gateway keys** and select **Create key**.
2. Admins and owners choose **Issued as**: **My user** or **Service account**. Other users don't see this option and always create a user key.
3. Enter a **name** that describes what uses the key, for example `Checkout agent` or `CI release pipeline`. The name is shown in the key list, and service account keys use it as the [trace user](#trace-user).
4. Optionally set an **expiration**.
5. Optionally add [**metadata**](#key-metadata) as key-value pairs.
6. Select **Create key** and copy the secret key. It's shown only once.

  ![Create gateway key dialog with the Issued as choice, name, expiration, and metadata fields](/images/docs/ai-gateway/create-key.png)

Creating and revoking a key are recorded in the [audit log](/docs/administration/audit-logs).

## Key metadata [#key-metadata]

Metadata on a key lets you segment and attribute gateway traffic. Add key-value pairs such as:

- `team: platform`
- `cost_center: 4711`
- `environment: production`

The gateway attaches them to every generation recorded with the key, under `langfuse.gateway.api_key.metadata.<key>`. Filter traces, observations, and [custom dashboard](/docs/metrics/features/custom-dashboards) charts on these keys to see usage and cost for one team, cost center, or service.

  Metadata can only be set when you create a key. To change it, issue a new key
  and revoke the old one.

## User ID [#trace-user]

The gateway sets the [trace user ID](/docs/observability/features/users) depending on the key type:

| Key type            | User ID                                                                                                                                                                                                                                                               |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| User key            | Always the owner's email, or their Langfuse user ID if the email is unknown. Clients can't override it, so a trace from a user key always shows who made the call.                                                                                                    |
| Service account key | The `langfuse-user-id` [header](/docs/gateway/features/tracing#headers) or baggage entry, so you can forward the end user's ID. Without one, the gateway uses the key name, unless the call runs inside your own trace, where the user on your spans stays in effect. |

Each generation also records these user-related metadata fields:

| Field                                    | Value                                                                     |
| ---------------------------------------- | ------------------------------------------------------------------------- |
| `langfuse.gateway.user_id_source`        | Where the user ID came from: `api_key_owner`, `client`, or `api_key_name` |
| `langfuse.gateway.api_key.id`            | The gateway key's ID                                                      |
| `langfuse.gateway.api_key.name`          | The gateway key's name                                                    |
| `langfuse.gateway.api_key.owner.user_id` | The key owner's Langfuse user ID (user keys only)                         |
| `langfuse.gateway.api_key.owner.name`    | The key owner's name (user keys only)                                     |

To attribute traces by team or cost center as well, add [key metadata](#key-metadata).

  A user key stops working as soon as its owner loses gateway access: they
  leave the organization, their role changes to one that can't call the gateway
  (for example Viewer), or they delete their Langfuse account. Service account
  keys aren't affected, so use one for shared services.

<!-- agent-instructions -->

---

## Agent Instructions

This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/docs/gateway/features/api-keys.md`.

### Querying these docs

If the answer is not on this page, query the documentation instead of guessing:

- **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question:

  ```bash
  curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?"
  ```

- **Index of every page**: <https://langfuse.com/llms.txt>, with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt).

### Before writing Langfuse code

- **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results.
- **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application.
- **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples.
- **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx @langfuse/cli api <resource> <action>`) to read or write traces, prompts, datasets, and scores from the terminal.

Found an error in these docs? Please open an issue at <https://github.com/langfuse/langfuse-docs/issues>.