Get API Credentials

API key types

Every API key is a pair — a secret key and a publishable key, generated together. A third credential type, the client secret, is generated per checkout session. Each credential serves a different purpose:

Test vs. live keys

Each key pair belongs to an environment:

The environment is determined server-side from the key prefix. You do not need to pass an environment parameter in your requests.

Get your keys

1. Log in to the Miracle Portal and switch it to the mode you need: test mode issues test keys (sk_test_, pk_test_), live mode issues live keys.
2. Open API Keys in the sidebar and choose Create key.
3. Choose the key type: a secret key for server-side calls, or a public key for tokenization in the browser.
4. Give the key a descriptive name, for example "Backend, staging" or "Mobile app". If you manage more than one merchant, choose the merchant the key belongs to.
5. For a secret key, select the permissions it needs. A key carries only the permissions selected for it: a key with none authenticates but cannot call anything. For the hosted payment page, select at least payment-experience:checkout:create and payment-experience:checkout:view; for payments created directly through the API, payment-processing:transaction:create and payment-processing:transaction:view.
6. Optionally limit the key to IP ranges and set an expiry, check the summary, and choose Create and reveal.
7. Copy the key the wizard shows.

Authentication

All API requests are authenticated with a Bearer token in the Authorization header. Use your secret key for server-side calls. In the examples, replace <api-host> with the API host your operator gave you:

curl https://<api-host>/v1/payments \
  -H "Authorization: Bearer sk_test_your_secret_key" \
  -H "Content-Type: application/json"

const response = await fetch('https://<api-host>/v1/payments', {
  headers: {
    'Authorization': `Bearer ${process.env.MIRACLE_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
});

const { data } = await response.json();

import os
import requests

response = requests.get(
    "https://<api-host>/v1/payments",
    headers={
        "Authorization": f"Bearer {os.environ['MIRACLE_SECRET_KEY']}",
        "Content-Type": "application/json",
    },
)

data = response.json()["data"]

When to use which credential

Publishable keys only grant access to the /tokenize and /payment-methods endpoints. Client secrets additionally grant access to /payments, but only for the associated checkout session. Any other endpoint will return 403 Forbidden.

Idempotency

All write operations (POST, PATCH, DELETE) require an Idempotency-Key header. This lets you safely retry requests without creating duplicate side-effects (e.g., double-charging a customer).

Idempotency-Key: your-unique-request-id

Use a unique value per request — a UUID v4 works well. The API will return the same response for repeated calls with the same idempotency key.

Key lifecycle

API keys have three possible states:

To rotate a key, select it in the Portal and choose Rotate, or call POST /v1/api-keys/{id}/rotate with an Idempotency-Key. You get a new secret with the same name, permissions and restrictions, shown once. The old key keeps working for a grace period (24 hours from the Portal; through the API, graceHours from 0 to 720), so you can switch your application without downtime. Keys never rotate on their own.

While your merchant account, or the account of the operator above it, is suspended or disabled, every key you hold answers 401 Unauthorized, test keys included, and no key can be created or rotated (409 CONFLICT). The same keys work again once the account is reinstated.

Security best practices

• Never expose secret keys in client-side code. Do not include sk_ keys in JavaScript bundles, mobile apps, or HTML. Use publishable keys (pk_) for client-side calls.
• Store keys in environment variables, not in source code or version control.
• Use test keys for development. Switch to live keys only when you are ready to process real payments.
• Act immediately if you suspect a key has been compromised: revoke it and issue a new one, or rotate it through the API with "graceHours": 0 so the old key stops working within 30 seconds.
• Restrict permissions when a key does not need full API access. For example, a key used only for creating payments does not need refund permissions.

Next step

You have your API keys — now create your first payment.

Your First Payment -->