Authentication

The Piriod API uses API tokens combined with a workspace header.

API tokens

Tokens are obtained from the Piriod dashboard (Settings → API tokens). Pass the token on every request:

Authorization: Token sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Do not include the token in client-side code. Treat it as a secret.

Each user has at most one active API token. Generating a new token from the dashboard invalidates the previous one.

Workspace header

Piriod is multi-workspace: a single user can belong to several accounts. Every request must declare which workspace it operates on:

x-simple-workspace: acc_01H8XYZ123ABC

Requests without this header (or with a workspace the user does not belong to) return 400 or 403.

Test mode

Set x-piriod-test-mode: true to operate against test data — separate from your production data. Resources created in test mode are returned only when this header is true.

x-piriod-test-mode: true

Publishable keys (payment links)

Hosted payment-link endpoints under /publishable/payment_links/... are designed to be called from the browser using the link’s publishable_key. These endpoints do not require Authorization: Token. They are read-only or limited to payment-intent operations.

Putting it all together

curl https://api.piriod.com/invoices/ \
  -H "Authorization: Token sk_live_xxxxx" \
  -H "x-simple-workspace: acc_01H8XYZ123ABC" \
  -H "x-piriod-test-mode: false"

Integration flows Error handling

Piriod API

Billing

Payments

Procurement

Collections

API tokens

Workspace header

Test mode

Publishable keys (payment links)

Putting it all together

​API tokens

​Workspace header

​Test mode

​Publishable keys (payment links)

​Putting it all together

API tokens

Workspace header

Test mode

Publishable keys (payment links)

Putting it all together