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

Test key

Use your project's Test key to call the API for test numbers without a show-once key.

View as Markdown

Every project has one Test key. It is a project token that works only with the project's test numbers, and you can reveal it again at any time. Use it in local code, in the code samples on these docs and in Try it requests. Every other team key and project token is shown once.

A request made with the Test key for a real Number is refused. A client token created with the Test key carries the same restriction.

Reveal the Test key#

Docs

  1. Sign in to the Console in the same browser.
  2. In these docs, open any API reference page. Open the Test key menu at the top of its navigation, in the menu on phones, and choose the project.
  3. Select Reveal Test key.

Code samples on the operations the Test key can call now show the key, and Try it sends requests with it. The key stays in this browser tab's memory until you hide it or close the tab.

Console

  1. Open the project's Settings tab and select API keys.
  2. In the Test key card above the project keys list, select Reveal. A project without a Test key shows Not created; select Create and reveal.
  3. Select Copy to copy the key.

The key stays visible until you select Hide, switch projects or leave the page, and for at most five minutes. The card also shows when the key was created, last revealed and last regenerated. The Test key is also a row in the project keys list, and revoking that row revokes it.

Inspector

  1. In Inspector's project list, find the project's row.
  2. Select Reveal, or Create and reveal if the project has no Test key.
  3. Select Copy to copy the key.

Inspector shows one project's key at a time. It hides the key after 60 seconds, or when you select Hide, reveal another project's key, switch teams, open a session or sign out. A hidden key shows only its last four characters. Inspector lists Test keys for projects in every team you authorized when you signed in.

The first reveal creates the key. Opening a page never creates one.

Use the Test key#

The Test key looks like any project token (pmfa_pt_ followed by random characters). Treat it as opaque: nothing inside it marks it as a Test key. Send it as a bearer token:

Shell
curl -X POST "https://api.polymorfa.com/messaging/$SESSION/messages/send" \
  -H "Authorization: Bearer $POLYMORFA_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": { "phoneNumber": "+15550100002" },
    "content": { "text": "Hello from a test number" }
  }'

$SESSION must be a test number in the key's project. The same request for a real Number fails.

What the Test key can call#

The Test key can call the operations below and nothing else. Every other operation returns 404 with resource_not_found, as if the route did not exist, even when the key has the operation's scope. Use a team key or project token for those. A Test key also cannot open a raw bridge connection.

Each operation checks that the Number it acts on is a test number in the key's project. A real Number, or a Number in another project, is refused. The to of a test phone message and the fromNumber of a test event must also be test numbers in the same project. Uploading history fixtures is not available with a Test key.

The Test key can start, stop and restart a test number in its project. These change only the test number's simulated account and never charge credit. Removing a test number needs a team key or project token. Existing Test keys can start, stop and restart without being regenerated. Use Try it or an HTTP request; the browser Shell does not run Platform lifecycle commands.

These responses acknowledge the request. Check the Number's status before treating a start, stop or restart as complete.

The project event and request-log reads return only rows that belong to a test number in the key's project. Rows for real Numbers and project-wide rows without a Number are left out of lists, and reading one of those events returns 404 with resource_not_found. A Test key created or regenerated before these reads were added lacks the events:read and logs:read scopes; regenerate it to add them.

OperationWhat it doesNumber check
GET /messaging/{session}/chatsList chatsThe session path parameter must name a test number in the key's project.
GET /messaging/{session}/chats/{conversation}Get chatThe session path parameter must name a test number in the key's project.
POST /messaging/{session}/chats/{conversation}/archiveArchive chatThe session path parameter must name a test number in the key's project.
PUT /messaging/{session}/chats/{conversation}/disappearingSet chat disappearing timerThe session path parameter must name a test number in the key's project.
GET /messaging/{session}/chats/{conversation}/messagesList chat messagesThe session path parameter must name a test number in the key's project.
DELETE /messaging/{session}/chats/{conversation}/messages/{messageId}Delete messageThe session path parameter must name a test number in the key's project.
GET /messaging/{session}/chats/{conversation}/messages/{messageId}Get chat messageThe session path parameter must name a test number in the key's project.
PUT /messaging/{session}/chats/{conversation}/messages/{messageId}Edit messageThe session path parameter must name a test number in the key's project.
POST /messaging/{session}/chats/{conversation}/unarchiveUnarchive chatThe session path parameter must name a test number in the key's project.
GET /messaging/{session}/contactsList contactsThe session path parameter must name a test number in the key's project.
GET /messaging/{session}/contacts/{contactId}Get contactThe session path parameter must name a test number in the key's project.
POST /messaging/{session}/messages/reactSend reactionThe session path parameter must name a test number in the key's project.
POST /messaging/{session}/messages/seenSend seenThe session path parameter must name a test number in the key's project.
POST /messaging/{session}/messages/sendSend messageThe session path parameter must name a test number in the key's project.
POST /messaging/{session}/messages/typingSet typingThe session path parameter must name a test number in the key's project.
GET /messaging/{session}/phoneGet testing phoneThe session path parameter must name a test number in the key's project.
PUT /messaging/{session}/phone/account-modeSet testing account modeThe session path parameter must name a test number in the key's project.
POST /messaging/{session}/phone/devices/{deviceId}/unlinkUnlink testing phone deviceThe session path parameter must name a test number in the key's project.
POST /messaging/{session}/phone/messagesSend testing phone messageThe session path parameter must name a test number in the key's project.
GET /messaging/{session}/safe-modeGet session safe modeThe session path parameter must name a test number in the key's project.
POST /messaging/{session}/test-eventsTrigger test eventThe session path parameter must name a test number in the key's project.
GET /messaging/test-events/fixturesList test event fixturesNames no Number. The response is the same for every project.
POST /platform/client-tokensMint client tokenThe session body field must name a test number in the key's project.
GET /platform/projects/{projectId}/eventsList project eventsReturns only the project's test numbers.
GET /platform/projects/{projectId}/events/{eventId}Get project eventNames no Number.
GET /platform/projects/{projectId}/request-logsList project request logsReturns only the project's test numbers.
GET /platform/sessionsList sessionsReturns only the project's test numbers.
GET /platform/sessions/{sessionId}Get sessionThe sessionId path parameter must name a test number in the key's project.
GET /platform/sessions/{sessionId}/capabilitiesGet session capabilitiesThe sessionId path parameter must name a test number in the key's project.
POST /platform/sessions/{sessionId}/restartRestart sessionThe sessionId path parameter must name a test number in the key's project.
GET /platform/sessions/{sessionId}/safe-modeGet number safe modeThe sessionId path parameter must name a test number in the key's project.
POST /platform/sessions/{sessionId}/startStart sessionThe sessionId path parameter must name a test number in the key's project.
POST /platform/sessions/{sessionId}/stopStop sessionThe sessionId path parameter must name a test number in the key's project.

Regenerate the Test key#

Regenerate the key if it leaks or someone who had it leaves the team.

  1. In the Console's Test key card, or on the project's row in Inspector, select Regenerate and confirm.
  2. Copy the new key and replace the old one wherever you use it.

Regenerate also creates a key when the project has none. The old key, and every client token created with it, stops working within 60 seconds. A successful Regenerate returns the new key even while that revocation is still reaching every region. Regenerate is the only way to replace the key in one step. Revoking the Test key's row in the Console's project keys list, or deleting the project, revokes it; after a revoke, the next Create and reveal creates a new key.

Limits and errors#

ActionLimit
Reveal30 per person and 120 per team in a rolling hour
Regenerate5 per project in a rolling hour
StatusCodeMeaning
429rate_limitedOver a limit. Retry after the Retry-After header's seconds.
503test_key_unavailableThe key service is unavailable. Nothing changed; retry later.
403forbiddenYou can't regenerate the key. Ask a team owner or admin.

Keep it safe#

A leaked Test key exposes your test numbers only, but treat it like any credential: don't commit it, and regenerate it if it is exposed. Copying the key puts it on your clipboard, where clipboard managers can keep it.

See also#