Open-source status page, incident response and uptime monitoring
TypeScript alertingincident-managementmcpmcp-servermonitoringmonitoring-as-codeobservabilityon-callopen-sourcesrestatus-pagestatuspagesynthetic-monitoringterraformtinybirdtursouptimeuptime-checkeruptime-monitor
---
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.