Authentication

Secure your API calls

Sigma PIM supports two authentication methods: JWT tokens for interactive user sessions and API keys for server-to-server integration. All authenticated endpoints require one of these methods.

JWT Tokens

For user sessions. Authenticate with email and password, receive a token with 24-hour expiry. Pass via Authorization: Bearer {token} header.

API Keys

For server-to-server integrations. Generate a key from the API, then pass it via the X-Sigma-ApiKey header on every request.

JWT Authentication Flow

POST your email and password to /api/v1/auth/login. You receive a signed JWT token and user details.

Use the token

Include the token in the Authorization header of every subsequent request as a Bearer token.

Refresh before expiry

Tokens expire after 24 hours. Call /api/v1/auth/refresh with the current token to get a new one without re-authenticating.

The JWT payload contains three claims: userId, workspaceId, and roleId. These determine identity, tenant isolation, and permission level for every request.

API Key Authentication

API keys are ideal for automated integrations, CI/CD pipelines, and server-to-server communication. They don't expire on their own but can be deactivated at any time.

# Pass the API key in the X-Sigma-ApiKey header
curl https://api.sigma-pim.com/api/v1/records \
  -H "X-Sigma-ApiKey: sigma_sk_live_abc123def456ghi789"

API keys grant admin-level access to the associated workspace. Treat them like passwords — never expose them in client-side code or commit them to version control.

Generate and manage API keys via the /api-keys endpoints. The key format is: sigma_sk_live_<random>

Token Format

JWT tokens are signed with HS256 and contain the following claims:

Claim	Type	Description
`userId`	string	The authenticated user's unique identifier
`workspaceId`	string	The tenant workspace this token is scoped to
`roleId`	string	The user's role, used for permission resolution
`iat`	number	Issued-at timestamp (Unix epoch seconds)
`exp`	number	Expiration timestamp — 24 hours after issuance

Endpoints

GET /api/v1/auth/quick-logins

Returns all registered tenants with their quick-login users. No authentication required. Useful for building login screens that let users pick a tenant and user without typing credentials.

This endpoint requires no authentication. It is designed for development and demo environments where quick login selection is needed.

Parameters

None — this endpoint takes no parameters.

curl

curl https://api.sigma-pim.com/api/v1/auth/quick-logins

JavaScript

// Fetch available tenants and users
const res = await fetch("https://api.sigma-pim.com/api/v1/auth/quick-logins");
const data = await res.json();
console.log(data.tenants);

Response 200 OK

// Response
{
  "tenants": [
    {
      "workspaceId": "ws-fashion-brand",
      "workspaceName": "Fashion Brand",
      "users": [
        {
          "name": "Admin User",
          "email": "admin@sigma.io",
          "password": "admin",
          "roleName": "Admin"
        },
        {
          "name": "Editor",
          "email": "editor@sigma.io",
          "password": "editor",
          "roleName": "Editor"
        }
      ]
    }
  ]
}

POST /api/v1/auth/login

Authenticate with email and password. Returns a signed JWT token (valid for 24 hours) and user details. If multiple tenants exist, the system searches all of them unless you specify a workspaceId.

Request Body

Field	Type	Description
email required	string	The user's email address
password required	string	The user's password
workspaceId optional	string	Target a specific tenant workspace. If omitted, all tenants are searched.

curl

curl -X POST https://api.sigma-pim.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@sigma.io",
    "password": "admin",
    "workspaceId": "ws-fashion-brand"
  }'

JavaScript

const res = await fetch("https://api.sigma-pim.com/api/v1/auth/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "admin@sigma.io",
    password: "admin"
  })
});

const { token, user } = await res.json();

// Use the token in subsequent requests
const schemas = await fetch("https://api.sigma-pim.com/api/v1/schemas", {
  headers: { "Authorization": `Bearer ${token}` }
});

Response 200 OK

// Response
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJ1c2VyLWFkbWluIiwid29ya3NwYWNlSWQiOiJ3cy1mYXNoaW9uLWJyYW5kIiwicm9sZUlkIjoicm9sZS1hZG1pbiJ9...",
  "user": {
    "id": "user-admin",
    "email": "admin@sigma.io",
    "name": "Admin User",
    "roleId": "role-admin",
    "workspaceId": "ws-fashion-brand"
  }
}

Error Responses

Status	Error Code	Description
`400`	`VALIDATION_ERROR`	Email and password are required
`401`	`UNAUTHORIZED`	Invalid email or password

// 401 Unauthorized
{
  "error": "UNAUTHORIZED",
  "message": "Invalid email or password"
}

POST /api/v1/auth/refresh

Refresh an existing JWT token before it expires. The old token is validated and a new token is issued with a fresh 24-hour expiry. The workspace must still exist in the tenant registry.

Request Body

Field	Type	Description
token required	string	The current JWT token to refresh

curl

curl -X POST https://api.sigma-pim.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "token": "eyJhbGciOiJIUzI1NiIs..."
  }'

JavaScript

const res = await fetch("https://api.sigma-pim.com/api/v1/auth/refresh", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    token: currentToken
  })
});

const { token: newToken } = await res.json();
// Replace the old token with the new one

Response 200 OK

// Response
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJ1c2VyLWFkbWluIiwid29ya3NwYWNlSWQiOiJ3cy1mYXNoaW9uLWJyYW5kIiwicm9sZUlkIjoicm9sZS1hZG1pbiJ9..."
}

Error Responses

Status	Error Code	Description
`400`	`VALIDATION_ERROR`	Token is required in the request body
`401`	`UNAUTHORIZED`	Invalid or expired token

// 401 Unauthorized
{
  "error": "UNAUTHORIZED",
  "message": "Invalid or expired token"
}

Endpoint Summary

Method	Endpoint	Auth	Description
GET	`/api/v1/auth/quick-logins`	None	List all tenants with quick-login users
POST	`/api/v1/auth/login`	None	Authenticate and receive a JWT token
POST	`/api/v1/auth/refresh`	None	Refresh an existing JWT token

Previous Getting Started Next Schemas & Attributes