Login

Authenticates an admin user and returns a short-lived JWT access token. The rotatable refresh token is set in an HttpOnly cookie — it is not included in the response body.

The provider field selects the authentication method. When omitted it defaults to email, the built-in email/password login.

To authenticate against a third-party identity provider (Okta, Azure AD, Google Workspace SSO, a custom JWT issuer, SAML, etc.), send { "provider": "<your_key>", ... } with the fields that provider requires. The endpoint returns the same JWT regardless of which provider authenticated the request. See Custom API Authentication for the list of configured providers and their required fields.

POST

api

admin

auth

Spree Admin SDK

import { createAdminClient } from '@spree/admin-sdk'

const client = createAdminClient({
  baseUrl: 'https://your-store.com',
  secretKey: 'sk_xxx',
})

// The refresh token is set as an HttpOnly cookie; only `token` and `user` come back in the body.
const auth = await client.auth.login({
  email: 'admin@example.com',
  password: 'password123',
})

spree api post /auth/login -d '{"email":"admin@example.com","password":"password123"}'

{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImU3YjgzNTVhLTExYWUtNGNmYy1iNzYyLTM4NGQ5OGY1ZGQwZCIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg1MTgyNzA1fQ.i0SlPXHKVN5YG7XjmSIknXGFOaKgeBwHiNkyQzHEqzw",
  "user": {
    "id": "admin_UkLWZg9DAJ",
    "email": "admin@example.com",
    "first_name": "Tien",
    "last_name": "Medhurst",
    "full_name": "Tien Medhurst",
    "selected_locale": null,
    "created_at": "2026-07-27T20:00:04.732Z",
    "updated_at": "2026-07-27T20:00:04.732Z",
    "avatar_url": null,
    "roles": [
      {
        "id": "role_UkLWZg9DAJ",
        "name": "admin"
      }
    ],
    "stores": [
      {
        "id": "store_UkLWZg9DAJ",
        "name": "Spree Test Store",
        "code": "spree_1"
      }
    ]
  }
}

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid email or password"
  }
}

Authorizations

x-spree-api-key

string

header

required

Secret API key for admin access

Headers

x-spree-api-key

string

required

Body

application/json

EmailPasswordLogin
ProviderLogin

Built-in email/password authentication (default when provider is omitted).

string<email>

required

Example:

"admin@example.com"

password

string

required

Example:

"password123"

provider

enum<string>

default:email

Available options:

email

Response

token

string

required

JWT access token

user

object

required

Show child attributes

Admin API endpoint index

Refresh token

⌘I

Spree Admin SDK

import { createAdminClient } from '@spree/admin-sdk'

const client = createAdminClient({
  baseUrl: 'https://your-store.com',
  secretKey: 'sk_xxx',
})

// The refresh token is set as an HttpOnly cookie; only `token` and `user` come back in the body.
const auth = await client.auth.login({
  email: 'admin@example.com',
  password: 'password123',
})

spree api post /auth/login -d '{"email":"admin@example.com","password":"password123"}'

{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImU3YjgzNTVhLTExYWUtNGNmYy1iNzYyLTM4NGQ5OGY1ZGQwZCIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg1MTgyNzA1fQ.i0SlPXHKVN5YG7XjmSIknXGFOaKgeBwHiNkyQzHEqzw",
  "user": {
    "id": "admin_UkLWZg9DAJ",
    "email": "admin@example.com",
    "first_name": "Tien",
    "last_name": "Medhurst",
    "full_name": "Tien Medhurst",
    "selected_locale": null,
    "created_at": "2026-07-27T20:00:04.732Z",
    "updated_at": "2026-07-27T20:00:04.732Z",
    "avatar_url": null,
    "roles": [
      {
        "id": "role_UkLWZg9DAJ",
        "name": "admin"
      }
    ],
    "stores": [
      {
        "id": "store_UkLWZg9DAJ",
        "name": "Spree Test Store",
        "code": "spree_1"
      }
    ]
  }
}

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid email or password"
  }
}

API basics

Endpoints

Login

Authorizations

Headers

Body

Response