Authentication

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 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.

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. 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:

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.

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"

Get started

Core workflows

In development

API key header

Where credentials come from

Get API access

API scopes

Idempotent writes

Correlation IDs

​API key header

​Where credentials come from

Get API access

​API scopes

​Idempotent writes

​Correlation IDs

API key header

Where credentials come from

API scopes

Idempotent writes

Correlation IDs