API

Validate source app credentials

Confirm that an API key can access a source App ID without creating or printing an order.

Use this endpoint during integration setup to confirm that a Yuzu API key and source App ID work together.

The request is read-only. It does not create, update, ingest, render, or print an order.

Request

GET https://app.yuzu.so/api/apps/validate?appId={appId}

Send the API key in the X-API-Key header. Set appId to the UUID of the source app that supplies the merchant's orders.

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

appId must be a source app UUID. Do not send a team ID, merchant-team ID, order ID, or Shopify order ID.

A team API key can validate a source app owned by the same team.

A parent 3PL API key can also validate a source app owned by one of its managed merchant teams. It cannot validate an app owned by an unrelated team.

A valid and accessible combination returns 200 OK:

{
  "valid": true
}

Treat the integration as active only when the response is 200 and valid is true.

Status	Meaning	What to do
`400`	`appId` is missing or is not a UUID.	Check the query parameter and source App ID. Do not retry unchanged.
`401`	The API key is missing, invalid, or revoked.	Check the `X-API-Key` header or replace the key.
`403`	The key cannot access the supplied App ID.	Check that the app belongs to the key's team or a merchant managed by its 3PL team.
`500`	Yuzu could not complete the validation.	Retry with backoff. Contact Yuzu if the error continues.

The 403 response uses a generic error. It does not reveal whether an inaccessible App ID exists for another team.

Ask the merchant for a Yuzu API key and source App ID.
Call GET /api/auth/whoami to confirm which team owns the key.
Call GET /api/apps/validate with the source App ID.
Mark the connection as active only after a successful validation response.
Ask the merchant to correct the credentials after a 400, 401, or 403 response.

This endpoint validates access only. It does not list apps, return app metadata, discover an App ID, or validate an order.

Links

Match orders across sources before Yuzu merges them.

Overview

Manage merchant teams and their orders with one 3PL API key.