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

# Authentication & API Keys

> Generate and manage API keys from the Connectly Settings page — with scoped permissions and optional expiration 🗝️

API keys authenticate your requests to the Connectly API. You can create multiple keys with different scopes and expiration dates — for example, a key scoped to messaging only for your backend, and a separate key with full access for internal tooling.

***

## Generate an API key

<Steps>
  <Step title="Open Settings">
    In the Connectly inbox, click **Settings** in the left sidebar, then select the **General** tab. Scroll down to the **API Key and Webhook Secret** section and click **Create API Key**.
  </Step>

  <Step title="Name your key">
    Give the key a descriptive name so you can identify it later — for example, `Production Backend` or ` Integration`.
  </Step>

  <Step title="Select scopes">
    Choose which permissions this key should have. If no scopes are selected, the key has full access to all operations.

    | Scope                 | What it allows                                                 |
    | --------------------- | -------------------------------------------------------------- |
    | `ai.manage`           | Manage AI tools and internal diagnostics                       |
    | `campaign.manage`     | Manage campaigns, templates, flows, automations, and audiences |
    | `commerce.manage`     | Manage orders, checkouts, billing, and delivery controls       |
    | `conversation.manage` | Manage rooms, inbox actions, tickets, and tags                 |
    | `customer.manage`     | Manage customer records and profile data                       |
    | `key.manage`          | Create, revoke, and manage API keys                            |
    | `messaging.send`      | Send outbound messages and campaigns                           |
    | `system.manage`       | Perform privileged internal system operations                  |
    | `workspace.manage`    | Manage business, channels, users, teams, and integrations      |

    <Tip>
      Follow the principle of least privilege — only select the scopes your integration actually needs. For example, a  webhook integration only needs `messaging.send` and `campaign.manage`.
    </Tip>
  </Step>

  <Step title="Set an expiration (optional)">
    By default, keys have no expiration. If you want the key to automatically expire — for example, for a temporary integration or a contractor — select an expiration period from the dropdown.
  </Step>

  <Step title="Create and copy the key">
    Click **Create Key**. Your API key is displayed **once only** — copy it immediately and store it somewhere secure such as a password manager or a secrets manager.

    <Warning>
      The key is shown only once at creation time. Connectly does not store the plaintext value. If you lose it, you'll need to generate a new one.
    </Warning>
  </Step>
</Steps>

***

## Use your API key

Include the key in the `X-API-Key` header on every request to the Connectly API:

```bash theme={null}
curl --request POST \
  --url https://api.connectly.ai/v1/businesses/<business_id>/send/messages \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <YOUR_KEY_HERE>' \
  --data '{...}'
```

Any request missing a valid `X-API-Key` header returns an `ERROR_TYPE_AUTHENTICATION` error.

***

## Manage existing keys

From **Settings → General → API Key and Webhook Secret** you can view all keys associated with your account, see their names, scopes, and expiration dates, and revoke any key that is no longer needed.

<Warning>
  Generating a new key does **not** automatically invalidate existing keys. To revoke a key, delete it explicitly from the Settings page.
</Warning>

***

## Security best practices

* **Never expose your API key client-side** — don't include it in frontend JavaScript, mobile apps, or public repositories.
* **Use scoped keys** — restrict each key to only the permissions it needs.
* **Rotate keys regularly** — especially after team member offboarding or if you suspect a key has been compromised.
* **Set expiration dates** for temporary integrations or external collaborators.
* **Store keys in a secrets manager** — use a tool like AWS Secrets Manager, HashiCorp Vault, or a password manager rather than hardcoding keys in config files.