Authentication

The Spiffy API supports two authentication methods. Which one you use depends on the type of integration you're building.

	API Key	OAuth 2.0
For	Private integrations	Third-party integrations
Access scope	Your account only	Any merchant who authorizes your app
Setup	Copy key from dashboard	Register OAuth client on Developer Platform

API Key

API key authentication is the simplest way to access the Spiffy API. It's intended for private integrations — internal tools and scripts that connect to your own Spiffy account.

Your API key is available in your Spiffy dashboard under Settings → API.

Pass your API key as a Bearer token in the Authorization header on every request:

Authorization: Bearer YOUR_API_KEY

Security:

• Treat your API key like a password. Do not commit it to version control or expose it in client-side code.

• If a key is compromised, regenerate it immediately from Settings → API. The old key is invalidated instantly.

OAuth 2.0

OAuth 2.0 is required for third-party integrations — apps that connect to other merchants' Spiffy accounts on their behalf.

Step 1 — Redirect the merchant to authorize:

https://app.spiffy.co/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &response_type=code
  &scope=REQUESTED_SCOPES
  &state=RANDOM_STATE_VALUE

The state parameter should be a random, unguessable value to prevent CSRF attacks.

Step 2 — Exchange the authorization code for tokens:

POST https://api.spiffy.co/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&redirect_uri=YOUR_REDIRECT_URI

Response:

{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "bearer",
  "expires_in": 3600
}

Step 3 — Use the access token:

Authorization: Bearer ACCESS_TOKEN

Step 4 — Refresh when expired:

Access tokens expire after 1 hour. Refresh tokens are valid for 1 month and are single-use — each refresh issues a new pair.

POST https://api.spiffy.co/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

Available scopes: account, users, customers, checkouts, subscriptions, subscription_metered_billing, integrations, orders, payments, paymentplans, webhooks

Token security:

• Store tokens securely — treat them like passwords

• Never expose tokens in client-side code, URLs, or logs

• Merchants can revoke access at any time; handle 401 responses gracefully