Authentication Guide
Youzu uses an API key for server-to-server administration and short-lived bearer tokens for scoped product and feature requests.
Keep your API key on your server. Never embed it in browser code, a mobile application, or a public repository.
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- 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.
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
| Field | Required | Description |
|---|---|---|
actionResource |
Yes | Protected resource, such as product, or * for an authorised multi-feature flow |
actionType |
Yes | create, read, update, delete, or * |
catalogueId |
No for catalogue-free product reads; yes for Merchant API | Explicit catalogue scope for multi-catalogue product reads and every merchant-api token |
userReference |
No | Your stable reference for the end user; do not send personal data |
Unless you intentionally use *, actionResource and actionType are matched exactly. Generate the narrowest token needed for the next request:
| Request | actionResource |
actionType |
|---|---|---|
GET /api/v1/product or /product/{id} |
product |
read |
POST /api/v1/product/search/near-space |
product |
read |
POST /api/v1/product/user-products/{productId} |
product |
create |
DELETE /api/v1/product/user-products/{productId} |
product |
delete |
POST /api/v1/lens |
lens |
create |
POST /api/v1/object-detection |
object-detection |
create |
POST /api/v1/fill |
fill |
create |
GET /api/v1/fill or /fill/{id} |
fill |
read |
POST /api/v1/swap |
swap |
create |
GET /api/v1/swap or /swap/{id} |
swap |
read |
POST /api/v1/room-visualize |
room-visualize |
create |
GET /api/v1/room-visualize or /room-visualize/{id} |
room-visualize |
read |
POST /api/v1/property-visualize |
property-visualize |
create |
GET /api/v1/property-visualize or /property-visualize/{id} |
property-visualize |
read |
DELETE /api/v1/property-visualize/{id} |
property-visualize |
delete |
POST /api/v1/magic-background |
magic-background |
create |
GET /api/v1/magic-background or /magic-background/{id} |
magic-background |
read |
DELETE /api/v1/magic-background/{id} |
magic-background |
delete |
POST /api/v1/2d-to-3d |
2d-to-3d |
create |
GET /api/v1/2d-to-3d or /2d-to-3d/{id} |
2d-to-3d |
read |
POST /api/v1/merchant-api/identity/suggestions |
merchant-api |
suggest-identity |
POST /api/v1/merchant-api/category/suggestions |
merchant-api |
suggest-category |
POST /api/v1/merchant-api/attributes/suggestions |
merchant-api |
suggest-attributes |
POST /api/v1/merchant-api/images/suggestions |
merchant-api |
suggest-images |
POST /api/v1/merchant-api/descriptions/suggestions |
merchant-api |
suggest-descriptions |
POST /api/v1/merchant-api/assets/upload-url |
merchant-api |
asset-upload |
Merchant API requires an explicit catalogueId and a new token for each request. See Merchant API for endpoint-specific inputs and advisory response handling.
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
401means 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.
