API Keys - Stigg

API keys are used to authenticate requests to the Stigg API and SDKs. Each environment has its own isolated set of keys, managed under Integrations > API keys.

Scoped API keys are available on the Stigg Scale plan. All plans include the default Full access and Publishable keys.

Key types

Every environment is provisioned with two system-managed default keys. Users on the Scale plan can also create additional scoped keys.

Key type	Type	Prefix	Scopes	Created by
Full access key	Server (Secret)	`server-`	All current and future permissions	System, one per environment
Publishable key	Client (Publishable)	`client-`	Read-only (immutable)	System, one per environment
Scoped key	Server (Secret)	`server-`	User-defined, restricted	Users, unlimited per environment

Full access and scoped secret keys must never be exposed in client-side code, public repositories, or frontend bundles. Use environment variables to store them securely.

Full access key

The default server key has unrestricted access to the current environment and automatically inherits all future permissions as new capabilities are added to the platform. It is the only key allowed to have full access. Users cannot create additional full-access keys.

Full access means full access to the environment the key belongs to. It does not grant access to other environments or other accounts.

Publishable key

Designed for use in frontend and mobile SDKs. Its read-only scope is immutable. For additional protection against unauthorized data access, enable client-side security enforcement.

Scoped keys

User-created server keys with explicitly defined, restricted permissions. Scoped keys do not automatically inherit future platform capabilities. New resource types must be manually granted.

Principle of least privilege: Instead of sharing a single full-access key everywhere, create narrow scoped keys per service or environment. If a key is compromised, the blast radius is limited to only the permissions that key holds.

Finding your API keys

Log in to the Stigg app
Navigate to Integrations > API keys

Each key row shows its name, type, masked key value, status, and creation date. Use the Type filter (Default, Scoped) and Status filter (Active, Expires soon, Expired) to narrow the list.

Key statuses

Status	Description
Active	The key is valid and accepts all requests
Expiring soon	The key is being rotated and remains valid until its grace period ends
Expired	The key is invalid. All requests return `401 Unauthorized`

Using API keys

GraphQL API

Include your API key in the X-API-Key header with every request:

curl -X POST https://api.stigg.io/graphql \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"query": "{ customers { edges { node { customerId name } } } }"}'

REST API

Include your key in the X-API-KEY header with every request:

curl -X GET "https://api.stigg.io/api/v1/customers" \
  -H "X-API-KEY: your-server-api-key" \
  -H "Content-Type: application/json"

Backend SDKs

Use the full access key (or a scoped key with appropriate permissions) when initializing a backend SDK:

import Stigg from '@stigg/node-server-sdk';

const stigg = await Stigg.initialize({
  apiKey: process.env.STIGG_SERVER_API_KEY,
});

import stigg

client = stigg.Stigg(api_key=os.environ["STIGG_SERVER_API_KEY"])

import Stigg from '@stigg/rest-client';

const stigg = new Stigg({
  apiKey: process.env.STIGG_SERVER_API_KEY,
});

Frontend SDKs

Use the publishable key when initializing a frontend SDK:

import { StiggProvider } from '@stigg/react-sdk';

<StiggProvider apiKey="client-..." customerId="customer-123">
  {children}
</StiggProvider>

import { Stigg } from '@stigg/js-client-sdk';

const stigg = await Stigg.initialize({
  apiKey: 'client-...',
  customerId: 'customer-123',
});

Creating a scoped key

Navigate to Integrations > API keys
Click + Add scoped key
Enter a Name and optional Description
Configure the Scope for each resource (see Scope matrix below)
Click Create

Upon creation, the key secret is displayed. You can copy it immediately, or reveal it again later via the Show/Hide toggle in the key’s detail panel.

Scope matrix

When creating a scoped key, choose from the following supported permission presets:

Permission	Description
Full access	Complete read/write access to all resources in the environment
Read only	Read access across all resources, no write operations
Customers write	Create and manage customer data
Subscriptions write	Create and update subscriptions
Coupons write	Manage discount and coupon logic
API keys read and write	Manage API keys programmatically
Event Queue read	Obtain temporary SQS event queue credentials (read-only; write is not supported for this resource)

Selecting a write permission on a resource also grants read access for that resource.

Key details panel

Click any row (or select Key details from the context menu ⋮) to open the detail panel, which has three tabs:

Overview

Displays the key’s name (editable for scoped keys), description, type, masked key value with Show/Hide toggle, status, expiration (if rotating), creation date, and environment.

Scope

Shows the configured permissions. For scoped keys, permissions can be updated and saved here. Default keys and integration keys have read-only scopes that cannot be changed.

Activity

An audit log scoped to this specific key, showing only lifecycle events for the key itself:

Column	Description
Timestamp	When the event occurred
Event	Action taken on the key: Key created, Key rotated, Scope updated, Key revoked
Actor	The user or API key that triggered the event

This is different from Logs > Activity, where you can see all API activity across your environment and which key was used for each operation. For example, an entry there might read Create customer with the associated key shown as Full access key or the name of a specific scoped key.

Key rotation

Rotating a key generates a new secret while keeping the old secret valid for a configurable grace period, enabling zero-downtime rolling deployments. To rotate a key:

Open the context menu (⋮) next to the key, or open the key’s detail panel
Click Rotate key
Select when the old key should expire:
- Now (immediately invalidated)
- In 1 hour
- In 24 hours
- In 3 days
- In 7 days
Confirm the rotation

The old key transitions to Expiring soon status and stays valid until the grace period ends. Update your services to use the new key before then.

Extending the grace period

If you need more time, extend the grace period before it expires:

Open the context menu (⋮) next to the expiring key
Click Change grace period
Select a new expiration window

Revoking a key

Revocation immediately and permanently invalidates a key. Any requests using it will receive 401 Unauthorized.

Open the context menu (⋮) next to the key, or open the key’s detail panel
Click Revoke
Confirm

Revocation is immediate and cannot be undone. Ensure all services have switched to a different key before revoking.

Client-side security

The publishable key is visible in client-side code by design. To prevent unauthorized access to other customers’ data, Stigg supports an additional hardening layer: your backend generates a signed customer token (HMAC SHA256) that Stigg validates on every frontend request. Enable and configure client-side security from the Publishable key detail panel, under the Overview tab.

Hardening client-side access

Integration keys

When a third-party integration (such as Salesforce) is configured, Stigg automatically provisions a dedicated server key for it. Integration keys appear in the API keys table with Default type and have immutable scopes. They are removed when the integration is disconnected.

Access control

API key visibility is governed by role-based access control (RBAC):

Action	Owner	Member	Read-only
View key prefix	✅	✅	✅
Copy full key value	✅	❌	❌
Create / rotate / revoke	✅	❌	❌

Migration from legacy keys

Existing keys are automatically migrated when upgrading to the new API key management system:

Legacy key	Migrated to
Client API Token	Publishable key
Server API Token	Full access key

No action is required. Existing integrations continue to work without changes.

​Key types

​Full access key

​Publishable key

​Scoped keys

​Finding your API keys

​Key statuses

​Using API keys

​GraphQL API

​REST API

​Backend SDKs

​Frontend SDKs

​Creating a scoped key

​Scope matrix

​Key details panel

​Overview

​Scope

​Activity

​Key rotation

​Extending the grace period

​Revoking a key

​Client-side security

Hardening client-side access

​Integration keys

​Access control

​Migration from legacy keys

Key types

Full access key

Publishable key

Scoped keys

Finding your API keys

Key statuses

Using API keys

GraphQL API

REST API

Backend SDKs

Frontend SDKs

Creating a scoped key

Scope matrix

Key details panel

Overview

Scope

Activity

Key rotation

Extending the grace period

Revoking a key

Client-side security

Integration keys

Access control

Migration from legacy keys