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.
2. Navigate to Settings > API Keys.
3. Click Create API Key.
4. Give the key a descriptive name (e.g., "Backend — staging" or "Mobile app").
5. Copy both the publishable key and the secret key.

You can optionally restrict the key to a subset of permissions. If you leave permissions unrestricted, the key inherits the full scope of its owner.

Authentication

All API requests are authenticated with a Bearer token in the Authorization header. Use your secret key for server-side calls:

curl https://api.miracle.com/v1/payments \
  -H "Authorization: Bearer sk_test_your_secret_key" \
  -H "Content-Type: application/json"

const response = await fetch('https://api.miracle.com/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.miracle.com/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: create a new key pair, update your application, verify it works, then revoke the old key. There is no automatic rotation.

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.
• Rotate keys immediately if you suspect they have been compromised. Create a new pair, deploy it, then revoke the old key.
• 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 -->