---
category: SDK
title: Authentication
description: "Configure API key authentication for the openstatus Node.js SDK"
---

## Recommended: createOpenStatusClient

Create a client with your API key. The key is automatically included in all requests via an interceptor.

```typescript
import { createOpenStatusClient } from "@openstatus/sdk-node";

const client = createOpenStatusClient({
  apiKey: process.env.OPENSTATUS_API_KEY,
});

// No headers needed on individual calls
const { httpMonitors } = await client.monitor.v1.MonitorService.listMonitors({});
```

## Alternative: Manual Headers

Use the default `openstatus` client and pass headers on each call.

```typescript
import { openstatus } from "@openstatus/sdk-node";

const headers = {
  "x-openstatus-key": process.env.OPENSTATUS_API_KEY,
};

await openstatus.monitor.v1.MonitorService.listMonitors({}, { headers });
```

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `OPENSTATUS_API_KEY` | Your openstatus API key | Required for authenticated calls |
| `OPENSTATUS_API_URL` | Custom API endpoint | `https://api.openstatus.dev/rpc` |

Get your API key from the [openstatus dashboard](https://app.openstatus.dev) under **Settings → General → API Keys**.

## Scopes

Each API key carries a scope that controls what it can do:

- **Read-only** (`['read']`) — list/get endpoints only. Mutations return `403 Forbidden`. Recommended for AI agents and read-only dashboards.
- **Read & write** (`['write']`) — full workspace access. Required for CI/CD and automation.

Scope is set when the key is created and is **immutable** — to change it, revoke the key and issue a new one. Existing keys created before this feature shipped continue to work as Read & write.

`GET /v1/whoami` echoes the resolved actor's scopes back so a client can introspect what it's allowed to do without probe-and-fail:

```json
{
  "name": "Acme",
  "slug": "acme",
  "plan": "team",
  "actor": {
    "type": "apiKey",
    "keyId": "42",
    "scopes": ["read"]
  }
}
```

API keys are managed from the dashboard (**Settings > General > API Keys**); there is no public REST or ConnectRPC endpoint for creating or revoking them. Internally, revocation carries one carve-out: a read-only key is allowed to revoke *itself*, so a leaked key always has a rotation path. Revoking a *different* key from a read-only actor is forbidden.

## Custom Base URL

For self-hosted instances or staging environments:

```typescript
import { createOpenStatusClient } from "@openstatus/sdk-node";

const client = createOpenStatusClient({
  apiKey: process.env.OPENSTATUS_API_KEY,
  baseUrl: "https://api.staging.example.com/rpc",
});
```

The `baseUrl` option takes precedence over the `OPENSTATUS_API_URL` environment variable.