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

# Authentication

> Send API keys, idempotency keys, and correlation IDs

Incarts authenticates API requests with an API key issued for your integration.

```bash theme={null}
curl "$INCARTS_API_BASE_URL/v1/links/{linkId}" \
  --header "X-Incarts-API-Key: $INCARTS_API_KEY"
```

## API key header

| Header              | Required                              | Description                                                            |
| ------------------- | ------------------------------------- | ---------------------------------------------------------------------- |
| `X-Incarts-API-Key` | Yes, except unauthenticated endpoints | Authenticates the caller and limits access to allowed projects.        |
| `Idempotency-Key`   | Recommended for writes                | Lets clients safely retry create requests without creating duplicates. |
| `X-Correlation-ID`  | Optional                              | Client-supplied request ID echoed in responses for tracing.            |

<Warning>
  Treat API keys as secrets. Do not expose them in browser code, client-side apps, screenshots, or public repositories.
</Warning>

## Where credentials come from

Incarts issues API keys through the dashboard. Each key is tied to an organization, a project
access policy, and a set of scopes:

| Value       | Purpose                                                                                               |
| ----------- | ----------------------------------------------------------------------------------------------------- |
| `projectId` | Identifies which Incarts project owns created links and QR codes.                                     |
| API key     | Authenticates your server and grants access to selected projects or all projects in its organization. |

Pass the API key in `X-Incarts-API-Key` and the `projectId` in request bodies that create project-owned resources.
If the key does not have access to that project, the API returns `403`.

<Card title="Get API access" icon="badge-check" href="/access">
  See the current onboarding flow for project IDs, API keys, and scopes.
</Card>

## API scopes

API keys are project-scoped and need operation-specific scopes such as `links:write`, `links:read`, and `qr-codes:write`. Retailer-specific writes also need the matching retailer scope. Project access never crosses the organization that owns the API key.

Request the smallest useful scope set for what you're building. A Walmart-only link creator usually needs:

```text theme={null}
links:write
retailers:walmart
```

Use `retailers:amazon`, `retailers:kroger`, `retailers:target`, `retailers:instacart`, or
`retailers:custom` for those providers. Add `links:read` only when you need to retrieve links after
creation, and `qr-codes:write` when you create additional QR codes.

## Idempotent writes

Use a stable `Idempotency-Key` when creating links or QR codes. If a network retry happens, reuse the same key for the same logical operation.

```bash theme={null}
curl --request POST "$INCARTS_API_BASE_URL/v1/links" \
  --header "Content-Type: application/json" \
  --header "X-Incarts-API-Key: $INCARTS_API_KEY" \
  --header "Idempotency-Key: link-create-20260521-001" \
  --data '{ "...": "..." }'
```

## Correlation IDs

Pass `X-Correlation-ID` when you want to align client logs with API logs.

```bash theme={null}
curl "$INCARTS_API_BASE_URL/v1/links/lnk_01JZ4TDK6A0NV2HG6R3Q7E28Y9" \
  --header "X-Incarts-API-Key: $INCARTS_API_KEY" \
  --header "X-Correlation-ID: req_01JZ4TCZ7AG9P9W38V4VNQ7W4B"
```