Authentication Guide

Youzu uses an API key for server-to-server administration and Merchant API requests, and short-lived bearer tokens for scoped product and feature requests.

API key authentication

Send your customer API key in the x-client-key header:

x-client-key: YOUR_CLIENT_KEY

Use API key authentication for:

• POST /api/v1/token
• Merchant API v1 and v2 under /api/v1/merchant-api and /api/v2/merchant-api
• Catalogue management and ingestion under /api/v1/admin/catalogue
• Moderation templates under /api/v1/admin/moderation/templates
• Catalogue moderation and review under /api/v1/admin/catalogue/{catalogueId}
• Managed upload credentials at /api/v1/admin/upload/signed

The catalogue ID in an admin URL must belong to the client identified by the key. Do not send a clientId; Youzu derives it from the key.

Merchant API v1 and v2 calls use the same reusable key directly; do not mint a token for them. Bearer and x-token authentication are rejected. Include the target catalogue UUID as catalogueId in every Merchant API JSON request body. The key identifies the client, but it does not select a catalogue. Requests do not accept a clientId. Analysis requests may include a category selector within that catalogue: {"id":"<Youzu category UUID>"} or a customer slug such as {"<SLUG_KEY>":"<SLUG_VALUE>"}. Replace both slug placeholders with the exact key and value configured on the category. Supply exactly one key: either id or one configured slug key/value pair. Multiple slug pairs or an ID plus a slug return 422; id is reserved for a Youzu UUID. Slug keys are independent of catalogue languages. If no unique category matches, Gemini selects from product evidence. See Select a product category. The named catalogue must belong to the authenticated client, be enabled and ready, and support Merchant API.

Single-use bearer tokens

Product reads and storefront features use a short-lived, single-use bearer token. Generate the token on your server with the API key, return it to the caller, and use it for exactly one protected request.

POST https://platform.youzu.ai/api/v1/token
x-client-key: YOUR_CLIENT_KEY
Content-Type: application/json

{
  "actionResource": "product",
  "actionType": "read",
  "userReference": "customer-123"
}

{
  "token": "5a79b9b6f41d4e84b670c98c516e99a0...",
  "expiresIn": 300,
  "actionResource": "product",
  "actionType": "read"
}

Use the returned token in the next request:

GET https://platform.youzu.ai/api/v1/product?page=1&limit=20
Authorization: Bearer YOUR_TOKEN

For catalogue-free product reads, the API derives catalogue scope from the key. Omit catalogueId as shown above. Product requests do not accept clientId or catalogueId query parameters, and a token cannot be reused after it has been consumed. Follow Upload Product Data and Track Processing, then Check Moderation Results.

Token request fields

Unless you intentionally use *, actionResource and actionType are matched exactly. Generate the narrowest token needed for the next request:

For an asynchronous feature, the token used to create a job cannot be used to poll it. Generate a new <feature>:read token for every status request. A multi-step workflow such as object detection followed by Lens also needs one token per step, with the resource shown above.

Error handling

• 401 means the key or bearer token is missing, invalid, expired, already consumed, or outside the required scope.
• Generate a new token after any request that consumed a token, including a failed protected request.
• Admin endpoints never accept a bearer token in place of x-client-key.