Authentication & Tokenization
Authenticate with your API key, and exchange it for an access token to tokenize cards.
All requests to the Tonder API must be authenticated. We use an API key to ensure that all
communication comes from a trusted source. An unauthenticated request returns 401 Unauthorized.
Authentication methods
| Credential | Sandbox | Production |
|---|---|---|
| API key | dashboard-stage.tonder.io → Developers → API Keys | dashboard.tonder.io → Developers → API Keys |
Required headers
| Header | Description |
|---|---|
Authorization | Your API key, prefixed with Token. |
Content-Type | Must be application/json for requests with a body. |
Authorization: Token <YOUR_API_KEY>
Content-Type: application/jsonThe scheme is Token followed by a space and then your key — not Bearer. If the space is
missing, you get 401 Unauthorized.
Also send X-Request-Id with a UUID v4 per request: it isn't an authentication header, it's the
idempotency key that deduplicates retries. See
Idempotency.
Complete request example
import requests
API_KEY = "your_api_key_from_dashboard"
BASE_URL = "https://stage.tonder.io/api/v1" # use https://app.tonder.io in production
request_body = {
"operation_type": "payment",
"amount": 100.00,
"currency": "MXN",
"customer": {"name": "Test Customer", "email": "test@example.com"},
"payment_method": {"type": "SPEI"},
"client_reference": "ORD-001"
}
headers = {"Authorization": f"Token {API_KEY}", "Content-Type": "application/json"}
response = requests.post(f"{BASE_URL}/process/", headers=headers, json=request_body)
print(f"Status: {response.status_code}")
print(f"Response: {response.json()}")curl -X POST https://stage.tonder.io/api/v1/process/ \
-H "Authorization: Token <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"operation_type": "payment",
"amount": 100.00,
"currency": "MXN",
"customer": { "name": "Test Customer", "email": "test@example.com" },
"payment_method": { "type": "SPEI" },
"client_reference": "ORD-001"
}'Card tokenization
To store or process cards with a smaller PCI scope, exchange your key for a short-lived access
token: GET /api/v1/tokenization/auth/ (with your API key) returns an access_token (JWT). That
token authorizes tokenizing the card data (X-Skyflow-Authorization header). See the full flow in
Card payments.
Security best practices
- Never expose your API key in client-side code, mobile apps, or version control.
- Use environment variables to store credentials — don't leave them in the code.
- Rotate keys immediately if you suspect they leaked.
- Use separate keys for sandbox and production.
- Restrict credential access on a need-to-know basis.
Authentication errors
| Code | Message | Cause | Fix |
|---|---|---|---|
401 | Unauthorized | Invalid or missing API key | Check that your key is correct and includes the Token prefix (with a space). |
403 | Forbidden | The key isn't allowed on this endpoint | Review your account permissions or contact support. |