02 authentication

Authentication

Stablix uses API keys to authenticate requests. You have two types of keys:

Key Type	Format	Use For	Safe to Expose?
Secret Key	sk_live_xxx	Backend API calls	❌ No
Public Key	pk_live_xxx	Checkout widget	✅ Yes

---

Secret Key (Backend)

Use your secret key for all server-side API calls. Pass it in the X-API-Key header:

curl https://api.stablix.xyz/api/v1/invoices \
  -H "X-API-Key: sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"amount": 99.99, "currency": "USDC", "chain": "solana"}'

// Node.js
const response = await fetch('https://api.stablix.xyz/api/v1/invoices', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.STABLIX_SECRET_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 99.99,
    currency: 'USDC',
    chain: 'solana'
  })
});

⚠️ Never expose your secret key in frontend code, public repositories, or client-side JavaScript.

---

Public Key (Frontend)

Use your public key for the checkout widget. Pass it in the X-Public-Key header (the widget handles this automatically):

StablixPay.setup({
  key: 'pk_live_your_public_key',  // Safe to expose
  amount: 99.99,
  currency: 'USDC',
  onSuccess: (res) => console.log('Paid!', res)
});

Public keys can only:

• Initialize checkout sessions

• Check payment status

They cannot access merchant data, release funds, or perform any other actions.

---

Test vs Live Keys

Environment	Secret Key	Public Key
Test	sk_test_xxx	pk_test_xxx
Live	sk_live_xxx	pk_live_xxx

Test keys:

• Work with testnet/devnet

• No real funds processed

• Same API behavior as live

// Test mode
StablixPay.setup({
  key: 'pk_test_your_test_key',
  amount: 10.00
});

---

Getting Your Keys

1. Log in to your Stablix Dashboard

2. Go to Settings → API Keys

3. Copy your keys

You can rotate keys at any time from the dashboard.

---

Environment Variables

Store your keys in environment variables:

# .env
STABLIX_SECRET_KEY=sk_live_your_secret_key
STABLIX_PUBLIC_KEY=pk_live_your_public_key

// Backend
const secretKey = process.env.STABLIX_SECRET_KEY;

// Frontend (Next.js)
const publicKey = process.env.NEXT_PUBLIC_STABLIX_PUBLIC_KEY;

---

Error Responses

Status	Error Code	Description
401	MISSING_API_KEY	No API key provided
401	INVALID_API_KEY	Key doesn't exist or is malformed
401	INVALID_PUBLIC_KEY	Public key doesn't exist
403	FORBIDDEN	Key doesn't have permission for this action

{
  "success": false,
  "message": "Invalid API key",
  "error": {
    "code": "INVALID_API_KEY"
  }
}