Authentication

The Yuzu API uses the X-API-Key header for authentication.

Create an API key

1. Open Settings > API Keys.
2. Click Create API Key.
3. Give the key a clear name, such as warehouse-sync-production.
4. Copy the secret before closing the confirmation screen.

Yuzu only shows the full key once. If the secret is lost, revoke it and create a new key.

Send the key

Include the key with every API request:

X-API-Key: YOUR_API_KEY

curl 'https://app.yuzu.so/api/orders' \
  --header 'X-API-Key: YOUR_API_KEY'

Verify a key

Call the identity endpoint before sending orders. It confirms which team the key belongs to.

GET https://app.yuzu.so/api/auth/whoami

curl 'https://app.yuzu.so/api/auth/whoami' \
  --header 'X-API-Key: YOUR_API_KEY'

{
  "authMethod": "api-key",
  "teamId": "org_exampleTeam123456789",
  "teamSlug": "example-team",
  "version": "2.12.0"
}

For a 3PL integration, teamId should be the parent 3PL team, not one of its managed merchant teams.

Validate a key and source App ID

GET /api/auth/whoami confirms which team owns a key. It does not confirm that the key can access a specific source app.

Use GET /api/apps/validate to validate the key and source App ID together. The check is read-only and does not require an order ID.

curl 'https://app.yuzu.so/api/apps/validate?appId=73ecf92c-4aaa-4abe-a8e9-f2986a5ee2a6' \
  --header 'X-API-Key: YOUR_API_KEY'

A parent 3PL key can validate apps owned by its managed merchant teams. A standard team key can validate apps owned by its own team.

Handling keys

Store API keys in your server-side secret manager. Do not expose them in browser code, mobile apps, public repos, logs, or support screenshots.

Use separate keys for development and production so you can rotate one environment without breaking the other.

Common auth errors