Copy page

LegitGrails API

Authentication

Create and manage API keys in LegitGrails integration settings. Send the API key as a bearer credential on every LegitGrails API request:

Code
Authorization: Bearer <api-key>

For example:

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

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

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 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 immediately after confirmed exposure.

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

Continue with Integration setup or browse the API Reference.