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

# Publishable Keys & Secrets

> Generate and manage the publishable key and signing secrets your apps use to authenticate with Statisfy's SDK and APIs.

Publishable keys and secrets let your own applications authenticate with Statisfy — for example, to embed a Statisfy digital worker in your product or to call Statisfy's data APIs. They come in a pair, following the same convention as Stripe and other platforms:

* A **publishable key** (`pk_live_…`) — a public identifier for your workspace. It is safe to ship in client-side code. There is one publishable key per workspace.
* A **secret** — a private signing/authentication credential, paired with the publishable key. Secrets are stored in Google Secret Manager and are never stored in plain text by Statisfy.

<Note>
  Managing these keys requires access to the **API keys** area of your workspace. If you don't see it, ask your Statisfy administrator.
</Note>

## Accessing your keys

Open the **API keys** section of your workspace. You'll see your publishable key, the controls to generate and rotate secrets, and a way to view an existing secret at any time.

## Secret types

A workspace can hold one secret per type. Choose the type that matches how your app authenticates:

| Type    | Use it for                                                                                                                                                         |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **JWT** | The digital-worker SDK and hosted customer portal. Your backend mints a short-lived JSON Web Token (JWT) signed with this secret; Statisfy verifies the signature. |
| **API** | Direct, server-to-server calls to Statisfy's data APIs, where your app presents the secret as an API key on each request.                                          |

<Tip>
  JWT secrets are the right choice for embedding a digital worker in your product. API secrets are for backend integrations that read or write Statisfy data programmatically.
</Tip>

## Generating a secret

<Steps>
  <Step title="Pick a secret type">
    Select **JWT** or **API** in the API keys panel.
  </Step>

  <Step title="Generate">
    Click **Generate**. The first time you generate any secret, Statisfy also creates your workspace's publishable key automatically.
  </Step>

  <Step title="Copy the values">
    Your publishable key and the new secret are shown. Copy the secret and store it somewhere safe (a secrets manager, environment variables, etc.).
  </Step>
</Steps>

A workspace holds **one secret per type**. If a secret of the selected type already exists, generating again is blocked — [rotate](#rotating-a-secret) it instead to get a fresh value.

## Viewing a secret

You can view an existing secret at any time. In the API keys panel, choose the secret type and select **View secret** — Statisfy reads the current value securely from Google Secret Manager and displays it so you can copy it again.

<Note>
  Viewing a secret does not change it. Existing integrations keep working.
</Note>

## Rotating a secret

Rotating replaces a secret with a brand-new value.

<Steps>
  <Step title="Choose the type and rotate">
    Select the secret type and click **Rotate**, then confirm.
  </Step>

  <Step title="Update your apps">
    Copy the new secret and update every app or backend that uses it.
  </Step>
</Steps>

<Warning>
  Rotation is a **hard cutover**. The old secret stops working immediately, so anything still using it — JWTs signed with the old secret, or API calls presenting it — will start failing until you update them. Plan rotations for a maintenance window, or update your apps right away.
</Warning>

Rotate a secret whenever you suspect it has been exposed (committed to source control, shared in a ticket, logged, etc.).

## About the publishable key

* It is **public** — safe to include in front-end code and client apps.
* There is **one per workspace**, created automatically the first time you generate a secret.
* It currently **cannot be revoked or disabled** from this screen. If you need to invalidate access, rotate the relevant secret instead — that immediately breaks anything signed with or presenting the old secret.

## Using your keys

### JWT (digital-worker SDK)

Your backend mints a short-lived JWT, signs it with your **JWT secret** using **HS256**, and your app sends it alongside the publishable key on each request:

```http theme={null}
X-Statisfy-Publishable-Key: pk_live_xxxxxxxxxxxxxxxx
Authorization: Bearer <your-signed-jwt>
```

The token should include standard claims (`iat`, `exp`) plus the end user's `email`, which Statisfy uses to resolve who is making the request. Because the JWT is short-lived and minted by your backend, the long-lived secret never leaves your server.

<Warning>
  Sign JWTs **on your backend only**. Never ship the JWT secret to a browser or mobile client — only the publishable key is safe to expose client-side.
</Warning>

### API (data APIs)

For server-to-server integrations, your backend presents the **API secret** as the credential on each call to Statisfy's data APIs, together with your publishable key. Keep the API secret on your server and never expose it in client-side code.

## Security

* Secrets are stored in **Google Secret Manager**, never as plain text in Statisfy's database.
* Each workspace's keys are **isolated** — there is no cross-workspace access.
* The publishable key is public; **the secret is sensitive** — treat it like a password.
* Rotate a secret immediately if you believe it has leaked.

## Frequently asked questions

<Accordion title="What's the difference between the publishable key and the secret?">
  The publishable key identifies your workspace and is safe to expose publicly. The secret is private and is used to sign JWTs or authenticate API calls. They are always used together.
</Accordion>

<Accordion title="I lost my secret. Can I get it back?">
  Yes — use **View secret** to display the current value again. If you'd rather replace it entirely, **Rotate** generates a new one (which invalidates the old value).
</Accordion>

<Accordion title="Can I have separate JWT and API secrets at the same time?">
  Yes. A workspace can hold one secret of each type — one JWT and one API — and you generate, view, and rotate each independently.
</Accordion>

<Accordion title="What happens to existing integrations when I rotate?">
  They break until updated. Rotation is an immediate cutover: the old secret stops working the moment the new one is created, so update every app that uses it as part of the rotation.
</Accordion>