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

# Authentication

> How authentication works, how workspace-scoped keys behave, and what to send on every request.

## Overview

Lamina's public Apps API uses **workspace-scoped API keys**.

The canonical public path is `/v1/...`.

Send the key with either:

```http theme={null}
x-api-key: lma_your_api_key
```

or:

```http theme={null}
Authorization: Bearer lma_your_api_key
```

Use `x-api-key` unless you have a reason to standardize on bearer auth across your stack.

## What The Key Grants Access To

An API key is bound to a Lamina workspace.

That means the key determines:

* which private apps can be discovered
* which executions can be started
* which execution records can be read
* which workspace context is used for authorization

When you call the Apps API with an API key, you do **not** need a JWT or cookie-based session.

## Workspace Scope

Keys are workspace-scoped, not user-scoped.

In practice this means:

* your own workspace apps are available through the key
* public apps from other workspaces may also be visible
* requests are still checked against the key's workspace context

If you send `x-workspace-id`, it must match the workspace associated with the API key.

## Example

```bash theme={null}
curl -H "x-api-key: lma_your_api_key" \
  https://app.uselamina.ai/v1/apps
```

## Security Recommendations

* Keep Lamina API keys on your server, not in browser code.
* Rotate keys if they are exposed in logs, screenshots, or commits.
* Create separate keys for staging and production.
* Prefer one key per integration so usage is easier to audit.

### Using the CLI locally

`lamina login` opens your browser for an OAuth approval flow — the same pattern used by `gh`, `supabase`, `vercel`, `firebase`. No copy-paste of secrets.

```bash theme={null}
lamina login
```

For CI / scripted callers, pass an API key non-interactively:

```bash theme={null}
lamina login --api-key lma_your_api_key
```

Either path persists credentials at `~/.lamina/config.json` (mode `0600`). OAuth access tokens auto-refresh in the background when they're near expiry; if the refresh token also expires (after 30 days), the CLI surfaces a clear "session expired" error pointing at `lamina login`.

See [Use The CLI And SDK](/guides/use-the-cli-and-sdk) for the full command reference.

## Common Authentication Errors

### `401 Missing API key`

No supported auth header was sent.

### `401 Invalid API key`

The key is malformed, revoked, or unknown.

### `403 Workspace header does not match API key workspace scope`

The request included an `x-workspace-id` value that does not match the key's workspace.

## Next Steps

* Read [Quick Start](/quick-start) to make your first request
* Read [Use The CLI And SDK](/guides/use-the-cli-and-sdk) to work from a terminal
* Read [Apps and Executions](/concepts/apps-and-executions) to understand the lifecycle
* Read [Integration Recipes](/guides/capability-recipes) for commerce, try-on, video, and media workflow patterns
* Read [Run Your First App](/guides/run-your-first-app) for a concrete end-to-end execution example