API Keys

Programmatic access for integrations

Generate API keys for server-to-server authentication. Keys are SHA-256 hashed at rest and scoped with fine-grained permissions: read, update-data, delete-data, update-model, and delete-model.

Store securely

The raw key is returned only once at creation time. Store it in a secrets manager or environment variable. It cannot be retrieved again.

Minimum permissions

Grant only the permissions your integration needs. A sync integration may need read + update-data, not delete-model.

Rotate regularly

Deactivate old keys and generate new ones periodically. Use the deactivate endpoint before deleting to ensure a graceful transition.

Key format

Keys follow the format sigma_sk_live_abc123def456ghi789 and are sent via the X-Sigma-ApiKey header.

Permissions

Permission	Grants access to
`read`	Read all resources: records, schemas, catalogs, dimensions, option lists, workflows
`update-data`	Create and update records, variants, catalog assignments
`delete-data`	Delete records, variants, catalog assignments
`update-model`	Create and update schemas, attributes, dimensions, option lists, workflows, roles
`delete-model`	Delete schemas, attributes, dimensions, option lists, workflows, roles

Endpoints

Method	Endpoint	Description
GET	`/api-keys`	List all API keys (hashes hidden)
POST	`/api-keys`	Generate a new API key
POST	`/api-keys/:id/deactivate`	Deactivate an API key
DELETE	`/api-keys/:id`	Delete an API key

List all API keys

Returns all API keys for the current tenant. The key hash is never included in list responses for security.

curl https://api.sigma-pim.com/api/v1/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

// Response
[
  {
    "id": "apikey-sync-prod",
    "name": "Shopify Sync - Production",
    "permissions": ["read", "update-data"],
    "active": true,
    "createdAt": "2026-02-15T09:00:00.000Z",
    "lastUsedAt": "2026-03-08T10:00:12.450Z"
  },
  {
    "id": "apikey-export-staging",
    "name": "Export Service - Staging",
    "permissions": ["read"],
    "active": true,
    "createdAt": "2026-03-01T14:30:00.000Z",
    "lastUsedAt": "2026-03-07T16:45:00.000Z"
  }
]

Generate new API key

Generate a new API key with the specified name and permissions. The raw key is returned only in this response — store it immediately. The key is SHA-256 hashed before storage.

Request body

Field	Type	Description
`name`	string	Human-readable name for the key
`permissions`	string[]	Array of: `read`, `update-data`, `delete-data`, `update-model`, `delete-model`

curl -X POST https://api.sigma-pim.com/api/v1/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Shopify Sync - Production",
    "permissions": ["read", "update-data"]
  }'

// Response — raw key shown ONLY ONCE
{
  "id": "apikey-sync-prod",
  "name": "Shopify Sync - Production",
  "rawKey": "sigma_sk_live_abc123def456ghi789jkl012mno345pqr678",
  "permissions": ["read", "update-data"],
  "createdAt": "2026-03-08T12:00:00.000Z"
}

Important: save the raw key now

The rawKey field is only returned in the create response. After this, only the SHA-256 hash is stored. If you lose the key, you must generate a new one.

Using an API key

Send the raw key in the X-Sigma-ApiKey header with every request.

curl https://api.sigma-pim.com/api/v1/records \
  -H "X-Sigma-ApiKey: sigma_sk_live_abc123def456ghi789jkl012mno345pqr678"

Deactivate API key

Deactivate an API key without deleting it. Deactivated keys are rejected on all endpoints. This allows a graceful key rotation: create new key, update integrations, deactivate old key, then delete.

curl -X POST https://api.sigma-pim.com/api/v1/api-keys/apikey-sync-prod/deactivate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

// Response
{
  "id": "apikey-sync-prod",
  "name": "Shopify Sync - Production",
  "permissions": ["read", "update-data"],
  "active": false,
  "createdAt": "2026-02-15T09:00:00.000Z",
  "deactivatedAt": "2026-03-08T12:30:00.000Z"
}

Delete API key

Permanently delete an API key. This action is irreversible. It is recommended to deactivate first to ensure no active integrations are using the key.

curl -X DELETE https://api.sigma-pim.com/api/v1/api-keys/apikey-sync-prod \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

// Response
{
  "deleted": true
}

Previous Sync Next Webhooks