# API keys

> Scoped, tenant-bound, expiring keys - the single credential type behind the REST API, MCP, and every integration.

Source: https://app.assetlab.ca/docs/manage/api-keys

Every non-human access path into AssetLab - the [REST API](/docs/reference/rest-api), [AI assistants over MCP](/docs/ai), BI pipelines, scripts - authenticates with an API key. One credential type, one management screen, one revocation story.

> [!note] API keys (and [webhooks](/docs/manage/webhooks)) are available on the Enterprise plan, or on other plans with the API keys add-on.

## Creating a key

**Settings → API Keys → New key** (Administrator only):

1. **Name it for its purpose** - "Power BI nightly", "Claude - Maria", "Migration script (temp)". Names are your audit trail's vocabulary.
2. **Pick scopes** - per-resource `:read` and `:write`, organized by category with bulk toggles, or `*:*` for full access. Full list: [Scopes reference](/docs/reference/scopes). Enabling the `users:read` scope raises a privacy confirmation first - it exposes member names and emails to whatever holds the key.
3. **Set expiry** - required; defaults to 90 days, maximum 365. Expiry is a feature: forgotten integrations die on their own instead of living forever.
4. **Copy the key** - `al_live_...` is displayed once. AssetLab stores only a hash; there is no "show me again."

## Properties worth understanding

- **Tenant-bound, permanently.** The key is minted for your organization and can never reach another. Client-supplied tenant identifiers are ignored - identity comes from the key.
- **Scopes are the ceiling.** A key without `work_orders:write` cannot create a work order, no matter what the caller (human, script, or AI) intends.
- **Rate-limited** - configurable per key from 1 to 1,000 requests/minute (default 60), with standard rate-limit headers on every response.
- **Revocation is instant.** The gateway looks the key up on every request; revoke and the next request fails. No grace period, no cached sessions.

## Using a key

```bash
curl -H "Authorization: Bearer al_live_xxxxx" \
  "https://<api-base>/v1/assets?per_page=10"
```

The API Keys screen shows the **MCP server URL** (`https://mcp.assetlab.ca`) for connecting AI assistants; the REST base URL and request details are in [REST API basics](/docs/reference/rest-api). For AI assistants, the key is pasted once during [connector authorization](/docs/ai/connect-claude).

## Lifecycle discipline

| Habit | Why |
|---|---|
| One key per consumer | Revoking Power BI shouldn't break Claude |
| Least scope | A dashboard needs `:read`; give it `:read` |
| Temp keys for temp jobs | Migration done → revoke same day |
| Calendar the expiries | Renewal is planned; expiry-surprise is an outage |
| Offboarding includes keys | Remove the user *and* revoke their keys ([checklist](/docs/manage/users-and-invitations)) |

## If a key leaks

Revoke it immediately (instant, remember), mint a replacement with the same scopes, update the consumer, and skim recent activity for anything unexpected. Because keys are per-consumer and scoped, the blast radius of one leak stays bounded - that's the payoff of the discipline above.