Custom Storefront Tokens - RMZ Developer Docs

Custom Storefront Tokens allow store owners to generate API keys that external developers can use to build custom storefronts. Tokens are scoped by domain, environment, and permissions.

POST /custom/tokens

Generate a new API token for a custom storefront domain.

Authentication

Requires Bearer token (auth:customer_api).

Headers

Header	Value	Required
Authorization	Bearer	Yes
Content-Type	application/json	Yes

Body Parameters

Parameter	Type	Required	Description
domain	string	Yes	The domain where the token will be used (max 255 chars). Production domains must use HTTPS and cannot be localhost.
permissions	array	Yes	Array of permission strings (minimum 1)
environment	string	Yes	Either `development` or `production`

Available Permissions

Permission	Description
`read_products`	Read product data
`read_categories`	Read category data
`read_orders`	Read order data
`read_store`	Read store information
`read_analytics`	Read analytics data
`write_cart`	Manage cart operations
`write_wishlist`	Manage wishlist operations

Development tokens are limited to read_products, read_categories, and read_store permissions only. Requesting other permissions for a development token will return an error.

Example Request

curl -X POST "https://front.rmz.gg/api/custom/tokens" \
  -H "Authorization: Bearer 1|abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "https://mystore.example.com",
    "permissions": ["read_products", "read_categories", "read_store", "write_cart"],
    "environment": "production"
  }'

const response = await fetch("https://front.rmz.gg/api/custom/tokens", {
  method: "POST",
  headers: {
    "Authorization": "Bearer 1|abc123xyz...",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    domain: "https://mystore.example.com",
    permissions: ["read_products", "read_categories", "read_store", "write_cart"],
    environment: "production"
  })
});
const data = await response.json();

response = requests.post("https://front.rmz.gg/api/custom/tokens",
    headers={"Authorization": "Bearer 1|abc123xyz..."},
    json={
        "domain": "https://mystore.example.com",
        "permissions": ["read_products", "read_categories", "read_store", "write_cart"],
        "environment": "production"
    }
)
data = response.json()

$response = Http::withToken("1|abc123xyz...")->post("https://front.rmz.gg/api/custom/tokens", [
    "domain" => "https://mystore.example.com",
    "permissions" => ["read_products", "read_categories", "read_store", "write_cart"],
    "environment" => "production"
]);
$data = $response->json();

Response

Success (200)

{
  "success": true,
  "data": {
    "id": 1,
    "token": "cst_42_a1b2c3d4e5f6...",
    "domain": "https://mystore.example.com",
    "permissions": ["read_products", "read_categories", "read_store", "write_cart"],
    "environment": "production",
    "expires_at": "2025-06-15T00:00:00.000000Z",
    "created_at": "2024-06-15T10:30:00.000000Z",
    "usage_note": "Store this token securely. It will not be shown again."
  },
  "message": "API token generated successfully"
}

The raw token value is only returned once at creation time. Store it securely — it cannot be retrieved again. The token is stored as a SHA-256 hash on the server.

Error Responses

Status	Description
400	Production domain uses localhost, production domain not HTTPS, or development token with restricted permissions
401	Not authenticated
409	Token already exists for this domain and environment
422	Validation error

Token Expiry

Environment	Expires After
`development`	30 days
`production`	1 year

GET /custom/tokens

List all tokens for the authenticated customer’s store.

Authentication

Requires Bearer token (auth:customer_api).

Headers

Header	Value	Required
Authorization	Bearer	Yes

Example Request

curl "https://front.rmz.gg/api/custom/tokens" \
  -H "Authorization: Bearer 1|abc123xyz..."

const response = await fetch("https://front.rmz.gg/api/custom/tokens", {
  headers: { "Authorization": "Bearer 1|abc123xyz..." }
});
const data = await response.json();

response = requests.get("https://front.rmz.gg/api/custom/tokens", headers={
    "Authorization": "Bearer 1|abc123xyz..."
})
data = response.json()

$response = Http::withToken("1|abc123xyz...")->get("https://front.rmz.gg/api/custom/tokens");
$data = $response->json();

Response

Success (200)

{
  "success": true,
  "data": [
    {
      "id": 1,
      "domain": "https://mystore.example.com",
      "permissions": ["read_products", "read_categories", "read_store", "write_cart"],
      "environment": "production",
      "is_active": true,
      "last_used_at": "2024-06-15T12:00:00.000000Z",
      "usage_count": 1500,
      "expires_at": "2025-06-15T00:00:00.000000Z",
      "created_at": "2024-06-15T10:30:00.000000Z"
    }
  ]
}

The raw token value is never returned in list responses. Only metadata is shown.

DELETE /custom/tokens/

Revoke (deactivate) a token.

Authentication

Requires Bearer token (auth:customer_api).

Path Parameters

Parameter	Type	Description
tokenId	integer	Token ID to revoke

Example Request

curl -X DELETE "https://front.rmz.gg/api/custom/tokens/1" \
  -H "Authorization: Bearer 1|abc123xyz..."

const response = await fetch("https://front.rmz.gg/api/custom/tokens/1", {
  method: "DELETE",
  headers: { "Authorization": "Bearer 1|abc123xyz..." }
});
const data = await response.json();

response = requests.delete("https://front.rmz.gg/api/custom/tokens/1", headers={
    "Authorization": "Bearer 1|abc123xyz..."
})
data = response.json()

$response = Http::withToken("1|abc123xyz...")->delete("https://front.rmz.gg/api/custom/tokens/1");
$data = $response->json();

Response

Success (200)

{
  "success": true,
  "data": null,
  "message": "Token revoked successfully"
}

Error Responses

Status	Description
401	Not authenticated
404	Token not found

GET /custom/tokens//stats

Get usage statistics for a specific token.

Authentication

Requires Bearer token (auth:customer_api).

Path Parameters

Parameter	Type	Description
tokenId	integer	Token ID

Example Request

curl "https://front.rmz.gg/api/custom/tokens/1/stats" \
  -H "Authorization: Bearer 1|abc123xyz..."

const response = await fetch("https://front.rmz.gg/api/custom/tokens/1/stats", {
  headers: { "Authorization": "Bearer 1|abc123xyz..." }
});
const data = await response.json();

response = requests.get("https://front.rmz.gg/api/custom/tokens/1/stats", headers={
    "Authorization": "Bearer 1|abc123xyz..."
})
data = response.json()

$response = Http::withToken("1|abc123xyz...")->get("https://front.rmz.gg/api/custom/tokens/1/stats");
$data = $response->json();

Response

Success (200)

{
  "success": true,
  "data": {
    "usage_count": 1500,
    "last_used_at": "2024-06-15T12:00:00.000000Z",
    "created_at": "2024-06-15T10:30:00.000000Z",
    "is_active": true,
    "environment": "production",
    "days_until_expiry": 365
  }
}

Error Responses

Status	Description
401	Not authenticated
404	Token not found

POST /custom/tokens/validate

Validate a custom storefront token. This is a public endpoint that does not require Bearer authentication.

Authentication

None required. The token to validate is passed in the request body.

Headers

Header	Value	Required
Content-Type	application/json	Yes

Body Parameters

Parameter	Type	Required	Description
token	string	Yes	The raw token value to validate

Example Request

curl -X POST "https://front.rmz.gg/api/custom/tokens/validate" \
  -H "Content-Type: application/json" \
  -d '{"token": "cst_42_a1b2c3d4e5f6..."}'

const response = await fetch("https://front.rmz.gg/api/custom/tokens/validate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ token: "cst_42_a1b2c3d4e5f6..." })
});
const data = await response.json();

response = requests.post("https://front.rmz.gg/api/custom/tokens/validate", json={
    "token": "cst_42_a1b2c3d4e5f6..."
})
data = response.json()

$response = Http::post("https://front.rmz.gg/api/custom/tokens/validate", [
    "token" => "cst_42_a1b2c3d4e5f6..."
]);
$data = $response->json();

Response

Valid Token (200)

{
  "success": true,
  "data": {
    "valid": true,
    "store_id": 42,
    "permissions": ["read_products", "read_categories", "read_store", "write_cart"],
    "environment": "production"
  }
}

Error Responses

Status	Description
401	Invalid or expired token
403	Token domain mismatch (production tokens are validated against the `Origin` header)
422	Validation error (missing token)

For production tokens, the Origin or Referer header of the request must match the domain registered with the token. Development tokens skip this check.

GET /custom/tokens/permissions

Get the permissions and metadata for a token identified by the X-Custom-Token header. This is a public endpoint.

Authentication

None required. Pass the token via the X-Custom-Token header.

Headers

Header	Value	Required
X-Custom-Token	Yes

Example Request

curl "https://front.rmz.gg/api/custom/tokens/permissions" \
  -H "X-Custom-Token: cst_42_a1b2c3d4e5f6..."

const response = await fetch("https://front.rmz.gg/api/custom/tokens/permissions", {
  headers: { "X-Custom-Token": "cst_42_a1b2c3d4e5f6..." }
});
const data = await response.json();

response = requests.get("https://front.rmz.gg/api/custom/tokens/permissions", headers={
    "X-Custom-Token": "cst_42_a1b2c3d4e5f6..."
})
data = response.json()

$response = Http::withHeaders(["X-Custom-Token" => "cst_42_a1b2c3d4e5f6..."])
    ->get("https://front.rmz.gg/api/custom/tokens/permissions");
$data = $response->json();

Response

Success (200)

{
  "success": true,
  "data": {
    "permissions": ["read_products", "read_categories", "read_store", "write_cart"],
    "environment": "production",
    "domain": "https://mystore.example.com",
    "expires_at": "2025-06-15T00:00:00.000000Z"
  }
}

Error Responses

Status	Description
401	Missing, invalid, or expired token

​POST /custom/tokens

​Authentication

​Headers

​Body Parameters

​Available Permissions

​Example Request

​Response

​Success (200)

​Error Responses

​Token Expiry

​GET /custom/tokens

​Authentication

​Headers

​Example Request

​Response

​Success (200)

​DELETE /custom/tokens/

​Authentication

​Path Parameters

​Example Request

​Response

​Success (200)

​Error Responses

​GET /custom/tokens//stats

​Authentication

​Path Parameters

​Example Request

​Response

​Success (200)

​Error Responses

​POST /custom/tokens/validate

​Authentication

​Headers

​Body Parameters

​Example Request

​Response

​Valid Token (200)

​Error Responses

​GET /custom/tokens/permissions

​Authentication

​Headers

​Example Request

​Response

​Success (200)

​Error Responses

POST /custom/tokens

Authentication

Headers

Body Parameters

Available Permissions

Example Request

Response

Success (200)

Error Responses

Token Expiry

GET /custom/tokens

Authentication

Headers

Example Request

Response

Success (200)

DELETE /custom/tokens/

Authentication

Path Parameters

Example Request

Response

Success (200)

Error Responses

GET /custom/tokens//stats

Authentication

Path Parameters

Example Request

Response

Success (200)

Error Responses

POST /custom/tokens/validate

Authentication

Headers

Body Parameters

Example Request

Response

Valid Token (200)

Error Responses

GET /custom/tokens/permissions

Authentication

Headers

Example Request

Response

Success (200)

Error Responses