Customer Tokens

The customer-tokens endpoint mints a short-lived, per-customer access token for the Allomancy customer page. Your key authenticates your store, you name a customer, and the response gives you a token plus a ready-formed link that opens the customer page as that resident. The minting store is always the one your API key authenticates, never a value in the request, and the customer is resolved from the identifier you send. Field shapes are on the Object reference page.

Mint a customer token

POST /v1/customer-tokens

Mints a customer access token for your store. Scope: customertokens:mint. The body is a MintCustomerTokenRequest.

Send the customer's Second Life username or avatar UUID in customerIdentifier (required); Allomancy resolves it to the resident server-side.

collectiveId is optional: set it to mint a token scoped to a collective instead of your store. Only the collective's owner store can mint this way, and only for a customer of your store. Omit it for a normal store-scoped token.

curl --fail-with-body https://integrations.allomancy.net/v1/customer-tokens \
  -H "X-API-Key: allo_live_8Kd2...zQ.Hk9...4w" \
  -H "Content-Type: application/json" \
  -d '{
    "customerIdentifier": "resident.username",
    "collectiveId": null
  }'

import requests

response = requests.post(
    "https://integrations.allomancy.net/v1/customer-tokens",
    headers={"X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w"},
    json={
        "customerIdentifier": "resident.username",
        "collectiveId": None,
    },
)
print(response.json())

const response = await fetch(
  "https://integrations.allomancy.net/v1/customer-tokens",
  {
    method: "POST",
    headers: {
      "X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      customerIdentifier: "resident.username",
      collectiveId: null,
    }),
  },
);
console.log(await response.json());

<?php
$ch = curl_init("https://integrations.allomancy.net/v1/customer-tokens");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: allo_live_8Kd2...zQ.Hk9...4w",
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "customerIdentifier" => "resident.username",
    "collectiveId" => null,
]));
$response = curl_exec($ch);
curl_close($ch);
echo $response;

{
  "token": "8Kd2zQ7Hs9...Qm4wZx",
  "url": "https://customers.example.com/#ct=8Kd2zQ7Hs9...Qm4wZx",
  "expiresAt": "2026-04-27T16:12:00Z"
}

The response is a MintCustomerTokenResponse. The url is ready to hand to the customer: it is the customer page origin with the token in the #ct= fragment. That origin is your store's configured customer page origin, or, for a token minted with collectiveId, the collective's. The customer page reads the token from that fragment and sends it as the X-Customer-Token header. The token is short-lived, so mint a fresh one when it expires.

Status: 200. A 400 means the request body is missing, customerIdentifier is empty, or no customer page origin is configured for your store or, when collectiveId is set, for the collective (Customer page origin is not configured.). A 404 means the store or customer could not be resolved; when collectiveId is set, it also means your store is not the collective's owner, the collective does not exist, or the resident is not a customer of your store. A 429 (Too many mint requests.) means the per-key mint rate limit was hit; retry after a short wait.

Related pages