# Authentication

Create and manage API keys in
[LegitGrails integration settings](https://account.legitgrails.com/settings/integrations).
Send the API key as a bearer credential on every LegitGrails API request:

```http
Authorization: Bearer <api-key>
```

For example:

```bash
export LEGITGRAILS_BASE_URL="https://api.legitgrails.com/v1/integrations"
export LEGITGRAILS_API_KEY="<api-key>"

curl --fail-with-body --silent --show-error \
  "$LEGITGRAILS_BASE_URL/catalog/categories" \
  --header "Authorization: Bearer $LEGITGRAILS_API_KEY"
```

Use the key only from a trusted backend; do not put it in a URL, request body,
cookie, browser application, or mobile binary.

## Environments

Choose the environment when creating an API key. Every key belongs to exactly
one environment:

| Environment | Use |
| --- | --- |
| Live | Create and manage live orders. |
| Test | Build and validate an integration without creating live orders. |

Both environments use the same base URL:

```text
https://api.legitgrails.com/v1/integrations
```

The API processes each request in the environment assigned to its API key. To
change environments, change the key, not the base URL.

Order creation has one environment-specific body field. A Test key requires
`mock_outcome` to select the simulated result; a Live key rejects that field.
See [Test orders](/orders#test-and-live-orders) for the supported values.

## Scopes

Grant only the scopes each service needs:

| Scope | Access |
| --- | --- |
| `orders:read` | List and retrieve orders; read the catalog. |
| `orders:write` | Upload photos, create orders, submit updated photos; read the catalog. |
| `balance:read` | Read `GET /balance`. |
| `webhooks:manage` | Create, list, and delete webhook endpoints. |
| `audit:read` | Read account audit events from `GET /audit/events`. |

Catalog routes accept either `orders:read` or `orders:write`. Other order reads
and writes require their corresponding scope; `orders:write` does not grant
general order-read access. Each operation's required scope is shown in the
[API Reference](/api).

## `401` and `403` responses

| Status | Meaning | Check |
| --- | --- | --- |
| `401 Unauthorized` | Credentials were missing or rejected. | Check the Authorization header and API key. |
| `403 Forbidden` | The request is not authorized for this operation. | Check the operation's required scope. |

Error responses include a `request_id`, also returned in the `X-Request-Id`
header. Record it when contacting support, but never record the Authorization
header. See [Errors](/errors) for the response format.

## Protect and rotate keys

- Store new credentials directly in a secrets manager or injected server
  configuration.
- Redact `Authorization` from logs, traces, crash reports, and support files.
- Use separate, least-privilege keys for each environment and service.
- Revoke a key in [integration settings](https://account.legitgrails.com/settings/integrations)
  immediately after confirmed exposure.

For a planned rotation, deploy and verify the replacement before revoking the
old key.

Continue with [Integration setup](/integration-setup) or browse the
[API Reference](/api).