Authentication

All requests to the Pixee PIM API must be authenticated. The API supports two authentication methods: API keys (recommended for integrations) and JWT Bearer tokens (for user sessions / cookie-based browser clients).

API keys

API keys are long-lived credentials prefixed with pm_live_ (production) or pm_test_ (test). Create and manage them in your account settings or via the API key management endpoints.

Using an API key

Pass the key in the X-API-Key header on every request:

curl https://api.pixeepim.com/api/v1/products \
  -H "X-API-Key: pm_live_abc123..."

API key scopes

Each key is restricted to a set of scopes — 14 in total:

Creating an API key

1. Log in at pixeepim.com.
2. Navigate to Settings → API Keys.
3. Click Create API Key, enter a descriptive name and select the required scopes.
4. Copy the key immediately — it won't be shown again.

Programmatically: POST /api-keys (see API key management).

Rotating a key

curl -X POST https://api.pixeepim.com/api/v1/api-keys/{key_id}/rotate \
  -H "Authorization: Bearer {jwt_access_token}"

The old key value is invalidated immediately and a new one is returned.

JWT Bearer tokens

User sessions use short-lived JWT access tokens, valid for 15 minutes.

Login

Obtain a token via the login endpoint:

curl -X POST https://api.pixeepim.com/api/v1/auth/login/json \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "••••••••"}'

{
  "access_token": "eyJhbGc...",
  "token_type": "bearer"
}

Login (form-encoded)

An OAuth2 password-grant-compatible variant, for tooling that expects the standard form-encoded login (e.g. Swagger UI's "Authorize" button, some OAuth2 client libraries):

curl -X POST https://api.pixeepim.com/api/v1/auth/login \
  -d "username=you@example.com&password=••••••••"

Use the token in the Authorization header just like an API key:

curl https://api.pixeepim.com/api/v1/products \
  -H "Authorization: Bearer eyJhbGc..."

Refresh token

Refresh tokens are server-side, DB-backed, with rotation and reuse detection: every refresh issues a brand-new refresh token belonging to the same token family, and revokes the previous one. If a already-rotated (stale) refresh token is presented again, the entire family is revoked — a signal that the token was replayed or stolen.

The refresh token itself travels only in the refresh_token HttpOnly cookie set at login — it is never returned in a JSON body and never sent as a header.

curl -X POST https://api.pixeepim.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  --cookie "refresh_token={cookie_value}"

Logout

Revokes the current refresh token family and clears the session cookies.

curl -X POST https://api.pixeepim.com/api/v1/auth/logout \
  -H "Authorization: Bearer {access_token}" \
  --cookie "refresh_token={cookie_value}"

Get current user

Returns the authenticated user's profile — id, email, role, and tenant context.

curl https://api.pixeepim.com/api/v1/auth/me \
  -H "Authorization: Bearer {access_token}"

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "you@example.com",
  "role": "manager",
  "first_name": "Jane",
  "last_name": "Doe",
  "is_active": true
}

Register

Completes an account created through a subscription invite — it is not an open self-signup endpoint. You need the signed token sent by email when the subscription was created.

curl -X POST https://api.pixeepim.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "token": "eyJhbGc...",
    "email": "you@example.com",
    "password": "••••••••",
    "first_name": "Jane",
    "last_name": "Doe"
  }'

Password reset

Two-step flow: request a reset email, then verify the token with a new password.

Request a reset

curl -X POST https://api.pixeepim.com/api/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

Verify and set a new password

curl -X POST https://api.pixeepim.com/api/v1/auth/reset-password/verify \
  -H "Content-Type: application/json" \
  -d '{"token": "{reset_token}", "new_password": "••••••••"}'

Cookie clients and CSRF

Browser clients that rely on the refresh_token HttpOnly cookie are also protected by a CSRF double-submit check on mutating requests (POST/PUT/PATCH/DELETE). Fetch a token and echo it back on the X-CSRF-Token header:

Get a CSRF token

curl https://api.pixeepim.com/api/v1/auth/csrf-token \
  --cookie-jar cookies.txt

curl -X PATCH https://api.pixeepim.com/api/v1/products/{id} \
  -H "X-CSRF-Token: {csrf_token}" \
  -H "Content-Type: application/json" \
  --cookie cookies.txt \
  -d '{"name": "Updated name"}'

You can verify your session and CSRF setup with:

Test auth

curl https://api.pixeepim.com/api/v1/auth/test \
  -H "Authorization: Bearer {access_token}"

Account lockout

After too many failed login attempts, an account is temporarily locked (423 Locked). Admins can inspect and clear a lockout:

Get lockout status

curl https://api.pixeepim.com/api/v1/auth/lockout/status/you@example.com \
  -H "Authorization: Bearer {admin_access_token}"

Unlock an account

curl -X POST https://api.pixeepim.com/api/v1/auth/lockout/unlock/you@example.com \
  -H "Authorization: Bearer {admin_access_token}"

See Rate Limiting for the exact login attempt thresholds.

Multi-tenant context

If your account manages multiple tenants, scope a request to a specific tenant with the X-Tenant-ID header:

curl https://api.pixeepim.com/api/v1/products \
  -H "X-API-Key: {api_key}" \
  -H "X-Tenant-ID: {tenant_id}"

Without this header, the request operates on your default account context.

Error responses

See the Errors guide for the full error format.