> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tagada.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication and keys

> Secret keys for your server, publishable keys for the browser, test and live modes.

> [!NOTE]
>
> **Preview.** The Payments API (V3) is live at `https://api.tagada.io/v1`, but it is not open to self-serve integrations yet: merchant secret keys cannot be created from the dashboard. Every merchant processes on [V2](https://docs.tagada.io/payments-api/v2-or-v3.md) today. Contact [api-support@tagadapay.com](mailto:api-support@tagadapay.com) if you plan a new integration.

Authenticate every request with a bearer key in the `Authorization` header:

```bash theme={null}
curl https://api.tagada.io/v1/payments \
  -H "Authorization: Bearer tsk_test_..." \
  -H "Payments-Version: 2026-11-01"
```

A request without a valid key gets `401 authentication_required`.

> [!WARNING]
>
> Payments API keys are not Commerce API (V2) keys. A dashboard API key that works on `/api/public/v1` does not work on `/v1`, and the reverse is also true.

## Key types

| Key | Prefix | Where it runs | Bound to |
| - | - | - | - |
| Secret | `tsk_live_`, `tsk_test_` | Your server only | One account |
| Publishable | `tpk_live_`, `tpk_test_` | The shopper's browser | One account, one store, a list of allowed origins |
| Platform | `tplk_live_`, `tplk_test_` | TagadaPay internal services | Several accounts, selected per request with `Payments-Account` |

Platform keys are not issued to merchants. Only a platform key may send `Payments-Account`.

> [!WARNING]
>
> A secret key can create, capture and refund payments. Never ship it to a browser, a mobile app or a public repository.

## Test and live mode

The key decides the mode, not the host. A `_test_` key creates test payments that never move money; a `_live_` key creates real ones. Objects of one mode are invisible to keys of the other: a test payment id read with a live key returns `404`.

## Publishable keys

A publishable key lets a browser confirm **one payment it holds the `client_secret` of**, read that payment, mount card fields and wallets, and create payment methods. It cannot create payments, list them or refund them.

Get the publishable key of a store from your server:

```bash theme={null}
curl https://api.tagada.io/v1/publishable-keys \
  -H "Authorization: Bearer tsk_test_..." \
  -H "Payments-Version: 2026-11-01" \
  -H "Idempotency-Key: 9d0b1c3e-1f2a-4b5c-8d7e-6f5a4b3c2d1e" \
  -H "Content-Type: application/json" \
  -d '{"store": "store_0123456789ab", "allowed_origins": ["https://shop.example.com"]}'
```

```json theme={null}
{
  "object": "publishable_key",
  "id": "...",
  "key": "tpk_test_...",
  "store": "store_0123456789ab",
  "mode": "test",
  "allowed_origins": ["https://shop.example.com"],
  "created_at": "2026-11-01T10:00:00.000Z"
}
```

* The first call creates the key. Later calls return the **same key** and replace its `allowed_origins` with the list you send, so always send every origin of the store.
* The key's mode is the mode of the secret key that asked for it.
* A browser request with a publishable key must come from one of the `allowed_origins` (the `Origin` header). Otherwise it gets `403 permission_denied`.

## Rate limits

Requests are counted per key kind and per account:

| Caller | Sustained | Burst |
| - | - | - |
| Secret key, per account | 100 requests per second | 200 |
| Publishable key | 20 requests per second | 40 |
| Account, all keys | 200 requests per second | 300 |

Above the limit, the API answers `429 rate_limited` with a `Retry-After` header in seconds.

## Getting keys

Self-serve secret keys are **coming soon**: the dashboard does not create Payments API keys yet. During the preview, contact [api-support@tagadapay.com](mailto:api-support@tagadapay.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.