Authentication Guide

SECURITY NOTE: The Secret Key should never be used in front-end applications. Always keep your Secret Key secure on your server-side application and make API calls from your backend services only.

Overview

Youzu uses two types of authentication:

Secret Key Authentication - Uses x-client-secret header for platform identification
Token Authentication - Uses short-lived bearer tokens generated with your API key

Authentication Options

You have two options for authenticating API requests:

Option 1: Secret Key (x-client-secret)

The x-client-secret header can be used to authenticate all API routes, including both admin routes and non-admin routes.

x-client-secret: YOUR_CLIENT_SECRET

Option 2: Token (non-admin routes only)

For non-admin routes, you can use a token in the Authorization header instead of x-client-secret. Tokens are useful when you want to limit access scope and duration.

Token works on: /api/v1/lens, /api/v1/fill, /api/v1/swap, /api/v1/room-visualize, /api/v1/magic-background, /api/v1/2d-to-3d, etc.

Token does NOT work on: /api/v1/admin/* routes (catalogue management, etc.)

Authorization: Bearer YOUR_TOKEN

Note: Admin routes always require x-client-secret regardless of whether you have a valid token.

Generating Authentication Tokens

Important: Tokens can be either ONE_TIME (single-use, expires immediately after first use) or SESSION (multi-use, configurable duration). ONE_TIME tokens are ideal for single API calls, while SESSION tokens are useful for multiple requests within a session. SESSION tokens expire after a configurable duration (default 5 minutes, maximum 24 hours).

For endpoints that require token authentication, you must first generate a token using your API key.

POST https://platform.youzu.ai/api/v1/token
x-client-secret: {your-client-key}
Content-Type: application/json

{
  "actionResource": "*",
  "actionType": "*",
  "userReference": "user-reference-id-from-sso",
  "catalogueId": "cat_abc123",
  "type": "ONE_TIME"
}

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 300,
  "actionResource": "*",
  "actionType": "*"
}

The token field contains a single-use token valid for the specified action resource and type. The expiresIn field shows the time-to-live in seconds.

Token Request Parameters

Parameter	Type	Required	Description
`actionResource`	String	Yes	Resource name. Options: `lens`, `object-detection`, `2d-to-3d`, `fill`, `swap`, `room-visualize`, `property-visualize`, `magic-background`, `catalogue`, `upload`, `token`, or `*` (all resources)
`actionType`	String	Yes	CRUD action type. Options: `create`, `read`, `update`, `delete`, or `*` (all actions)
`userReference`	String	No	User reference to identify the user
`catalogueId`	String	No	Catalogue ID if searching against a specific catalogue
`type`	String	No	Token type: `"ONE_TIME"` or `"SESSION"`. Default: `"ONE_TIME"`
`duration`	Integer	No	Duration in minutes for SESSION tokens. Default: `5`, Maximum: `1440` (24 hours)

Using Tokens in API Requests

Once you have obtained a token, include it in the Authorization header as a Bearer token for protected endpoints:

GET https://platform.youzu.ai/api/v1/user?user_id=550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer {your-token}

SDK

Example: Complete Authentication Flow

Here's a complete example showing how to authenticate and make an API request:

// Step 1: Generate a token (server-side)
const generateToken = async () => {
  const response = await fetch('https://platform.youzu.ai/api/v1/token', {
    method: 'POST',
    headers: {
      'x-client-secret': 'YOUR_CLIENT_SECRET',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      actionResource: 'magic-background',
      actionType: 'create'
    })
  });

  if (response.ok) {
    const data = await response.json();
    return data.token;
  } else {
    throw new Error('Failed to generate token');
  }
};

// Step 2: Use the token to make an API request
const useToken = async () => {
  const token = await generateToken();
  
  const formData = new FormData();
  formData.append('productImage', 'https://example.com/product.jpg');
  
  const response = await fetch('https://platform.youzu.ai/api/v1/magic-background', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'x-client-secret': 'YOUR_CLIENT_SECRET'
    },
    body: formData
  });

  if (response.ok) {
    return await response.json();
  } else {
    throw new Error('API request failed');
  }
};

Install

Youzu Lens