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

# Authentication

> How to authenticate with the DevHelm API — API keys, token formats, headers, and per-surface setup for CLI, SDKs, Terraform, and CI/CD

## API keys

All DevHelm API requests require a Bearer token in the `Authorization` header. API keys use the `dh_live_` prefix and are scoped to your organization.

```bash theme={null}
Authorization: Bearer dh_live_xxxxxxxxxxxxxxxx
```

### Creating an API key

1. Open the [DevHelm Dashboard](https://app.devhelm.io)
2. Navigate to **Settings → API Keys**
3. Click **Create API Key** and give it a descriptive name
4. Copy the key immediately — it won't be shown again

### Required headers

REST API requests authenticated with an API key need a single header:

| Header          | Description                    | Example                    |
| --------------- | ------------------------------ | -------------------------- |
| `Authorization` | Bearer token with your API key | `Bearer dh_live_abc123...` |

```bash theme={null}
curl https://api.devhelm.io/api/v1/monitors \
  -H "Authorization: Bearer $DEVHELM_API_TOKEN"
```

<Note>
  API keys are scoped to a single organization and workspace, so the key itself
  carries that context — no extra headers needed. The `x-phelm-org-id` /
  `x-phelm-workspace-id` headers only apply to session (JWT) tokens like the
  ones the dashboard uses, where one user can belong to multiple organizations.
</Note>

***

## Per-surface setup

### CLI

The CLI resolves your API token from (in order of priority):

1. `--api-token` flag
2. `DEVHELM_API_TOKEN` environment variable
3. Saved context in `~/.devhelm/contexts.json` (set via `devhelm auth login`)

```bash theme={null}
# Option A: environment variable
export DEVHELM_API_TOKEN=dh_live_xxxxxxxx
devhelm monitors list

# Option B: saved context
devhelm auth login
```

See [CLI Authentication](/cli/authentication) for details on contexts and interactive login.

### TypeScript SDK

```typescript theme={null}
import { Devhelm } from "@devhelm/sdk";

const client = new Devhelm({
  token: process.env.DEVHELM_API_TOKEN,
});
```

See [TypeScript SDK quickstart](/sdk/typescript/quickstart) for full setup.

### Python SDK

```python theme={null}
import os
from devhelm import Devhelm

client = Devhelm(token=os.environ["DEVHELM_API_TOKEN"])
```

See [Python SDK quickstart](/sdk/python/quickstart) for full setup.

### Terraform Provider

```hcl theme={null}
provider "devhelm" {}
# Reads token from DEVHELM_API_TOKEN env var.
# All four provider attributes (token, base_url, org_id, workspace_id) have
# DEVHELM_* env var equivalents and are optional.
```

See [Terraform provider overview](/mac/terraform/overview) for full setup.

### GitHub Action

```yaml theme={null}
- uses: devhelmhq/setup-devhelm@v1
  with:
    api-token: ${{ secrets.DEVHELM_API_TOKEN }}
```

See [GitHub Actions integration](/mac/ci-cd/github-actions) for workflow examples.

### MCP Server

```json theme={null}
{
  "mcpServers": {
    "devhelm": {
      "command": "uvx",
      "args": ["devhelm-mcp-server"],
      "env": {
        "DEVHELM_API_TOKEN": "dh_live_xxxxxxxx"
      }
    }
  }
}
```

See [MCP server configuration](/sdk/mcp/configuration) for transport modes and advanced setup.

***

## Security best practices

<AccordionGroup>
  <Accordion title="Use environment variables, never hardcode tokens">
    Store API keys in your CI/CD secrets manager or `.env` files that are gitignored. Never commit tokens to version control.
  </Accordion>

  <Accordion title="Rotate keys periodically">
    Create a new API key, update your environment, then revoke the old one. This can be done with zero downtime.
  </Accordion>

  <Accordion title="Use separate keys for CI and local development">
    Create dedicated API keys for each environment. This makes it easier to audit usage and revoke keys if compromised.
  </Accordion>

  <Accordion title="Use separate keys per environment">
    Create dedicated API keys for production and staging. This makes it easier to audit usage and revoke keys if one is compromised.
  </Accordion>
</AccordionGroup>

***

## Error responses

| Status             | Meaning                                | Common cause                                                         |
| ------------------ | -------------------------------------- | -------------------------------------------------------------------- |
| `401 Unauthorized` | Missing, invalid, or revoked API key   | Check that your token starts with `dh_live_` and hasn't been revoked |
| `403 Forbidden`    | Valid key but insufficient permissions | The key doesn't have access to the requested organization            |

```json theme={null}
{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or revoked API key",
  "timestamp": 1712956800000
}
```

## Next steps

<CardGroup cols={2}>
  <Card title="API keys management" icon="key" href="/platform/api-keys">
    Create, rotate, and scope API keys.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Create your first monitor in under 5 minutes.
  </Card>
</CardGroup>