> For the complete documentation index, see [llms.txt](https://developers.spiffy.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.spiffy.co/api/getting-started/authentication.md).

# 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**        | Create a key in the 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.

Create and manage keys in your Spiffy dashboard under **Settings → API**. An account can hold multiple named keys — for example, one per integration — so you can tell at a glance what each key is used for and revoke one without affecting the others.

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

```
Authorization: Bearer YOUR_API_KEY
```

**Security:**

* Treat every key like a password. Do not commit it to version control or expose it in client-side code.
* To rotate a key without downtime, create a new key, cut your integration over to it, then delete the old key.
* If a key is compromised, regenerate it from Settings → API. That invalidates only that key's old secret immediately and issues a new one in its place — other keys on the account are unaffected.

#### 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:

```json
{
  "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
