Login

Authenticates a customer and returns a JWT access token + refresh token.

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 (Auth0, Okta, Firebase, a custom JWT issuer, SAML, etc.), send { "provider": "<your_key>", ... } with the fields that provider requires. The endpoint returns the same JWT + refresh token regardless of which provider authenticated the request. See Custom API Authentication for the list of configured providers and their required fields.

POST

api

store

auth

Spree SDK

import { createClient } from '@spree/sdk'

const client = createClient({
  baseUrl: 'https://your-store.com',
  publishableKey: '<api-key>',
})

const auth = await client.auth.login({
  email: 'customer@example.com',
  password: 'password123',
})

{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjE2Yjg1MmI5LTVkZDgtNDIzYi1hNTExLWMxYTRmYzlhNmJhMCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzgxNjA5MjIxfQ.-qVED6Xae0WMi4kkOjfdsaMfBqcaW6p6-0KSITucdzw",
  "refresh_token": "c5T1u7sT7BUgTTN4LqyL1jFy",
  "user": {
    "id": "cus_UkLWZg9DAJ",
    "email": "test@example.com",
    "first_name": "Eun",
    "last_name": "Franecki",
    "phone": null,
    "accepts_email_marketing": false,
    "full_name": "Eun Franecki",
    "available_store_credit_total": "0",
    "display_available_store_credit_total": "$0.00",
    "addresses": [],
    "default_billing_address": null,
    "default_shipping_address": null
  }
}

Authorizations

x-spree-api-key

string

header

required

Publishable API key for store 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:

"customer@example.com"

password

string

required

Example:

"password123"

provider

enum<string>

default:email

Available options:

email

Response

token

string

required

JWT access token

refresh_token

string

required

Refresh token for obtaining new access tokens

user

object

required

Show child attributes

Migrating from Storefront API v2

Refresh token

⌘I

Spree SDK

import { createClient } from '@spree/sdk'

const client = createClient({
  baseUrl: 'https://your-store.com',
  publishableKey: '<api-key>',
})

const auth = await client.auth.login({
  email: 'customer@example.com',
  password: 'password123',
})

{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjE2Yjg1MmI5LTVkZDgtNDIzYi1hNTExLWMxYTRmYzlhNmJhMCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzgxNjA5MjIxfQ.-qVED6Xae0WMi4kkOjfdsaMfBqcaW6p6-0KSITucdzw",
  "refresh_token": "c5T1u7sT7BUgTTN4LqyL1jFy",
  "user": {
    "id": "cus_UkLWZg9DAJ",
    "email": "test@example.com",
    "first_name": "Eun",
    "last_name": "Franecki",
    "phone": null,
    "accepts_email_marketing": false,
    "full_name": "Eun Franecki",
    "available_store_credit_total": "0",
    "display_available_store_credit_total": "$0.00",
    "addresses": [],
    "default_billing_address": null,
    "default_shipping_address": null
  }
}