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

# API Keys and Secrets

> Learn the different authentication methods available in SuprSend and how to securely integrate them into your application.

SuprSend supports **three authentication methods**:

* **Workspace Key & Secret** → Used to authenticate requests from **Backend SDKs**.
* **API Keys** → Used to authenticate **REST APIs** as `Bearer <API_KEY>`.
* **Public Key & Signing Key** → Used to authenticate **Client SDKs** (with enhanced security options).

<Note>All keys and secrets are unique per workspace. This is done to keep your testing and production workspace separate and safeguards against accidentally sending wrong notification to your production users during testing.</Note>

***

## 1. Authenticating Backend SDKs

Backend SDKs are authenticated using a **Workspace Key** and **Workspace Secret**. To find these credentials:

1. Go to **SuprSend Dashboard → Developers → API Keys**.
2. The Workspace Key and Secret for the selected workspace are shown at the top.

Save this as environment variable in your backend SDK configuration for safekeeping.

***

## 2. Authenticating REST API Requests

REST API requests are authenticated using **API Keys**. Pass the API Key in the `Authorization` header with `Bearer` scheme:

```http theme={"system"}
Authorization: Bearer <API_KEY>
Content-Type: application/json
```

To find these credentials:

1. Navigate to **Dashboard → Developers → API Keys**.
2. Click **Generate API Key**.
3. Provide a name and select **Create and Save**.
4. Copy the API Key and store it securely — it will be shown **only once** at generation.

<Warning> API Keys are confidential and are shown only once at generation. We recommend keeping them in your environment variables or secure vault to avoid accidental exposure.  </Warning>

## 3. Authenticating Client-side SDKs

Client SDKs (Web/Mobile) use Public Keys for authentication.
You can manage these in Dashboard → Developers → API Keys → Public Keys.

<Frame>
  <img src="https://mintcdn.com/suprsend/jhGzZpggWCp1KSgu/images/docs/d44c8b5993f4dace694f63d10493f76c81814c25a23ddf5642d26e6d2253460a-Screenshot_2024-09-08_at_9.26.14_PM.png?fit=max&auto=format&n=jhGzZpggWCp1KSgu&q=85&s=34835992d4ccc351e013666e4de120d7" width="2856" height="556" data-path="images/docs/d44c8b5993f4dace694f63d10493f76c81814c25a23ddf5642d26e6d2253460a-Screenshot_2024-09-08_at_9.26.14_PM.png" />
</Frame>

Generate new keys or rotate/delete existing ones.

For Production workspaces, Public Keys alone are insecure. Enable Enhanced Security Mode, which requires a Signed User Token (JWT) from your backend.

<Check> 📘 Some legacy mobile SDKs may still use Workspace Key/Secret. These are being phased out. </Check>

### Enhanced Security Mode with signed User Token

When enhanced security mode is on, user level authentication is performed for all requests. This is recommended for Production workspaces. All requests will be rejected by SuprSend if enhanced security mode is on and signed user token is not provided. This signed user token should be generated by your backend application and should be passed to your client.

<Steps>
  <Step title="Generate Signing Key">
    You can generate Signing key from SuprSend Dashboard (below Public Keys section in API Keys page).

    <Frame>
      <img src="https://mintcdn.com/suprsend/y77gmHjmaTSnbCzd/images/docs/ba1ee6d00d68bd97058f828c95bea3984e780e439ea47c8460d9c38a65bb13cb-Screenshot_2024-09-08_at_9.57.56_PM.png?fit=max&auto=format&n=y77gmHjmaTSnbCzd&q=85&s=36da7b5a4a9b2e7e48cb683ee09a34c8" width="3018" height="1380" data-path="images/docs/ba1ee6d00d68bd97058f828c95bea3984e780e439ea47c8460d9c38a65bb13cb-Screenshot_2024-09-08_at_9.57.56_PM.png" />
    </Frame>

    Once signing key is generated it won't be shown again, so copy and store it securely. It contains 2 formats:

    * **Base64 format:** This is single line text, suitable for storing as an environment variable.
    * **PEM format:** This is multiline text format string.

    You can use any of the above format. This key will be used as secret to generate JWT token as shown in below step.
  </Step>

  <Step title="Creating Signed User JWT Token">
    This should be created on your backend application only. You will need to sign the JWT token with the signing key from above step and expose this JWT token to your Frontend application.

    * **JWT Algorithm:**ES256

    * **JWT Secret:**Signing key in PEM format generated in step1. If you are using Base64 format, it should be converted in to PEM format.

    * **JWT Payload:**

    <CodeGroup>
      ```json Payload theme={"system"}
      {
        "entity_type": 'subscriber', // hardcode this value to subscriber
        "entity_id": your_distinct_id, // replace this with your actual distinct id
        "exp": 1725814228, // token expiry timestamp in seconds
        "iat": 1725814228 // token issued timestamp in seconds.
        "scope": { "tenant_id": "string" }
      }
      ```
    </CodeGroup>

    <Note>
      SuprSend requests will be scoped to tenant. If tenant passed by you in SDK doesn't match with the JWT payload scope `tenant_id` then requests will throw `403` error.

      If `tenant_id` is not passed, it is assumed to be `default` tenant.

      Currently only Inbox requests supports scope, later on we will extend it to preferences and other requests.
    </Note>

    Create JWT token using above information:

    <CodeGroup>
      ```javascript Node theme={"system"}
      import jwt from 'jsonwebtoken';

      const payload  = { entity_type:'subscriber', entity_id:"johndoe", exp:1725814228 };

      const secret = 'your PEM format signing key';

      // if base64 signing key format is used use below code to convert to PEM format.
      const secret = Buffer.from('your_base64_signingKey', 'base64').toString('utf-8')

      const signedUserToken = jwt.sign(payload, secret,{ algorithm: 'ES256' })
      ```
    </CodeGroup>
  </Step>

  <Step title="Using signed user token in client">
    After creating user token on backend send it to your Frontend application to be used in SuprSend SDK as user token.

    <CodeGroup>
      ```javascript Javascript theme={"system"}
      import SuprSend from '@suprsend/web-sdk';

      const suprSendClient = new SuprSend(publicApiKey: string);

      const authResponse = await suprSendClient.identify(user.id, user.userToken);
      ```
    </CodeGroup>
  </Step>
</Steps>

### Token expiry handling

To handle cases of token expiry our client SDK's have **Refresh User Token callback** as parameter in identify method which gets called to get new user token when existing token is expired.

<CodeGroup>
  ```javascript Javascript theme={"system"}
  const authResponse = await suprSendClient.identify(user.id, user.userToken,
    { refreshUserToken: (oldUserToken, tokenPayload) => {
       //.... write your logic to get new token by making API call to your server...
       // return new token
    }});
  ```
</CodeGroup>

***