Something went wrong. Try again.
[READ-ONLY] Mirror of https://github.com/openstatusHQ/openstatus. 🫖 Status page with uptime monitoring & API monitoring as code 🫖 openstatus.dev
bun drizzle-orm monitoring monitoring-as-code nextjs observability on-call open-source shadcn-ui status-page statuspage synthetic-monitoring tinybird turso uptime uptime-checker uptime-monitor
Something went wrong. Try again.
MDX
12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485---category: SDKtitle: Authenticationdescription: "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.
```typescriptimport { createOpenStatusClient } from "@openstatus/sdk-node";
const client = createOpenStatusClient({ apiKey: process.env.OPENSTATUS_API_KEY,});
// No headers needed on individual callsconst { httpMonitors } = await client.monitor.v1.MonitorService.listMonitors({});```
## Alternative: Manual Headers
Use the default `openstatus` client and pass headers on each call.
```typescriptimport { 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:
```typescriptimport { 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.