# Retrieve the workspace

> Introspect the key: which workspace it belongs to, what it may do, its rate limit, and current usage.

Source: https://getlaunchlist.com/help/docs/api/workspace

---

Answers "does this key work, and what can it do?", which makes it the first call worth making from
any new integration.

Requires the **`projects:read`** scope, the same one that grants
[projects and forms](/help/docs/api/projects). Both dashboard presets carry it, so any key you
created in the app can call this. A key that lacks it answers `403 insufficient_scope`, because
plan and usage are billing-adjacent and a key with no grants should not read them.

## What it tells you

- **`name`** and **`plan`**: which workspace the key belongs to, and its tier
- **`plan_size`** and **`billing_interval`**: the size the plan is bought at (the contacts it holds) and whether it is billed `monthly` or `yearly`. `billing_interval` is `null` without a paid subscription
- **`complimentary`**: `true` when the plan is given rather than sold. A complimentary plan has no subscription, so its `billing_interval` is `null`
- **`api_key.scopes`**: what this key may do
- **`api_key.project`**: the project it is pinned to, or `null` for the whole workspace
- **`api_key.mode`**: `live` or `test`. A test key works on test data only (see [Testing without touching your audience](/help/docs/api/openapi#testing-without-touching-your-audience)). Every response also names it in the `LaunchList-Mode` header
- **`limits`** and **`usage`**: the contacts your plan holds and your rate limit, against what you have used

## Use it as a health check

```bash
curl https://api.getlaunchlist.com/v1/workspace \
  -H "Authorization: Bearer llk_live_8xKq3Rp9Wm2Nz7Vt6yL1cG5dH0jA4sE8uNqB2fXk"
```

A `200` means the key is live and you know exactly what it can reach. A `401` means it is wrong or
revoked, and finding that out here is much better than finding it out mid-import. A `403` means the
key is valid but does not carry `projects:read`, so this endpoint cannot answer for it: fall back to
any call the key does carry a scope for.

> [!TIP] Check scopes at startup, not at first failure
> Reading `api_key.scopes` when your integration boots lets you fail with "this key needs
> contacts:write" instead of surfacing a confusing `403` hours later.

## Next

- [Authentication](/help/docs/api/authentication)
- [Rate limits](/help/docs/api/rate-limits)