API Key Provisioning
Create API keys for a merchant so their developers can integrate with the Miracle PSP payment API. API keys authenticate every request the merchant's application makes to the platform.
How to Create Keys
Portal: Select the Merchant, then navigate to API Keys and select Create.
When you create a new API key, the system generates a key pair:
| Key | Prefix | Purpose |
|---|---|---|
| Secret key | sk_test_ or sk_live_ | Authenticates server-side API requests. Must be kept confidential. |
| Publishable key | pk_test_ or pk_live_ | Used in client-side code (e.g., payment forms). Safe to expose in frontend. |
| Client secret | cs_ | Session-scoped token for HPP and widget flows. Automatically generated when creating a CheckoutSession. Short-lived and bound to a single session — not created or managed manually. |
The secret key is shown only once at creation time. Copy it immediately and store it securely. It cannot be retrieved again after the creation dialog is closed.
The client secret is not created through the Portal. It is returned in the POST /v1/checkout-sessions response and is used by the payer's browser to authenticate requests within that checkout session.
Key Types
| Environment | Secret Key | Publishable Key | Purpose |
|---|---|---|---|
| Test | sk_test_... | pk_test_... | Sandbox transactions only. Use for integration development and testing. |
| Live | sk_live_... | pk_live_... | Production transactions. Only available after merchant status is live. |
Always start with test keys. Live keys should only be created and shared after the merchant has successfully tested their integration in sandbox mode.
Key Scope
API keys can be scoped to different levels of the entity hierarchy:
| Scope | Access | Use Case |
|---|---|---|
| Merchant-scoped | Operations for a single merchant only | Standard merchant integration — one key pair per merchant. |
| Tenant-scoped | Cross-merchant access within the tenant | Bulk operations, reporting, settlements, and administrative APIs that span multiple merchants. |
Merchant-scoped keys are the default. Tenant-scoped keys are created from the tenant-level API Keys page and should only be issued to the tenant's own engineering team, not to individual merchants.
Permission Restrictions
By default, an API key inherits the full permission set of its owner level (merchant or tenant). You can optionally restrict a key to a subset of permissions when creating it.
Portal: When creating a key, expand Permission Restrictions and select only the permissions the key should have. If no restrictions are specified, the key has full access for its scope.
Examples of restricted keys:
- A key that can only create payments but not issue refunds
- A read-only key for reporting and transaction lookups
- A key limited to webhook management
Permission restrictions are immutable after creation. To change permissions, revoke the existing key and create a new one with the desired restrictions.
Sharing Keys with Merchant Developers
When providing API keys to a merchant's development team:
- Share the secret key through a secure channel — use a secrets manager, encrypted message, or secure file transfer. Never send secret keys over email or unencrypted chat.
- Share a link to the merchant documentation — point them to the integration guides so they can get started quickly.
- Recommend starting with test keys — the merchant should build and verify their integration in sandbox mode before switching to live keys.
Managing Keys
View Active Keys
Portal: Select the Merchant, then navigate to API Keys. You can see all active keys, their creation date, and last used timestamp. Note that only the key prefix is displayed — the full secret key is never shown after creation.
Rotate Keys
To rotate a key:
- Create a new key pair
- Update the merchant's application to use the new key
- Revoke the old key once the new one is confirmed working
This approach avoids downtime during the transition.
Revoke Keys
Portal: Select the key and choose Revoke. Revoked keys stop working immediately. Any API requests using a revoked key will receive an authentication error.
If a secret key is compromised, revoke it immediately and create a replacement.