Authentication

What you'll learn

• How JWT-based authentication works
• Which endpoints require tokens and which don't
• How to login, register, and refresh tokens
• How OAuth and SSO integrations work
• How Partner API key authentication works

Prerequisites

• A Store UUID
• Completed the Quick Start

Authentication Levels

The API has three authentication levels:

1. Tokenless (No Authentication Required)

Many storefront endpoints work without any authentication. These use the jwt_optional_authenticated pipeline — a JWT token is accepted but not required.

Tokenless endpoints include:

• GET /api/v1/store — Store details
• GET /api/v1/products — Product listing
• GET /api/v1/products/{id} — Product detail
• GET /api/v1/products/categories — Categories
• GET /api/v1/products/brands — Brands
• GET /api/v1/products/filters — Available filters
• GET /api/v1/products/types — Product types
• GET /api/v1/products/tags — Tags
• GET /api/v1/products/price-ranges — Price ranges
• GET /api/v1/store/deals/promotions — Deals
• POST /api/v1/auth/login — Login
• POST /api/v1/auth/register — Registration

This means your frontend can render the entire product catalog, search, and filtering experience without requiring user login.

2. JWT Authenticated

Endpoints that access or modify user-specific data require a valid JWT token in the Authorization header.

Authenticated endpoints include:

• Cart operations (POST /api/v5/carts, etc.)
• Order operations (POST /api/v4/orders, etc.)
• User profile (GET /api/v1/users/me, PUT /api/v1/users/me)
• Payment sources (GET /api/v1/store/payments/{service}/sources)
• Loyalty and rewards (GET /api/v3/users/me/loyalty)

3. Partner API Key

The Partner API uses API key authentication for store provisioning and configuration. This is not used by storefront frontends.

Login Flow

Step 1: Authenticate

curl -X POST https://ecom-api.staging.blaze.me/api/v1/auth/login \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -d '{
    "data": {
      "type": "users",
      "attributes": {
        "email": "john@example.com",
        "password": "securepassword123"
      }
    }
  }'

You can login with either email or phone_number (with country code):

{
  "data": {
    "type": "users",
    "attributes": {
      "phone_number": "+15551234567",
      "password": "securepassword123"
    }
  }
}

Step 2: Use the Token

The response includes a JWT token in data.attributes.token. Use it in all authenticated requests:

curl -X GET https://ecom-api.staging.blaze.me/api/v1/users/me \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

JavaScript Example

// Login
const loginResponse = await fetch(`${BASE_URL}/api/v1/auth/login`, {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    Accept: "application/vnd.api+json",
    "X-Store": STORE_UUID,
  },
  body: JSON.stringify({
    data: {
      type: "users",
      attributes: { email: "john@example.com", password: "securepassword123" },
    },
  }),
});

const { data } = await loginResponse.json();
const token = data.attributes.token;

// Use the token for authenticated requests
const meResponse = await fetch(`${BASE_URL}/api/v1/users/me`, {
  headers: {
    "Content-Type": "application/vnd.api+json",
    Accept: "application/vnd.api+json",
    "X-Store": STORE_UUID,
    Authorization: `Bearer ${token}`,
  },
});

Registration Flow

New user registration may require phone verification depending on store settings:

Simple Registration

curl -X POST https://ecom-api.staging.blaze.me/api/v1/auth/register \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -d '{
    "data": {
      "type": "users",
      "attributes": {
        "email": "jane@example.com",
        "phone_number": "+15559876543",
        "password": "securepassword123",
        "password_confirmation": "securepassword123",
        "first_name": "Jane",
        "last_name": "Doe",
        "date_of_birth": 694224000000
      }
    }
  }'

Phone Verification Flow

If the store requires phone verification:

1. POST /api/v1/auth/verification — Request verification code
2. POST /api/v1/auth/verification-check — Submit the code + complete registration

Password Recovery

# Request reset
POST /api/v1/auth/recover_password
{ "data": { "type": "users", "attributes": { "email": "john@example.com" } } }

# Reset with token (from email link)
POST /api/v1/auth/reset_password/{token}
{ "data": { "type": "users", "attributes": { "password": "newpassword123", "password_confirmation": "newpassword123" } } }

Logout

curl -X DELETE https://ecom-api.staging.blaze.me/api/v1/auth/logout \
  -H "Content-Type: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer YOUR_TOKEN"

OAuth / SSO

The API supports OAuth provider login for stores that have it configured.

Available providers: auth0, cognito, google, apple

• POST /api/v1/auth/{provider}/register — Register via OAuth provider
• POST /api/v1/auth/{provider}/verification-check — Complete OAuth verification
• POST /api/v1/auth/sso/keycloak — Keycloak SSO login
• GET /oauth/v1/authorize — OAuth2 authorization endpoint
• POST /oauth/v1/token — OAuth2 token endpoint

Error Handling

Common authentication errors: