Authentication

Create a secret key in Dashboard → Developers and send it as a bearer token. The key is shown once, so store it in your server's environment variables.

curl https://utopia-payments.com/api/v1/account \
  -H "Authorization: Bearer $UTOPIA_API_KEY"

Live and test keys

Keys start with sk_live_ or sk_test_. Each kind has its own products, customers, payments, subscriptions, webhooks and events: nothing is shared between them. See Test mode.

Account approval and revoking

Your merchant account must be approved before keys can be used. Revoke a key from the dashboard at any time; requests using it stop immediately with 401 UNAUTHORIZED.

Looking after your keys

Each mode allows 10 active keys, which is what makes a clean rotation possible: create the new key, deploy it, confirm the old one has stopped being used, then revoke it. The dashboard lists when each key was last used, so you can tell whether anything still depends on one before you revoke it. Revoked keys don't count towards the 10. Creating a key asks you to confirm your sign-in again.

If a key leaks, revoke it first and ask questions afterwards — a revoked key is refused from the next request, and there is no way to un-leak one that is still valid. Then create a replacement, deploy it, and check Dashboard → Payments for charges you don't recognise. A leaked key cannot move money to anyone else, but it can create checkouts and read your customers and payments. Treat a key committed to a repository as leaked even in a private one.

Going live

A test key exercises everything except a real card, and its objects are separate, so nothing has to be cleaned up when you switch. To go live: get the account approved, create an sk_live_ key, check GET /account reports payments_enabled: true, and add live-mode webhook endpoints — endpoints, like everything else, belong to one mode, so the test ones will not fire in live. Keep both keys in configuration rather than in code, so switching mode is a deployment, not an edit.