Authentication

Tsara uses different credentials for server-side API calls, hosted checkout creation, embedded widgets, and webhook verification. Using the correct credential for each surface is important: public credentials identify an integration, while secret credentials authorize access to business data and money movement.

Credential types

Credential	Typical prefix	Where it is used	Safe in frontend code?
Business secret key	`sk_live_` or `sk_test_`	Server-to-server API requests	No
Business public key	`pk_live_` or `pk_test_`	Checkout creation	Yes, only for documented public-key flows
Widget public key	`rwpk_live_` or `rwpk_test_`	Ramp bootstrap and session creation	Yes
Ramp session token	Returned at runtime	Ramp quote, options, initiate, and status calls	Short-lived; keep scoped to the active session
Webhook secret	Dashboard-generated	Verifying incoming webhook signatures	No

Business server-to-server endpoints

Send the active business secret key as a Bearer token:

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Example:

curl --request GET \
  --url https://YOUR_BASE_URL/v1/transactions \
  --header 'Authorization: Bearer sk_live_xxxxx' \
  --header 'Accept: application/json'

This applies to the main business API groups:

/v1/payment-links
/v1/transactions
/v1/webhook
/v1/api-keys
/v1/fiat
/v1/payouts
/v1/refunds
/v1/stablecoin
/v1/customers
/v1/bill
/v1/ramp/widgets
/v1/ramp/transactions

Checkout creation

POST /v1/checkout uses the business public key in the request body:

{
  "public_key": "pk_live_xxxxx"
}

Server-side checkout reads and updates use the business secret key:

GET /v1/checkout
GET /v1/checkout/account
GET /v1/checkout/status
POST /v1/checkout/crypto

Ramp widget authentication

Ramp widgets use a scoped session model:

Load public configuration with GET /v1/ramp/widgets/bootstrap and the widget public key.
Create a session with POST /v1/ramp/widgets/session, the widget public key, and the current origin.
Use the returned session_token for quote, options, verification, initiation, and status calls.

Live widgets require an allowed origin. Treat the session token as temporary authorization for one widget session, not as a replacement for the business secret key.

Test and live modes

Use credentials from the same mode throughout one flow. Do not mix test and live keys, widget keys, transactions, or webhook secrets. A test credential cannot be used to query a live resource, and a live secret should never be placed in a test client bundle.

Key handling checklist

store secret keys and webhook secrets in environment variables or a secret manager
send secret keys only from your backend over HTTPS
redact credentials from application logs and support screenshots
rotate a secret immediately if it was committed, logged, or exposed to frontend code
update webhook verification separately when rotating a webhook secret
return a generic error to clients; keep detailed authentication diagnostics in protected server logs

Troubleshooting `401` and `403`

confirm the endpoint expects the credential type you supplied
confirm the key belongs to the same test/live mode as the resource
confirm the Authorization value starts with Bearer for secret-key endpoints
confirm the business or requested product feature is enabled
confirm a ramp session has not expired and its origin matches the widget configuration