Authentication

Send API keys, idempotency keys, and correlation IDs

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

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.

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

Where credentials come from

Incarts issues API keys during onboarding. Each key is tied to a project 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 a specific project.

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.

Get API access

See the current onboarding flow for project IDs, API keys, and scopes.

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.

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

links:write
retailers:walmart

Add retailers:custom for custom URL links, retailers:instacart for Instacart links, and links:read only when you need to retrieve links after creation.

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.

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.

curl "$INCARTS_API_BASE_URL/v1/links/lnk_01JZ4TDK6A0NV2HG6R3Q7E28Y9" \
  --header "X-Incarts-API-Key: $INCARTS_API_KEY" \
  --header "X-Correlation-ID: req_01JZ4TCZ7AG9P9W38V4VNQ7W4B"