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',
})

curl --request POST \
  --url http://{defaultHost}/api/v3/store/auth/login \
  --header 'Content-Type: application/json' \
  --header 'x-spree-api-key: <api-key>' \
  --data '
{
  "email": "customer@example.com",
  "password": "password123",
  "provider": "email"
}
'

{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImYzYWIxNzRmLWNiYjAtNGZmMC1iNGE0LWYxZThmYWYyYzVkYyIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzgzNzg3OTM1fQ.mg0GrqIcwsYLMZSjcoaVb50Pfgk-ae02Y39jT1BszS4",
  "refresh_token": "AUSfX2Wau8EecQv92Yisj7B8",
  "user": {
    "id": "cus_UkLWZg9DAJ",
    "email": "test@example.com",
    "first_name": "Patsy",
    "last_name": "Stark",
    "phone": null,
    "accepts_email_marketing": false,
    "full_name": "Patsy Stark",
    "available_store_credit_total": "0",
    "display_available_store_credit_total": "$0.00",
    "addresses": [],
    "default_billing_address": null,
    "default_shipping_address": null
  }
}

{
  "error": {
    "code": "invalid_token",
    "message": "Valid API key required"
  }
}

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',
})

curl --request POST \
  --url http://{defaultHost}/api/v3/store/auth/login \
  --header 'Content-Type: application/json' \
  --header 'x-spree-api-key: <api-key>' \
  --data '
{
  "email": "customer@example.com",
  "password": "password123",
  "provider": "email"
}
'

{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImYzYWIxNzRmLWNiYjAtNGZmMC1iNGE0LWYxZThmYWYyYzVkYyIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzgzNzg3OTM1fQ.mg0GrqIcwsYLMZSjcoaVb50Pfgk-ae02Y39jT1BszS4",
  "refresh_token": "AUSfX2Wau8EecQv92Yisj7B8",
  "user": {
    "id": "cus_UkLWZg9DAJ",
    "email": "test@example.com",
    "first_name": "Patsy",
    "last_name": "Stark",
    "phone": null,
    "accepts_email_marketing": false,
    "full_name": "Patsy Stark",
    "available_store_credit_total": "0",
    "display_available_store_credit_total": "$0.00",
    "addresses": [],
    "default_billing_address": null,
    "default_shipping_address": null
  }
}

{
  "error": {
    "code": "invalid_token",
    "message": "Valid API key required"
  }
}