# API Authentication

> Send an API key as a Bearer token or refresh an OAuth access token, pick the right base URL, and read the one error shape every endpoint returns.

All API requests require authentication via an API key or access token.

> Looking for the full endpoint catalog? See the interactive [API Reference](/docs/api/reference/), generated from the live API definitions.

## API Keys

Generate an API key from **Settings → API Keys** in the web app. Include it as a Bearer token:

```bash
curl -H "Authorization: Bearer <api-key>" \
  https://api.hyperfile.io/fs
```

## Access Tokens

If you're building an integration that uses the OAuth flow, you'll receive access and refresh tokens. Access tokens expire after 15 minutes and must be refreshed.

## Base URL

| Environment | URL |
|---|---|
| Production | `https://api.hyperfile.io` |
| Staging | `https://api.staging.hyperfile.io` |

## Error Responses

All errors return a consistent JSON structure:

```json
{
  "error": {
    "message": "Human-readable description",
    "code": "machine_readable_code",
    "status": 401
  }
}
```

### Common Error Codes

| Code | Status | Description |
|---|---|---|
| `auth_missing` | 401 | No authorization header |
| `auth_invalid` | 401 | Invalid or expired token |
| `forbidden` | 403 | Insufficient permissions |
| `not_found` | 404 | Resource not found |
| `validation` | 422 | Invalid request body |

---

Canonical HTML version: https://hyperfile.io/docs/api/