GuideAPI Reference

Session Token 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 to the session endpoint from your backend services only.

This guide provides detailed instructions for working with Youzu API session tokens, including creation, usage, and refresh.

OverviewCopied!

Youzu uses JWT (JSON Web Tokens) for authentication. The authentication flow consists of:

  1. Obtaining a session token with your Secret Key and a user reference
  2. Using the token in subsequent API calls
  3. Refreshing the token before it expires

Creating a Session TokenCopied!

To create a session token, you need to make a request to the /v1/user/session endpoint.

PrerequisitesCopied!

  • A Secret Key provided by Youzu (sent in the x-client-secret header)
  • A valid user system reference ID (from your SSO system)

Request FormatCopied! 

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

{
  "system_ref": "user-reference-id-from-sso"
}

Response FormatCopied!

A successful response (HTTP 200) will include both user information and session details:

{
  "user": {
    "id": "user-uuid",
    "systemRef": "user-reference-id-from-sso"
  },
  "session": {
    "token": "jwt-access-token",
    "refreshToken": "refresh-token-for-later-use",
    "expiresAt": 1743865460
  }
}

Error HandlingCopied!

Common error responses include:

  • 400 Bad Request: Missing required parameters

    {
  "error": "invalid_request",
  "message": "Missing systemRef parameter"
}

  • 401 Unauthorized: Invalid Secret Key

    {
  "error": "unauthorized",
  "message": "Invalid or missing platform authentication"
}

Using Session TokensCopied!

Once you have obtained a session token, you can use it to authenticate requests to protected API endpoints.

Including the Token in RequestsCopied!

Add the token to your request's Authorization header as a Bearer token:

GET https://platform-api.youzu.ai/api/v1/user
Authorization: Bearer jwt-access-token

Refreshing Session TokensCopied!

Session tokens have a limited lifespan, indicated by the expiresAt field. To maintain continuous access, refresh your token before it expires.

Request FormatCopied! 

POST https://platform-api.youzu.ai/api/v1/user/session/refresh
Content-Type: application/json

{
  "refresh_token": "refresh-token-from-previous-session"
}

Response FormatCopied!

A successful refresh response provides a new set of tokens:

{
  "session": {
    "token": "new-jwt-access-token",
    "refreshToken": "new-refresh-token",
    "expiresAt": 1743951860
  }
}

Error HandlingCopied!

Common refresh errors include:

  • 400 Bad Request: Missing refresh token

    {
  "error": "invalid_request",
  "message": "Missing refresh token"
}

  • 401 Unauthorized: Invalid or expired refresh token

    {
  "error": "unauthorized",
  "message": "Invalid refresh token"
}

Related DocumentationCopied!