Users & QR codes API

Use the customer API to create, retrieve, edit, regenerate and delete managed provisioning users. The same subscription allowance and tenant rules apply as in the portal. Saved-user management must be enabled for the subscription.

The API accepts JSON, not a CSV upload. To automate a CSV import, parse the CSV in your integration and submit the rows as a users array.

Create a key

In Account management → API Keys, create a named key and select the permissions your integration needs:

Select both for an integration that manages and retrieves users. Existing keys do not automatically receive these scopes. Copy the key when it is created and keep it in a server-side secret store; do not embed it in browser code or put it in a URL.

Keys are restricted to the customer account that created them. Portal administrator access does not expand API-key access. Keys cannot purchase additional capacity; use the portal checkout for that.

Send the key in the header Authorization: Bearer YOUR_KEY. For requests with a JSON body, also send Content-Type: application/json.

Base URL: https://cloud.sessiontalk.io/api/v1/customer

Identify the subscription and tenant

Call GET /plans with the plans:read permission. The response contains result.plans. Use the desired plan’s id as subscriptionId below. For appName, use the exact name from that plan’s tenants array. A tenant’s name can differ from its subscription ID. Do not use a Provider ID as either identifier.

Endpoints

All paths below are relative to the base URL. Encode path parameters when they contain spaces or other reserved characters.

Responses are wrapped in { "result": ... }, or { "error": "..." } on failure. Treat credential and token responses as private data; do not log their bodies.

Preview a batch

Send this JSON body to POST /plans/{subscriptionId}/users:

{
  "appName": "ExampleTenant",
  "preview": true,
  "users": [
    {
      "userRef": "guide-001",
      "displayName": "Alex",
      "sipaccounts": [
        {
          "sipusername": "1001",
          "sippassword": "replace-this-password",
          "subdomain": "pbx.example.com",
          "transport": "TLS"
        }
      ]
    }
  ]
}

The preview returns counts including newUsers, existingUsers, shortfall, limit and used. It does not save users or issue tokens. Choose SIP values and transport that match the PBX; the values above are examples only.

Omit preview or set it to false to save and generate. The response includes result.users, whose entries contain the stable internal id, userRef, tenantId, tenantName, qrPayload, qrStatus and expiresAt.

Render the returned qrPayload exactly as supplied with a QR library. Do not reconstruct the token, change its URL scheme or call the app’s redemption endpoint to test it: redemption consumes the code. Reading the /qr endpoint does not consume it.

Updates and retries

The same userRef updates a user already assigned to appName; it does not consume another slot. A duplicate reference within a batch is rejected. Any invalid row or insufficient capacity rejects the entire batch.

Saving is not an idempotent token operation: repeating a successful POST keeps the user identity but generates a new code and invalidates the previous unused code. If you lose the response, list users and retrieve the current /qr rather than blindly repeating generation.

User profiles support 1–4 sipaccounts and up to 4 xmppaccounts. CSV-style fields map to lowercase SIP property names, such as authusername, proxy and sipport. Send all accounts and options you intend to retain when updating; account arrays replace the saved profile. For the batch API, omitting displayName preserves an existing name; sending an empty string clears it.

Edit a user or change tenant

First retrieve the editable details. Send the complete intended profile to PUT /plans/{subscriptionId}/users/{userId} using the body shape below:

{
  "appName": "AnotherTenantInTheSameSubscription",
  "user": {
    "userRef": "guide-001",
    "displayName": "Alex",
    "sipaccounts": [
      {
        "sipusername": "1001",
        "sippassword": "replace-this-password",
        "subdomain": "pbx.example.com",
        "transport": "TLS"
      }
    ],
    "xmppaccounts": []
  }
}

Keep userRef unchanged. Both tenants must belong to the same subscription. The explicit PUT operation can move the user; a batch POST against another tenant returns a conflict. Editing creates a new code but does not add a user slot or reconfigure an installed app.

Regenerate without resending credentials

Send POST /plans/{subscriptionId}/qr/regenerate with:

{ "userIds": ["id-returned-by-the-users-endpoint"] }

The response’s result is an array of fresh QR records. Each keeps its saved tenant, consumes no extra user capacity and starts a new 72-hour lifetime. Its previous unused code becomes invalid.

Errors and limits

The customer API is limited to 120 requests per minute per source IP. Batch save requests are limited to 1 MB and 500 users; individual PUT and regeneration requests are limited to 64 KB. Generation and edits require an active subscription or valid trial. Saved records remain readable after expiry of the subscription, but QR tokens still obey their own single-use and 72-hour limits.