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 your store's configured customer page origin with the token in the #ct= fragment. 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 your store has no customer page origin configured (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 (The mint rate limit has been exceeded.) means the per-key mint rate limit was hit; retry after a short wait.

Related pages