Documentation / Authentication · Updated 16 September 2026
Secrets with a clear boundary.
Use Authorization: Bearer cg_test_… on every API request. Keys are bound to a single merchant workspace; another workspace’s payment IDs return 404. Browser session cookies do not authenticate API requests.
Key lifecycle
- Enable two-factor authentication in your workspace. A session authenticated with a second factor is required to issue keys.
- Choose a useful label, permissions, and a 7, 30 or 90 day lifetime.
- Save the secret when it appears. Only its hash and a display prefix are stored.
- Create a replacement before expiry, deploy it to your server, then revoke the old key.
- If a key is exposed, revoke it immediately from Developers. Revocation does not require MFA and cannot be undone.
Permissions
| Scope | Allows |
|---|---|
| payments:read | Retrieve a test payment intent |
| payments:write | Create a test payment intent |
| payments:simulate | Set a pending test intent to succeeded or failed |
Any valid key can read its own workspace ID and enabled capabilities at GET /account. Up to 10 active keys can exist per workspace. Expired and revoked keys fail with 401; suspension fails with 403.
Do not share keys with support. To report a failed request, send its request ID and a redacted description through your workspace support panel.