Get your API key
Sign in to the Cosmos Pay developer platform, choose an environment, and mint an API key with the scopes your integration needs.
Every request to Cosmos Pay is authenticated with an API key. You create and manage keys in the developer dashboard. A key carries two things that matter: the environment it belongs to (which picks testnet or mainnet, on every chain) and the scopes it's allowed to use.
Create a key
- Sign in to the developer platform at dev.cosmospay.lat and open the Dashboard.
- Pick the environment with the dashboard's Test / Production switch:
- Test issues
dv_…keys that run on testnet; use these while developing. - Production issues
prod_…keys that run on mainnet; use these to go live.
- Test issues
- Go to API Keys → Create.
- Give the key a name (and an optional description) so you can recognise it later.
- Choose a role:
- User: scoped. Pick exactly the permissions it needs from the matrix (per resource: read and/or write for payments, webhooks, products, customers and analytics).
- Admin: full access, which bypasses the scope matrix. Use sparingly.
- Create, then copy the key immediately.
Shown only once
The full key is displayed once, at creation (and again only if you rotate it). Store it in a secret manager or your server's environment variables right away, because you can't view it again.
Use the key
Keep the key on your server and pass it to the SDK (or send it as a Bearer token to the REST API):
import { Client } from '@cosmosapp/pay_sdk';
// Reads e.g. COSMOS_PAY_API_KEY from your server environment. Never hard-code it.
const client = new Client({ apiKey: process.env.COSMOS_PAY_API_KEY });Authorization: Bearer dv_xxxxxxxxxxxxxxxxxxxxxxxxLeast privilege
Give each key only the scopes it needs. A server that just creates payments can use a key with
payments:write and payments:read and nothing else, so a leaked key can't do more than its job.
Good practice
- One key per environment / service. Don't reuse a
prod_key in test, and rotate keys per service so you can revoke one without taking down the rest. - Never ship a key to the browser. The web client signs transactions with the user's wallet and does not need your key.
- Rotate on exposure. If a key leaks, rotate it in the dashboard. The old value stops working immediately.
Next steps
Getting started
Everything you need before your first Cosmos Pay payment, including what it is, how a payment flows, and the two ways to integrate.
Embed a pay button or checkout
Take a payment on your own website with one script tag, using a button that opens the hosted checkout or a compact checkout drawn inside your page.