Skip to content
Shortcut: /, ⌘K or Ctrl+K

Client tokens

View as Markdown

The client token object

Attributes

  • tokenstringrequired

    Client token with pmfa_ct_ prefix

  • expiresAtstringrequired

    ISO 8601 timestamp when this resource expires.

The client token object
{
  "token": "string",
  "expiresAt": "string"
}

Get client rules

GET/platform/sessions/{session}/client-rulesPlatform API
Base URL
https://api.polymorfa.com
Required permission
sessions:manage

Path parameters

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

Responses

  • 200Client rules
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      Show 10 child fields
    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 500Internal server error
GET /platform/sessions/{session}/client-rulescURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/sessions/<session>/client-rules" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true,
  "data": {
    "recipientMode": "conversation",
    "allowedActions": "string",
    "rateLimit": 0,
    "maxDaily": 0,
    "allowedOrigins": "string",
    "maxConcurrency": 0,
    "allowedNumber": "string",
    "maxSetupsPerMinute": 0,
    "conversationTtlSeconds": 300,
    "enabled": true
  }
}

Mint client token

POST/platform/client-tokensPlatform API
Base URL
https://api.polymorfa.com

Required scopes (all): sessions:manage · messages:write · contacts:read · presence:read · presence:observe · mcp

Minting requires an active, unrevoked issuer with the required scopes and current resource ownership. A human-owned issuer must belong to a current team owner or admin who is not banned. Service-account credentials can delegate only actions allowed by the issuing credential's live scopes. Test-key clients remain restricted to test numbers. Issuance eligibility denials return 403; unavailable issuance checks return 503 and no token.

Minting requires an active issuer with the required scopes and current Number or Customer ownership. A human-owned issuer must still belong to a team owner or admin who is not banned. Service-account credentials delegate only actions allowed by the issuing credential's live scopes. Test-key clients remain restricted to test numbers. Eligibility denials return 403; unavailable issuance checks return 503. Neither response contains a token.

Body

  • sessionstringmin length1

    ID of the session this token can access. Provide exactly one of session or customer.

  • customerstring (uuid)

    Polymorfa Customer ID. The token covers the numbers this Customer owns when it is minted, and only while the Customer still owns each one. Provide exactly one of session or customer. Requires the customers:read scope and enrollment in the Customer-scoped client tokens beta.

  • allowarray of stringitems0–30

    Immutable action ceiling, intersected with live client rules. Session allow requires the action-ceilings beta. With ceiling issuance enabled, session omission snapshots its configured actions. For a Customer, omission uses the original Customer action set. An empty session allow grants no actions; Customer allow must be non-empty. Regional actions are reserved for enrolled beta access.

    Allowed valuesShow all 30 values
    mcpsend_messagesend_reactionsend_typingsend_seenread_presencesubscribe_presenceread_contactvoip_placevoip_answervoip_signalchats_readchats_managecontact_writecontact_deletegroups_readgroups_manageread_callsconversations_readconversations_managelabels_readlabels_managecontacts_manageprofile_readprofile_managechannels_readchannels_managebusiness_readpresence_writestickers_manage
  • ephemeralIdstringrequiredmin length1

    Your identifier for the browser or mobile user receiving this token.

  • ttlSecondsinteger

    Token lifetime in seconds. Must be at least 1 and within the maximum allowed lifetime. Omit to use that maximum.

Responses

  • 200Token minted
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      Show 2 child fields
    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 500Internal server error
POST /platform/client-tokenscURL
curl -X POST "https://api.polymorfa.com/platform/client-tokens" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "ephemeralId": "string"
}'
Response
{
  "success": true,
  "data": {
    "token": "string",
    "expiresAt": "string"
  }
}

Set client rules

PUT/platform/sessions/{session}/client-rulesPlatform API
Base URL
https://api.polymorfa.com

Required scopes (all): sessions:manage · messages:write · contacts:read · presence:read · presence:observe · mcp

Path parameters

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

Body

  • recipientModestringrequired

    Behavior selected for recipient.

  • allowedActionsstringmax length1024

    Specifies allowed actions for this management platform access set client rules request.

    Default ""
  • rateLimitintegermin0

    Specifies rate limit for this management platform access set client rules request.

    Default 0
  • maxDailyintegermin0

    Specifies max daily for this management platform access set client rules request.

    Default 0
  • allowedOriginsstringmax length8192

    Specifies allowed origins for this management platform access set client rules request.

    Default ""
  • enabledbooleanrequired

    Whether this feature is enabled.

  • maxConcurrencyintegerdeprecatedmin0

    Deprecated. Has no effect. Client tokens use the same call limits as every other credential.

    Default 0
  • allowedNumberstringmax length8192

    Specifies allowed number for this management platform access set client rules request.

    Default ""
  • maxSetupsPerMinuteintegerdeprecatedrange0–600

    Deprecated. Has no effect. Client tokens use the same call limits as every other credential.

    Default 0
  • conversationTtlSecondsintegerrange300–604800

    How long, in seconds, a sender remains replyable in conversation mode after their latest inbound message. Must be between 300 (5 minutes) and 604800 (7 days). Defaults to 86400 (24 hours).

    Default 86400

Responses

  • 200Rules saved
    • successbooleanrequired

      Whether the request succeeded.

    • messagestring

      Human-readable message associated with this result.

    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 500Internal server error
PUT /platform/sessions/{session}/client-rulescURL
Not available with the Test key. Use a team key or project token.
curl -X PUT "https://api.polymorfa.com/platform/sessions/<session>/client-rules" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "recipientMode": "string",
  "enabled": true
}'
Response
{
  "success": true
}

Delete client rules

DELETE/platform/sessions/{session}/client-rulesPlatform API
Base URL
https://api.polymorfa.com
Required permission
sessions:manage

Path parameters

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

Responses

  • 200Rules deleted
    • successbooleanrequired

      Whether the request succeeded.

    • messagestring

      Human-readable message associated with this result.

    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 500Internal server error
DELETE /platform/sessions/{session}/client-rulescURL
Not available with the Test key. Use a team key or project token.
curl -X DELETE "https://api.polymorfa.com/platform/sessions/<session>/client-rules" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true
}