> ## Documentation Index
> Fetch the complete documentation index at: https://docs.antsfield.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate API requests with workspace API keys and scoped permissions.

All Retrac API requests must use **HTTPS**. Unencrypted HTTP is not supported.

## API keys

Create keys under **Settings → API Keys** in your workspace. Each key is tied to the user who created it and inherits that user's workspace role and location access.

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

<Warning>
  API keys are shown **once** at creation. Store them in a secrets manager or environment variable. Never commit keys to source control, client-side code, or public repositories.
</Warning>

## Key types

| Type            | Prefix      | Workspace ID                                            | Scopes                                |
| --------------- | ----------- | ------------------------------------------------------- | ------------------------------------- |
| **Full access** | (no prefix) | Required on every request via `workspaceId` query param | All permissions your user role allows |
| **Restricted**  | `retrac_`   | Embedded in the key — omit `workspaceId`                | Only scopes you select at creation    |

Restricted keys are recommended for integrations. Grant the **minimum scopes** needed.

## Scopes

Restricted keys use space-separated scopes. Presets in the dashboard map to:

| Preset         | Scopes        | Use when                                                       |
| -------------- | ------------- | -------------------------------------------------------------- |
| **All access** | `apis.all`    | Trusted server-side integrations needing full inventory access |
| **Read only**  | `apis.read`   | Reporting, dashboards, sync-from-Retrac jobs                   |
| **Restricted** | Custom subset | Principle of least privilege                                   |

Individual resource scopes:

| Scope                                  | Allows                                                            |
| -------------------------------------- | ----------------------------------------------------------------- |
| `items.read` / `items.write`           | List and manage catalog items                                     |
| `tags.read` / `tags.write`             | List and manage tags                                              |
| `locations.read` / `locations.write`   | List and manage locations (`write` is owner-only)                 |
| `inventory.read` / `inventory.write`   | Read balances/movements; set on-hand stock                        |
| `transfers.read` / `transfers.write`   | List and create transfers; owners may revert                      |
| `workspaces.read` / `workspaces.write` | Read workspace metadata; update workspace (`write` is owner-only) |

A restricted key cannot exceed what your workspace **role** allows. For example, a member cannot use a key with `locations.write` if their role does not include that permission.

## Workspace ID

Full-access keys must pass `workspaceId` on every workspace-scoped request:

```bash theme={null}
https://api.retrac.co/items?workspaceId=YOUR_WORKSPACE_ID
```

Find the workspace ID under **Settings → General**.

Restricted keys (`retrac_…`) are bound to one workspace — do not pass `workspaceId`; the server resolves it from the key.

## Session authentication

Dashboard session cookies are **not** documented here and should not be used for third-party integrations. Use API keys for programmatic access.

## Plan requirements

API keys are available on **Business** plans and above. Lower plans may receive `403` responses when creating or using keys.