API Keys

Create and manage your Moosyl API keys: when to use a secret or a publishable key, Sandbox vs Production, and how to replace a key safely.

Every request to the Moosyl API is authenticated with an API key. Each key has a type (secret or publishable) and belongs to one environment (Sandbox or Production).

Secret and publishable keys

	Secret key	Publishable key
Where it lives	Your server only	Your app or website
Create payment requests	Yes	No
Create checkout sessions	Yes	No
Products, customers, subscriptions, invoices	Yes	No
Read a payment request, list payment methods, start a payment	Yes	Yes

Use the publishable key in the Flutter and React Native SDKs. Anything that creates a charge or reads your business data needs the secret key, so keep it on your server and out of mobile and frontend code.

Webhook signatures are not checked with an API key. Each webhook has its own secret, which you set when you create it. See Webhooks.

Create a key

Open the dashboard and select the environment in the environment switcher.
Go to API Keys and click Create API Key.
Choose the key type, then copy the key.

Keys are random strings with no prefix, so label them clearly in your password manager or secrets store.

Sandbox and Production

Sandbox keys only see sandbox data. Payments are simulated and no money moves. Use them while you build and with the test phone numbers.
Production keys take real payments. The Production environment is available once your business is approved.

A key only works in its own environment. Webhooks are per environment too, so create them in both.

Use a key

Send the key as is in the Authorization header. There is no Bearer prefix.

curl https://api.moosyl.com/configuration \
  -H "Authorization: YOUR_PUBLISHABLE_KEY"

This request returns the payment methods enabled for the key's environment, which makes it a quick way to check that a key works.

With the TypeScript SDK, pass the key to the constructor:

import { Moosyl } from "moosyl-sdk";

const moosyl = new Moosyl(process.env.MOOSYL_SECRET_KEY!);

Keep keys in environment variables rather than in your code:

MOOSYL_SECRET_KEY=YOUR_SECRET_KEY
MOOSYL_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY

Replace a key

To replace a key without downtime:

Create a new key of the same type in the same environment.
Deploy your app or server with the new key.
Delete the old key under API Keys.

If a secret key leaks, delete it right away, then create and deploy a new one. Requests with a deleted key are rejected.

Troubleshooting

Requests are rejected as unauthorized

The key is from the other environment. Sandbox keys don't work against Production data, and the reverse.
A publishable key is used for an action that needs the secret key, such as creating a payment request.
The header has extra characters. Send the key exactly as copied, without Bearer or surrounding spaces.
The key was deleted.

It works in the sandbox but not in production

Create production keys and webhooks in the Production environment and deploy them. Sandbox keys and webhooks are not copied over.