---
title: Authentication
description: Authenticate API requests using Bearer tokens. Learn about API key scopes and security best practices.
section:
  title: API Reference
  order: 6
order: 2
lastUpdated: 2026-02-14
---

All API requests require authentication using a Bearer token in the `Authorization` header.

## Header Format

Include your API key in the `Authorization` header with the `Bearer` prefix:

```
Authorization: Bearer uptime_xxxx...
```

## Getting an API Key

Create API keys from your team settings. See [Managing API Keys](/docs/team/api-keys) for instructions on creating, viewing, and revoking keys.

## Example Requests

### cURL

```bash
curl https://uptime.sergiodxa.com/api/v1/monitors \
  -H "Authorization: Bearer uptime_your_api_key"
```

### JavaScript (fetch)

```javascript
const response = await fetch("https://uptime.sergiodxa.com/api/v1/monitors", {
	headers: {
		Authorization: "Bearer uptime_your_api_key",
	},
});
```

## Scopes

API keys have scopes that control which resources they can access. When creating a key, select only the scopes your integration requires.

### Available Scopes

| Scope                | Description                                           |
| -------------------- | ----------------------------------------------------- |
| `monitors:read`      | View monitors and their check results                 |
| `monitors:write`     | Create and update monitors                            |
| `monitors:delete`    | Delete monitors                                       |
| `alerts:read`        | View alert channels and notification history          |
| `alerts:write`       | Create, update, and delete alert channels             |
| `status-pages:read`  | View status pages and incidents                       |
| `status-pages:write` | Create, update, and delete status pages and incidents |
| `maintenance:read`   | View maintenance windows                              |
| `maintenance:write`  | Create, update, and delete maintenance windows        |
| `team:read`          | View team members and invites                         |
| `team:write`         | Manage team members and send invites                  |
| `api-keys:read`      | View API keys (not the secret values)                 |
| `api-keys:write`     | Create and revoke API keys                            |

Requests that require a scope your key doesn't have return a `403 Forbidden` error.

## Challenges And Discovery

Every `401` and `403` carries a `WWW-Authenticate` header with a `Bearer` challenge. Its
`resource_metadata` parameter points at the API's
[RFC 9728](https://www.rfc-editor.org/rfc/rfc9728) metadata, which lists every scope a key can
hold:

```
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer scope="monitors:write", error="insufficient_scope", resource_metadata="https://uptime.sergiodxa.com/.well-known/oauth-protected-resource/api/v1"
```

A request without a key gets the challenge with no `error`; an unknown, expired or revoked key
adds `error="invalid_token"`, and a key missing a scope adds `error="insufficient_scope"` with
the `scope` it needs. The metadata at
`https://uptime.sergiodxa.com/.well-known/oauth-protected-resource/api/v1` needs no key.

## Key Expiration

API keys can have an optional expiration date. Once expired, requests using that key return a `401 Unauthorized` error. Set expiration dates for keys used for temporary integrations or time-limited access.

## Security Best Practices

Follow these guidelines to keep your API keys secure:

- **Never commit keys to source control** - Add `.env` files to `.gitignore` and use secrets management in CI/CD
- **Use environment variables** - Store keys in environment variables rather than hardcoding them
- **Use minimal scopes** - Only grant the scopes your integration actually needs
- **Rotate keys periodically** - Create new keys and revoke old ones on a regular schedule
- **Set expiration dates** - For temporary access or contractor integrations, always set an expiration date
- **Audit key usage** - Regularly review which keys exist and revoke any that are no longer needed