Docs/Authentication

Authentication

PausePoint uses API keys for all developer-authenticated endpoints.

API Key Format#

Live keys have the prefix pp_live_ followed by 48 hex characters; test keys use pp_test_:

text

pp_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6
pp_test_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6

Test keys run the full pause flow without sending real notifications or consuming your plan quota. Both keys are created automatically at registration.

The prefix is stored in plaintext (for display purposes). The full key is hashed with SHA-256 before storage. The plaintext key is only shown once — on registration or key rotation.

How to Authenticate#

Include the key in every request as a Bearer token:

text

Authorization: Bearer pp_live_your_key_here

Example:

bash

curl https://api.pausepoint.dev/v1/auth/me \
  -H "Authorization: Bearer pp_live_your_key_here"

Key Rotation#

Rotate your key with:

bash

curl -X POST https://api.pausepoint.dev/v1/auth/keys/rotate \
  -H "Authorization: Bearer pp_live_old_key"

This immediately invalidates the old key. Save the new key before dismissing the response.

Security Best Practices#

Store in environment variables, never in source code:

bash

# .env (add to .gitignore)
PAUSEPOINT_API_KEY=pp_live_your_key_here

# Python
import os
key = os.environ["PAUSEPOINT_API_KEY"]

# Node.js
const key = process.env.PAUSEPOINT_API_KEY;

Never commit API keys to version control. If you accidentally expose a key, rotate it immediately via POST /v1/auth/keys/rotate.

Unauthenticated Endpoints#

These endpoints do not require an API key:

POST /v1/auth/register — registration
POST /v1/auth/login — login
GET /v1/respond/{token} — response page data (protected by HMAC token instead)
POST /v1/respond/{token} — submit human response
POST /v1/billing/webhook — Paddle webhook (verified via Paddle-Signature header)
GET /health — health check