API keys and project credentials

Polymorfa has distinct team and project credentials. The full token is returned once. Store it securely when it is created; the Console cannot reveal it again. A newly created project credential starts masked in the save dialog. Select Reveal to read it or Copy to store it securely before closing. Opening a different credential starts masked again. Switching projects hides the previous project’s credential immediately.

​

Ownership

Both team and project keys offer You and Service account ownership with configurable permissions.

• You creates a personal key. Removing your team membership, demoting you below owner or admin, banning your account, or deleting your account revokes your personal keys. Restoring access does not restore revoked keys.
• Service account creates a named identity for the integration. Its key survives changes to the person who created it. Revoke the key when the integration no longer needs access.

Existing keys retain their access as service-owned keys. Ownership does not expand the selected permissions or the key’s team/project scope. Automatic personal-key revocations take effect as revocation updates reach active connections.

​

Billing controls

Team keys need billing:read to read spending limits and funding priorities, and billing:manage to change them. These permissions are team-only. Project credentials and client tokens cannot use them. Existing keys do not gain new billing permissions automatically. See Usage for controls and the revision checks used by the API.

​

Request logs

Team keys and project credentials need logs:read to read the request log. Select Request logs → Read when you create the key. Existing keys, including keys created with every permission, do not gain it automatically.

​

Create a project credential

1. Open the project in the Console.
2. Open Settings → API Keys and choose Create project key.
3. Choose You or Service account, enter a label, and choose an expiry.
4. Select the smallest permission set required by the integration.
5. Create the credential and copy the full token immediately.

Choose All, Restricted, or Read only permissions. In each resource row, None grants no access, Read grants the available read actions, and Write grants read access plus the resource’s write or management actions. Rows only offer the access levels supported by that resource. Select Webhooks → Read to inspect endpoints or Webhooks → Write to manage them. Delivery inspection and retries have their own Webhook deliveries row. Issuing browser tokens and updating their session rules requires session write, message write, contact read, presence read/observe, and MCP permissions together. See client token delegation. Project credentials require at least one project-safe scope. See Authentication for the scope list. Selecting * grants every project-safe action available to your team when the credential is issued. It does not grant access to team membership, team billing or settings, team API-key administration, or dashboard-only operations. Only a signed-in person in the Console can create, list or revoke organization keys and project tokens. API keys and project tokens cannot manage either credential kind. The public API provides credential endpoints only for client tokens.

​

Review and revoke

The Console lists each credential’s prefix, last four characters, label, scopes, expiry, creation time, last use, and revocation time. It never displays the full token again. Revoke a credential from the same screen. Confirm that the integration has switched to its replacement before revoking a credential during planned rotation.

​

Team keys

Open the team without selecting a project, then open Settings → Team API Keys and choose Create team key. The public Platform API does not provide key or token management operations. Choose ownership and permissions in the same way as for a project key. The selected actions apply across the team and every project in that team. Human-only account operations still require a signed-in dashboard user. Raw WhatsApp bridge connections require a project key with bridge:connect; they do not accept team keys.

​

Safety rules

• Use a project credential for workloads that only need one project.
• Treat a cross-project 404 resource not found as a boundary failure; do not retry with another project’s identifier.
• Never use a client token to mint another credential.
• Rotate by deploying the new credential before revoking the old one.
• Treat 404 credential not found as an absent or inaccessible credential. Do not use identifiers from another team or project.

​

First-use notifications

Enable API key first use in My Notifications to receive email when a newly issued team or project key first passes credential verification. This alert does not confirm that the request completed successfully. It does not backfill first use for keys issued before the alert was introduced. First-use security emails identify the team or project credential and show the request’s reported client, available IP and approximate location, and time. They include Account settings and Manage sessions links. This context identifies a credential’s network use; it does not identify a human operator. Unavailable request details are labeled Unavailable. See Personal notification settings to choose email delivery for API-key first use.