API keys & authentication

The platform’s two domains each have their own key. A third key — the Partner Key — is the master credential you use to provision both. Three keys, three scopes, three blast radii.

The three keys

Key	Format	Domain / base URL	Scope	Minted by
Partner Key	`tp_sk_live_…` / `tp_sk_test_…`	provisioning on both	All your merchants & TPAs	TagadaPay (Partner Hub)
CRM Key	`sk_crm_live_…` / `sk_crm_test_…` (legacy UUID accepted)	CRM — `/api/public/v1`	One merchant (`acc_xxx`)	`partners.crm.merchants.keys.create()`
Processing Key	`tp_sk_live_…` / `tp_sk_test_…`	Processing — `/api/tagadapay/v1`	One TPA (`tpa_xxx`)	`partners.processing.tpas.keys.create()`

Partner and Processing keys share the tp_sk_live_… / tp_sk_test_… prefix — you cannot tell them apart by looking at the string. The scope (partner vs one TPA) is attached server-side to the key, not encoded in the prefix. Keep your Partner Key clearly labelled in your secret manager; it is the only tp_sk_… key that can provision.

┌──────────────────────────────────────────────────────────────┐
│  PARTNER KEY  tp_sk_live_…   (scope: partner, server-side)     │
│  Can: provision merchants + TPAs, mint CRM/Processing keys,    │
│       submit KYB. Scope: ALL your merchants & TPAs.            │
│  Used by: your provisioning / onboarding pipeline only.        │
└───────────────┬───────────────────────────┬───────────────────┘
                │                            │
 crm.merchants.keys.create(acc)   processing.tpas.keys.create(tpa)
                ▼                            ▼
┌──────────────────────────┐   ┌──────────────────────────────┐
│  CRM KEY  sk_crm_live_…   │   │  PROCESSING KEY  tp_sk_live_… │
│  CRM API for ONE merchant │   │  Charging/reporting for ONE   │
│  (orders, customers, …)   │   │  TPA (charge, refund, …)      │
│  Scope: one acc_xxx       │   │  Scope: one tpa_xxx           │
└──────────────────────────┘   └──────────────────────────────┘

Never use the Partner Key in your runtime path. Mint a CRM Key and/or a Processing Key per merchant on creation, store them next to the merchant’s record in your secret manager, and use only those thereafter. A leaked scoped key exposes one merchant — never your whole partnership.

API keys ≠ Ops roles. Partner / CRM / Processing keys authenticate the Node SDK and REST. They do not carry Clerk tgdRoles and do not open the Ops dashboard. Human access to Ops uses the payment_ops job (+ scope) — see Partners overview → Humans vs machines and IAM Overview.

Getting your Partner Key

Your first key cannot be bootstrapped via API — it’s minted for you.

Step	Who	What
1	TagadaPay	Activates your partnership (`par_xxx`)
2	TagadaPay / your account manager	Mints a live Partner Key in the Hub (`tp_sk_live_…`)
3	Your backend	Uses that key for all provisioning calls

Use a live Partner Key for production merchants. A test Partner Key (tp_sk_test_…) can only mint test keys — it cannot mint live CRM or Processing keys. Trying to do so returns 403 mode_escalation_forbidden.

CRM Keys (`sk_crm_…`) — the merchant control plane

A CRM Key authenticates the public API (/api/public/v1/*) for one merchant (acc_xxx): orders, stores, customers, subscriptions, promotions.

const partner = new Tagada(process.env.TAGADA_PARTNER_KEY!);

const key = await partner.partners.crm.merchants.keys.create('acc_xxx');
// {
//   object: 'crm_key',
//   id: '…',
//   accountId: 'acc_xxx',
//   prefix: 'sk_crm_live_a1b2…',   // safe to store/log/display
//   token: 'sk_crm_live_a1b2c3…',  // RETURNED ONCE — store immediately
//   name: 'Your Partner — merchant_42',
//   createdAt: '2026-04-29T…',
// }

const keys = await partner.partners.crm.merchants.keys.list('acc_xxx');
await partner.partners.crm.merchants.keys.revoke(key.id);

New format, backward compatible. New CRM Keys are minted as sk_crm_…. Existing UUID tokens keep working unchanged — authentication looks up the presented token regardless of prefix. You don’t have to migrate anything.

The token field is only returned on creation. Only the prefix is kept for display. If you lose the token, revoke and mint a new one.

A merchant client then uses that token directly:

const merchant = new Tagada(crmKey.token); // sk_crm_live_…
await merchant.orders.list();

Processing Keys (`tp_sk_…`) — charging & reporting

A Processing Key authenticates the Processing API (/api/tagadapay/v1/*) for one TPA (tpa_xxx): charges, refunds, balance transactions, disputes, payouts.

const subKey = await partner.partners.processing.tpas.keys.create('tpa_xxx');
// optional: { mode: 'test' } for a test key
// {
//   object: 'processing_key',
//   id: 'ak_xxx',
//   tpaId: 'tpa_xxx',
//   prefix: 'tp_sk_live_a1b2c3d4',     // safe to store/log/display
//   secret: 'tp_sk_live_a1b2c3d4…',    // RETURNED ONCE — store immediately
//   label: 'Your Partner — merchant_42',
//   status: 'active',
//   createdAt: '2026-04-29T…',
// }

const keys = await partner.partners.processing.tpas.keys.list('tpa_xxx');
await partner.partners.processing.tpas.keys.revoke(subKey.id);

Labels are auto-assigned as {PartnerName} — {externalRef} (falls back to the TPA id when externalRef is missing). Set externalRef on the TPA so keys are easy to tell apart.

The secret field is only returned on creation. Store it in your secret manager immediately. If you lose it, revoke and re-mint.

Recommended: one record per merchant, per environment

your_db.merchants table:
  external_ref            = 'merchant_42'        // your id — used as externalRef
  tagada_merchant_id      = 'acc_xxx'            // CRM
  tagada_crm_key          = (encrypted sk_crm_live_…)
  tagada_tpa_id           = 'tpa_xxx'            // Processing
  tagada_store_id         = 'store_xxx'
  tagada_processing_key   = (encrypted tp_sk_live_…)

Don’t share keys across merchants — the security boundary disappears if you do.

Authenticating requests

All three keys use the same Bearer header; only the base URL differs by domain.

# CRM domain
curl https://api.tagada.io/api/public/v1/orders \
  -H "Authorization: Bearer sk_crm_live_xxx"

# Processing domain
curl -X POST https://api.tagada.io/api/tagadapay/v1/payments/process \
  -H "Authorization: Bearer tp_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "storeId": "store_xxx", "paymentInstrumentId": "pi_xxx", ... }'

The SDK handles the header and the right base URL for you:

const merchant = new Tagada(crmKey.token);       // routes CRM calls to /api/public/v1
const charging = new Tagada(processingKey.secret); // routes processing calls to /api/tagadapay/v1

Scope enforcement

The server enforces scope on every request:

Key	Endpoint	Result
Partner key (payfac WL)	`processing.tpas.create`	✅ allowed
Partner key (CRM-only)	`processing.tpas.create`	❌ 403 `payfac_required` — use `applications.create` / embed
Partner key	`processing.applications.create`	✅ allowed (sub-merchant `accountId` required)
Partner key	`crm.merchants.create`	✅ allowed
Processing key	`processing.tpas.create`	❌ 403 — can’t provision
Processing key	`payments.process`	✅ only for its own `tpa_xxx`
Processing key for tpa_A	`payments.process` with a store of tpa_B	❌ 403
CRM key	`orders.list`	✅ only for its own `acc_xxx`
CRM key	`/api/tagadapay/v1/*` (processing)	❌ 403 — wrong domain

Revocation & rotation

// Mint the new key first, deploy it, THEN revoke the old one.
const next = await partner.partners.processing.tpas.keys.create('tpa_xxx');
await yourSecretManager.set('merchant_42.processing_key', next.secret);
// after confirming no traffic on the old key:
await partner.partners.processing.tpas.keys.revoke('ak_old_xxx');

Revocation is immediate and irreversible — subsequent calls with that secret get HTTP 401; in-flight calls complete. A lastUsedAt timestamp updates on every call, useful to confirm a key is safe to revoke.

Test mode

Test keys carry a _test_ segment (tp_sk_test_… for both Partner and Processing keys, sk_crm_test_… for CRM keys):

const partnerTest = new Tagada(process.env.TAGADA_PARTNER_TEST_KEY!);
// Payfac WL only — CRM-only partners use applications.create / embed instead
const tpa = await partnerTest.partners.processing.tpas.create({ legalName: 'Acme SAS', accountId: 'acc_xxx', country: 'FR' });
const testKey = await partnerTest.partners.processing.tpas.keys.create(tpa.id); // tp_sk_test_…

Test mode routes to test processors, returns mock 3DS challenges, moves no real money, and lives in a fully isolated namespace — you can’t mix test and live keys in the same client.

Get Started

CRM provisioning

Processing provisioning

REST reference

Server-to-server payments

Money movement

Reporting & disputes

End-to-end

API keys & authentication

API keys & authentication

The three keys

Getting your Partner Key

CRM Keys (`sk_crm_…`) — the merchant control plane

Processing Keys (`tp_sk_…`) — charging & reporting

Recommended: one record per merchant, per environment

Authenticating requests

Scope enforcement

Revocation & rotation

Test mode

​API keys & authentication

​The three keys

​Getting your Partner Key

​CRM Keys (sk_crm_…) — the merchant control plane

​Processing Keys (tp_sk_…) — charging & reporting

​Recommended: one record per merchant, per environment

​Authenticating requests

​Scope enforcement

​Revocation & rotation

​Test mode

API keys & authentication

The three keys

Getting your Partner Key

CRM Keys (`sk_crm_…`) — the merchant control plane

Processing Keys (`tp_sk_…`) — charging & reporting

Recommended: one record per merchant, per environment

Authenticating requests

Scope enforcement

Revocation & rotation

Test mode