Authentication

PacSpace uses two authentication mechanisms depending on which API surface you're calling:

Balance API — API Key Authentication#

All Balance API and Advanced API requests are authenticated with an API key passed in the X-Api-Key header.

Key Format#

API keys follow the format:

pk_{environment}_{publicId}.{secret}

The full key includes both the public identifier and the secret, separated by a period. For example:

pk_live_abc123def456.7890ghijklmnop

Making Requests#

Pass the full key in the X-Api-Key header with every request.

cURL

curl https://balance-api.pacspace.io/api/v1/balance/derive/customer_001 \
  -H "X-Api-Key: pk_live_PUBLIC.SECRET"

Node.js

const response = await fetch(
  "https://balance-api.pacspace.io/api/v1/balance/derive/customer_001",
  {
    headers: {
      "X-Api-Key": "pk_live_PUBLIC.SECRET",
      "Content-Type": "application/json",
    },
  }
);

const balance = await response.json();

Python

import requests

response = requests.get(
    "https://balance-api.pacspace.io/api/v1/balance/derive/customer_001",
    headers={
        "X-Api-Key": "pk_live_PUBLIC.SECRET",
        "Content-Type": "application/json",
    },
)

balance = response.json()

Key Management Best Practices#

• Never expose keys in client-side code. API keys should only be used in server-to-server requests.
• Use test keys for development. Keys prefixed with pk_test_ route to the Sandbox API endpoint on dedicated sandbox infrastructure and don't affect production data.
• Rotate without downtime. Create a new key in the dashboard, update your application to use it, then revoke the old key. Both keys remain active during the transition.
• Scope keys by service. Create separate keys for separate services or environments so you can revoke one without affecting others.

Infrastructure separation: Sandbox and Production environments run on dedicated, isolated infrastructure. Test operations using pk_test_* keys never interact with production systems, ensuring complete isolation.

Error Responses#

Dashboard API — JWT Bearer Authentication#

The Dashboard API powers the PacSpace dashboard and is authenticated with JWT bearer tokens. Use this API to manage your account, API keys, billing, contracts, and webhooks.

Getting a Token#

Log in with your email and password to receive an access token:

curl -X POST https://balance-api.pacspace.io/dashboard/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-secure-password"
  }'

The response includes a token:

{
  "id": "usr_abc123",
  "email": "you@example.com",
  "name": "Jane Doe",
  "role": "owner",
  "isVerified": true,
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Making Authenticated Requests#

Pass the token in the Authorization header:

curl https://balance-api.pacspace.io/dashboard/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Token Lifecycle#

• Tokens expire after a set period. When a request returns 401, re-authenticate by calling the login endpoint again.
• Store tokens securely. Never log them or store them in version control.

Public Endpoints#

The following Dashboard API endpoints do not require authentication:

All other Dashboard API endpoints require a valid JWT bearer token.

Which Auth Method Should I Use?#

• Building an integration that emits deltas, queries balances, or verifies settlement? Use API Key auth with the Balance API.
• Managing your account programmatically — creating keys, configuring webhooks, checking billing? Use JWT Bearer auth with the Dashboard API.

Most developers only interact with API key authentication. The Dashboard API is primarily used by the web dashboard and for account automation.