Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
---
title: "Admin SDK authentication with API keys and JWT cookies"
sidebarTitle: "Authentication"
description: "Authenticate @spree/admin-sdk with a secret API key for server-to-server, scope-based access or JWT cookie auth for role-based browser admin apps."
---
The Admin API supports two authentication methods. Both reach the same endpoints — they differ in **where the credential lives** and **how authorization is decided**:
| | Secret API key | JWT + cookie |
|---|---|---|
| **For** | Backend integrations, automations, cron jobs | Browser-based admin apps where a human signs in |
| **Credential** | `sk_…` key, created in the admin | Short-lived access token + httpOnly refresh cookie |
| **Authorization** | [Scopes](/api-reference/admin-api/authentication) attached to the key (`read_products`, `write_orders`, …) | The admin user's roles and permissions |
| **Where it runs** | Server-side only — never in a browser | Browser (the refresh token never touches your JS) |
## Secret API key (server-to-server)
Create a secret key in the admin under **Settings → API Keys**, grant it the scopes your integration needs, and pass it to the client:
```typescript
import { createAdminClient } from '@spree/admin-sdk'
const client = createAdminClient({
baseUrl: 'https://your-store.com',
secretKey: process.env.SPREE_SECRET_KEY, // sk_xxx
})
```
Each key carries the list of scopes granted at creation time. A request to an endpoint the key isn't scoped for fails with `code: 'access_denied'` — the error's `details.required_scope` names the missing scope (see [Querying & Errors](/developer/sdk/admin/querying-and-errors#scope-errors)).
<Warning>
Secret keys grant back-office access to your store. Never embed them in client-side code, mobile apps, or public repositories — keep them in server-side environment variables or a secrets manager.
</Warning>
## JWT + cookie authentication (browser apps)
For browser-based admin tooling, authenticate as an admin user. The flow is designed so that **no long-lived credential is ever exposed to JavaScript**:
- `auth.login()` returns `{ token, user }` — a short-lived access token you hold in memory.
- The **refresh token never appears in JSON.** The server sets it as an `HttpOnly` cookie scoped to `/api/v3/admin/auth`, and the SDK sends requests with `credentials: 'include'` by default, so the cookie flows automatically.
- `auth.refresh()` takes **no arguments** — it's driven entirely by the cookie, and rotates it on every call.
- `auth.logout()` revokes the refresh token server-side and clears the cookie.
```typescript
import { createAdminClient } from '@spree/admin-sdk'
// A cookie-auth app can start with no credentials at all
const client = createAdminClient({ baseUrl: 'https://your-store.com' })
// Sign in — the refresh token lands in the httpOnly cookie
const { token, user } = await client.auth.login({
email: '[email protected]',
password: 'password123',
})
client.setToken(token)
// Auto-recover from expired access tokens
client.onUnauthorized(async () => {
const { token: fresh } = await client.auth.refresh()
client.setToken(fresh)
return true // retry the failed request
})
// Sign out — revokes the refresh token server-side
await client.auth.logout()
```
### Bootstrapping a returning session
Because the refresh cookie outlives the in-memory access token, a returning user can be signed back in without re-entering credentials — call `refresh()` on app load and treat failure as "not signed in":
```typescript
try {
const { token } = await client.auth.refresh()
client.setToken(token)
} catch {
// No valid session — show the login form
}
```
### Identity providers
`auth.login()` also accepts third-party identity-provider payloads when the server has a [matching strategy registered](/developer/how-to/custom-api-authentication):
```typescript
const { token } = await client.auth.login({ provider: 'auth0', token: idpJwt })
```
### Current user and permissions
After signing in, `client.me.get()` returns the admin user's profile together with their serialized permissions — use it to drive what your UI shows:
```typescript
const { user, permissions } = await client.me.get()
```
## Staff invitations
The `auth` resource also exposes the unauthenticated invitation-acceptance flow used when onboarding new staff: `auth.lookupInvitation(id, token)` returns the safe-to-render invitation context (store, role, inviter), and `auth.acceptInvitation(id, token, params)` accepts it — issuing a JWT and refresh cookie identical to `login`. Sending invitations is an authenticated operation on [`client.invitations`](/developer/sdk/admin/resources).
## Custom fetch
Pass a custom `fetch` implementation when you need request interception, proxying, or a non-standard runtime:
```typescript
const client = createAdminClient({
baseUrl: 'https://your-store.com',
secretKey: process.env.SPREE_SECRET_KEY,
fetch: customFetchImplementation,
})
```