# Authentication

> Authenticate HubFit API requests with a secret API key sent as a bearer token. Covers creating keys, scopes, expiry and revoking.

Source: https://hubfit.com/developers/authentication

## API keys

The workspace's owner creates API keys in HubFit under **Settings > API**. A key starts with `hubfit_sk_`, belongs to one workspace and acts as the owner there. HubFit shows it once, when it's created.

A workspace can have up to 10 active keys, so give each integration its own: you can then revoke one without breaking the others. Each key expires after 30 days, 90 days (the default) or a year, or never.

> **Warning:** Store keys in an environment variable or a secret manager on your server. Never put one in client-side code, a mobile app or a public repository.

## Sending your key

Send the key in the `Authorization` header of every request, as a bearer token. A request without a valid key gets a `401` with a `WWW-Authenticate` header: `error="invalid_token"` when a key was sent but refused because it's invalid, expired or revoked, or its coach lost access.

**Authenticated request**

```bash
curl https://api.hubfit.com/v1/tags \
  -H "Authorization: Bearer $HUBFIT_API_KEY"
```

## Scopes

When you create a key, you choose what it can do. Each endpoint in the reference names the scope it needs, and a key without it gets `403 insufficient_scope`, with the missing scope in `requiredScope`. Give each key only what its integration uses.

| Scope | In Settings | Allows |
| --- | --- | --- |
| `clients:read` | Read clients | See clients, what they log, check-ins, health data, notes and purchases. |
| `clients:write` | Update clients | Add notes to clients. |
| `clients:create` | Add clients | Add clients and send them their login details, and list onboarding flows. |
| `check-ins:review` | Review check-ins | Mark check-ins reviewed, with an optional comment. |
| `messages:write` | Message clients | Send chat messages to clients. |
| `tasks:write` | Manage tasks | See, add and change your team's tasks. |
| `on-demand:write` | Manage on-demand access | List on-demand content, and give clients access to it or take it away. |
| `webhooks:write` | Manage webhooks | Add and manage webhook endpoints. |

## Rotating and revoking keys

To rotate a key, create a new one, switch your integration to it, then revoke the old one in **Settings > API**. A revoked or expired key stops working at once.

Webhook endpoints live as long as the key that made them: revoking a key, or its expiry, turns its endpoints off for good. See [Webhooks](https://hubfit.com/developers/webhooks#endpoint-lifecycle).

## AI assistants

AI assistants such as Claude and ChatGPT connect to the [HubFit MCP server](https://hubfit.com/developers/mcp) instead, signing in with HubFit. Their sign-in tokens only work on the MCP server, not this API.