> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stigg.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Keys

> Manage and authenticate with Stigg API keys

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**.

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

## 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 |

<Warning>
  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.
</Warning>

### 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.

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

### 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](#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.

<Note>
  **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.
</Note>

## Finding your API keys

1. Log in to the [Stigg app](https://app.stigg.io)
2. 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:

```bash theme={null}
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:

```bash theme={null}
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:

<CodeGroup>
  ```typescript Node.js theme={null}
  import Stigg from '@stigg/node-server-sdk';

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

  ```python Python theme={null}
  import stigg

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

  ```typescript REST SDK theme={null}
  import Stigg from '@stigg/rest-client';

  const stigg = new Stigg({
    apiKey: process.env.STIGG_SERVER_API_KEY,
  });
  ```
</CodeGroup>

### Frontend SDKs

Use the **publishable key** when initializing a frontend SDK:

<CodeGroup>
  ```typescript React theme={null}
  import { StiggProvider } from '@stigg/react-sdk';

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

  ```typescript JavaScript theme={null}
  import { Stigg } from '@stigg/js-client-sdk';

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

## Creating a scoped key

1. Navigate to **Integrations > API keys**
2. Click **+ Add scoped key**
3. Enter a **Name** and optional **Description**
4. Configure the **Scope** for each resource (see [Scope matrix](#scope-matrix) below)
5. 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:**

1. Open the context menu (⋮) next to the key, or open the key's detail panel
2. Click **Rotate key**
3. Select when the old key should expire:
   * **Now** (immediately invalidated)
   * **In 1 hour**
   * **In 24 hours**
   * **In 3 days**
   * **In 7 days**
4. 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:

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

## Revoking a key

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

1. Open the context menu (⋮) next to the key, or open the key's detail panel
2. Click **Revoke**
3. Confirm

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

## 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.

<Card title="Hardening client-side access" icon="shield-check" href="/api-and-sdks/integration/frontend/hardening-client-side-access" horizontal />

## 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)](/documentation/managing-your-account/access-management/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.