---
title: "Join a sandbox Product through a join link"
method: POST
path: "/v1/customer-identity/join"
tags: ["Customers"]
---

# Join a sandbox Product through a join link

`POST /v1/customer-identity/join`

## Request

- Base URL: `https://hyperscale0.ai`
- URL: `https://hyperscale0.ai/v1/customer-identity/join`
- Auth: none required

Redeems a join link: creates a sandbox test customer from the first name, activates its enrollment in the link's Product, opens its customer_balance account, funds it with the link's test money, and signs it in. The session is bound to that one customer and Product, and ends no later than the link does. An unknown token is not found, an expired link is refused as expired, and a link that has admitted maxJoins people is refused as full. Each call makes a new customer; the same person joining twice is two customers. The session token is a one-time secret surfaced only in this response.

## Headers

- `X-Hyperscale-Environment` 'sandbox' | 'live'
- `Idempotency-Key` string, required

## Request body

- object
  - `token` string, required: The secret in a join link's URL path, after /j/. Whoever holds it can join the link's Product as a sandbox customer until the link expires or fills.
  - `firstName` string, required: The only thing a guest gives. It becomes the display name.

## Response `201`

Success

- CustomerJoinOutput
  - `tenantId` string, required: Organization tenant ID
  - `productId` string, required: Hyperscale product ID
  - `environment` 'sandbox' | 'live', required
  - `customerId` string, required: Tenant-local customer ID
  - `entityId` string, required: Hyperscale entity ID
  - `displayName` string, required
  - `customerAccessId` string, required: Hyperscale customer access ID
  - `customerAccessStatus` 'pending' | 'active' | 'suspended' | 'closed', required
  - `accountId` string, required: Hyperscale account ID
  - `fundingTransferId` string, required: Hyperscale transfer ID
  - `fundingAmount` string, required: Positive minor-unit integer amount serialized as a string (at most 18 digits)
  - `currency` 'SAR', required
  - `customerSessionId` string, required: Hyperscale end-customer session ID
  - `sessionToken` string: One-time session token surfaced only in the first response; receipts and replays omit it
  - `sessionExpiresAt` string, date-time, required

## Other responses

- `default`: ErrorResponse. See x-error-codes and x-errors for codes, HTTP statuses and retry guidance.

---

[API](https://skmtc.dev/hyperscale0/apis/hyperscale-product-api.md) · [All operations](https://skmtc.dev/hyperscale0/apis/hyperscale-product-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hyperscale0/apis/hyperscale-product-api/revisions/e9e8faa044d5?raw)