Test key
Use your project's Test key to call the API for test numbers without a show-once key.
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
- Sign in to the Console in the same browser.
- 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.
- 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
- Open the project's Settings tab and select API keys.
- 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.
- 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
- In Inspector's project list, find the project's row.
- Select Reveal, or Create and reveal if the project has no Test key.
- 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:
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.
| Operation | What it does | Number check |
|---|---|---|
GET /messaging/{session}/chats | List chats | The session path parameter must name a test number in the key's project. |
GET /messaging/{session}/chats/{conversation} | Get chat | The session path parameter must name a test number in the key's project. |
POST /messaging/{session}/chats/{conversation}/archive | Archive chat | The session path parameter must name a test number in the key's project. |
PUT /messaging/{session}/chats/{conversation}/disappearing | Set chat disappearing timer | The session path parameter must name a test number in the key's project. |
GET /messaging/{session}/chats/{conversation}/messages | List chat messages | The session path parameter must name a test number in the key's project. |
DELETE /messaging/{session}/chats/{conversation}/messages/{messageId} | Delete message | The session path parameter must name a test number in the key's project. |
GET /messaging/{session}/chats/{conversation}/messages/{messageId} | Get chat message | The session path parameter must name a test number in the key's project. |
PUT /messaging/{session}/chats/{conversation}/messages/{messageId} | Edit message | The session path parameter must name a test number in the key's project. |
POST /messaging/{session}/chats/{conversation}/unarchive | Unarchive chat | The session path parameter must name a test number in the key's project. |
GET /messaging/{session}/contacts | List contacts | The session path parameter must name a test number in the key's project. |
GET /messaging/{session}/contacts/{contactId} | Get contact | The session path parameter must name a test number in the key's project. |
POST /messaging/{session}/messages/react | Send reaction | The session path parameter must name a test number in the key's project. |
POST /messaging/{session}/messages/seen | Send seen | The session path parameter must name a test number in the key's project. |
POST /messaging/{session}/messages/send | Send message | The session path parameter must name a test number in the key's project. |
POST /messaging/{session}/messages/typing | Set typing | The session path parameter must name a test number in the key's project. |
GET /messaging/{session}/phone | Get testing phone | The session path parameter must name a test number in the key's project. |
PUT /messaging/{session}/phone/account-mode | Set testing account mode | The session path parameter must name a test number in the key's project. |
POST /messaging/{session}/phone/devices/{deviceId}/unlink | Unlink testing phone device | The session path parameter must name a test number in the key's project. |
POST /messaging/{session}/phone/messages | Send testing phone message | The session path parameter must name a test number in the key's project. |
GET /messaging/{session}/safe-mode | Get session safe mode | The session path parameter must name a test number in the key's project. |
POST /messaging/{session}/test-events | Trigger test event | The session path parameter must name a test number in the key's project. |
GET /messaging/test-events/fixtures | List test event fixtures | Names no Number. The response is the same for every project. |
POST /platform/client-tokens | Mint client token | The session body field must name a test number in the key's project. |
GET /platform/projects/{projectId}/events | List project events | Returns only the project's test numbers. |
GET /platform/projects/{projectId}/events/{eventId} | Get project event | Names no Number. |
GET /platform/projects/{projectId}/request-logs | List project request logs | Returns only the project's test numbers. |
GET /platform/sessions | List sessions | Returns only the project's test numbers. |
GET /platform/sessions/{sessionId} | Get session | The sessionId path parameter must name a test number in the key's project. |
GET /platform/sessions/{sessionId}/capabilities | Get session capabilities | The sessionId path parameter must name a test number in the key's project. |
POST /platform/sessions/{sessionId}/restart | Restart session | The sessionId path parameter must name a test number in the key's project. |
GET /platform/sessions/{sessionId}/safe-mode | Get number safe mode | The sessionId path parameter must name a test number in the key's project. |
POST /platform/sessions/{sessionId}/start | Start session | The sessionId path parameter must name a test number in the key's project. |
POST /platform/sessions/{sessionId}/stop | Stop session | The 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.
- In the Console's Test key card, or on the project's row in Inspector, select Regenerate and confirm.
- 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#
| Action | Limit |
|---|---|
| Reveal | 30 per person and 120 per team in a rolling hour |
| Regenerate | 5 per project in a rolling hour |
| Status | Code | Meaning |
|---|---|---|
429 | rate_limited | Over a limit. Retry after the Retry-After header's seconds. |
503 | test_key_unavailable | The key service is unavailable. Nothing changed; retry later. |
403 | forbidden | You 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.