# 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](https://docs.polymorfa.com/testing/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.

> **Note**
>
> **Before you begin.** Your team needs [test numbers](https://docs.polymorfa.com/testing). Any member with
> access to the project can reveal its Test key. Only team owners and admins can
> regenerate it.

## Reveal the Test key

**Docs:**

1. Sign in to the Console in the same browser.
2. In these docs, open any [API reference](https://docs.polymorfa.com/api) 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:

```bash
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`](https://docs.polymorfa.com/api/chats/list-chats) | List chats | The `session` path parameter must name a test number in the key's project. |
| [`GET /messaging/{session}/chats/{conversation}`](https://docs.polymorfa.com/api/chats/get-chat) | Get chat | The `session` path parameter must name a test number in the key's project. |
| [`POST /messaging/{session}/chats/{conversation}/archive`](https://docs.polymorfa.com/api/chats/archive-chat) | Archive chat | The `session` path parameter must name a test number in the key's project. |
| [`PUT /messaging/{session}/chats/{conversation}/disappearing`](https://docs.polymorfa.com/api/chats/set-chat-disappearing-timer) | Set chat disappearing timer | The `session` path parameter must name a test number in the key's project. |
| [`GET /messaging/{session}/chats/{conversation}/messages`](https://docs.polymorfa.com/api/chats/list-chat-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}`](https://docs.polymorfa.com/api/chats/delete-message) | Delete message | The `session` path parameter must name a test number in the key's project. |
| [`GET /messaging/{session}/chats/{conversation}/messages/{messageId}`](https://docs.polymorfa.com/api/chats/get-chat-message) | Get chat message | The `session` path parameter must name a test number in the key's project. |
| [`PUT /messaging/{session}/chats/{conversation}/messages/{messageId}`](https://docs.polymorfa.com/api/chats/edit-message) | Edit message | The `session` path parameter must name a test number in the key's project. |
| [`POST /messaging/{session}/chats/{conversation}/unarchive`](https://docs.polymorfa.com/api/chats/unarchive-chat) | Unarchive chat | The `session` path parameter must name a test number in the key's project. |
| [`GET /messaging/{session}/contacts`](https://docs.polymorfa.com/api/contacts/list-contacts) | List contacts | The `session` path parameter must name a test number in the key's project. |
| [`GET /messaging/{session}/contacts/{contactId}`](https://docs.polymorfa.com/api/contacts/get-contact) | Get contact | The `session` path parameter must name a test number in the key's project. |
| [`POST /messaging/{session}/messages/react`](https://docs.polymorfa.com/api/messages/send-reaction) | Send reaction | The `session` path parameter must name a test number in the key's project. |
| [`POST /messaging/{session}/messages/seen`](https://docs.polymorfa.com/api/messages/send-seen) | Send seen | The `session` path parameter must name a test number in the key's project. |
| [`POST /messaging/{session}/messages/send`](https://docs.polymorfa.com/api/messages/send-message) | Send message | The `session` path parameter must name a test number in the key's project. |
| [`POST /messaging/{session}/messages/typing`](https://docs.polymorfa.com/api/messages/set-typing) | Set typing | The `session` path parameter must name a test number in the key's project. |
| [`GET /messaging/{session}/phone`](https://docs.polymorfa.com/api/testing/get-testing-phone) | Get testing phone | The `session` path parameter must name a test number in the key's project. |
| [`PUT /messaging/{session}/phone/account-mode`](https://docs.polymorfa.com/api/testing/set-testing-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`](https://docs.polymorfa.com/api/testing/unlink-testing-phone-device) | Unlink testing phone device | The `session` path parameter must name a test number in the key's project. |
| [`POST /messaging/{session}/phone/messages`](https://docs.polymorfa.com/api/testing/send-testing-phone-message) | Send testing phone message | The `session` path parameter must name a test number in the key's project. |
| [`GET /messaging/{session}/safe-mode`](https://docs.polymorfa.com/api/safe-mode/get-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`](https://docs.polymorfa.com/api/testing/trigger-test-event) | Trigger test event | The `session` path parameter must name a test number in the key's project. |
| [`GET /messaging/test-events/fixtures`](https://docs.polymorfa.com/api/testing/list-test-event-fixtures) | List test event fixtures | Names no Number. The response is the same for every project. |
| [`POST /platform/client-tokens`](https://docs.polymorfa.com/api/client-tokens/mint-client-token) | Mint client token | The `session` body field must name a test number in the key's project. |
| [`GET /platform/projects/{projectId}/events`](https://docs.polymorfa.com/api/events/list-project-events) | List project events | Returns only the project's test numbers. |
| [`GET /platform/projects/{projectId}/events/{eventId}`](https://docs.polymorfa.com/api/events/get-project-event) | Get project event | Names no Number. |
| [`GET /platform/projects/{projectId}/request-logs`](https://docs.polymorfa.com/api/request-logs/list-project-request-logs) | List project request logs | Returns only the project's test numbers. |
| [`GET /platform/sessions`](https://docs.polymorfa.com/api/numbers/list-sessions) | List sessions | Returns only the project's test numbers. |
| [`GET /platform/sessions/{sessionId}`](https://docs.polymorfa.com/api/numbers/get-session) | Get session | The `sessionId` path parameter must name a test number in the key's project. |
| [`GET /platform/sessions/{sessionId}/capabilities`](https://docs.polymorfa.com/api/numbers/get-session-capabilities) | Get session capabilities | The `sessionId` path parameter must name a test number in the key's project. |
| [`POST /platform/sessions/{sessionId}/restart`](https://docs.polymorfa.com/api/numbers/restart-session) | Restart session | The `sessionId` path parameter must name a test number in the key's project. |
| [`GET /platform/sessions/{sessionId}/safe-mode`](https://docs.polymorfa.com/api/bansafe/get-number-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`](https://docs.polymorfa.com/api/numbers/start-session) | Start session | The `sessionId` path parameter must name a test number in the key's project. |
| [`POST /platform/sessions/{sessionId}/stop`](https://docs.polymorfa.com/api/numbers/stop-session) | 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.

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

| 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.

## See also

- [Testing](https://docs.polymorfa.com/testing)
- [Send your first test message](https://docs.polymorfa.com/testing/quickstart)
- [Test numbers](https://docs.polymorfa.com/testing/test-numbers)
- [API keys](https://docs.polymorfa.com/development/api-keys)
