Authentication

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

Balance API - API Key Authentication#

All Balance 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_PUBLIC.SECRET

Making Requests#

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

cURL

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

Node.js

const response = await fetch(
  "https://app.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://app.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 Sandbox; use the Sandbox URL from your PacSpace dashboard or SDK sandboxUrl configuration.
• 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.

Environment separation: Test operations using pk_test_* keys do not affect production records.

Error Responses#

Dashboard API - Browser Session Authentication#

The Dashboard API powers the PacSpace dashboard and is authenticated with httpOnly session cookies. Use this API to manage your account, API keys, billing, environments, and webhooks. Unsafe cookie-authenticated mutations also send X-Pacspace-CSRF: 1.

Starting a Session#

Log in with your email and password to establish a dashboard session. Browser clients receive httpOnly Set-Cookie headers; cURL examples should use a cookie jar:

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

The response includes user/session display data, not bearer tokens:

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

Making Authenticated Requests#

Send the dashboard session cookies on protected routes. Add X-Pacspace-CSRF: 1 for unsafe methods (POST, PUT, PATCH, DELETE):

curl https://app.pacspace.io/dashboard/api-keys \
  -b pacspace-dashboard-cookies.txt

Session Lifecycle#

• Access cookies are short-lived and refresh cookies are rotated by the dashboard auth flow.
• Do not script against browser-visible dashboard bearer tokens; dashboard login responses no longer expose them.

Public Endpoints#

The following Dashboard API endpoints do not require authentication:

All other Dashboard API endpoints require a valid dashboard session cookie.

Which Auth Method Should I Use?#

• Building an integration that emits deltas, queries balances, or checks proofs? Use API Key auth with the Balance API.
• Managing your account programmatically - creating keys, configuring webhooks, checking billing? Use browser session 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.