Core Concepts → Authentication

Authentication

Vittas Core uses API key authentication for all server-to-server calls. Pass your secret key as a Bearer token in the Authorization header on every authenticated request.

Required headers

Header	Value	Required
Authorization	Bearer <your-secret-key>	Yes
Content-Type	application/json	For POST/PATCH

bash

curl https://api.core.vittasinternational.com/api/widget/sessions \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

API key types

Vittas issues two types of keys per environment. Both are managed in the API Keys section of the developer portal.

Secret key

sk_test_… / sk_live_…

Used for server-to-server API calls. Has full read/write access. Never use in frontend code.

Publishable key

pk_test_… / pk_live_…

Used to initialise the frontend widget. Read-only access only. Safe to embed in HTML, JavaScript bundles, or native apps.

Test vs Live environments

All API calls are scoped to an environment. Pass ?environment=test or ?environment=live on GET endpoints that support it (e.g. listing sessions, webhooks).

Environment	Key prefix	Notes
Test	sk_test_ / pk_test_	Simulated payments only. No real money moves.
Live	sk_live_ / pk_live_	Real transactions. Requires KYC approval.

Switching environments in the portal

The toggle in the top-right of the developer portal switches the UI context. API calls always respect the key you send — test keys route to the test environment regardless of the toggle.

Authentication errors

HTTP status	Cause
401	Missing or invalid `Authorization` header
403	Valid key but insufficient permissions, or accessing a resource that belongs to another business
429	Rate limit exceeded (150 requests/minute). Back off and retry.

error response

json

{
  "meta": {
    "statusCode": 401,
    "message": "Unauthorized"
  }
}

Security best practices

Use environment variables

Never hardcode keys in source code. Use .env files or a secrets manager like AWS Secrets Manager.

Rotate keys regularly

Generate a new key from the portal whenever you suspect a key has been exposed. Old keys are revoked immediately on rotation.

Scope backend access

Only your server should ever hold the secret key. The publishable key is the only key safe for browsers and mobile apps.

Verify webhook signatures

Always validate the X-Vittas-Signature header before processing any webhook payload. See the Webhooks guide for code examples.