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

# Service accounts

> Give your integrations their own identity and API keys, scoped to the knowledge stores they need.

A **service account** is an identity for an integration, such as a customer portal, a Slack bot, or a nightly sync. It's a member of your organization that can't sign in: you give it access to knowledge stores, then create API keys for it. Requests made with its keys act as the service account, with its permissions.

Service accounts are never billed as users and never receive emails. Use them instead of a person's credentials, so an integration keeps working when someone leaves and its access is limited to what it needs.

<Note>
  Only organization admins can manage service accounts.
</Note>

## Create a service account

1. Open your organization and click **Service accounts** in the sidebar.
2. Click **New service account**.
3. Enter a **Name**. Name it after the integration that will use it, for example `Customer portal`. Names must be unique in the organization.
4. Click **Create**. The service account's page opens.

## Give it access to knowledge stores

A service account can only reach the stores you add it to.

1. On the service account's page, under **Knowledge stores**, click **Add store**.
2. Select the **Knowledge store**.
3. Choose a profile: **Technical User** (the default), **Contributor**, or **User**. See [User management](/guides/user-management#profiles).
4. Choose its permissions:
   * **DataReader** and **Admin**, as for any user. See [User management](/guides/user-management#permissions).
   * **Impersonate**: lets the integration act on behalf of a member of the store. See [Act on behalf of a user](#act-on-behalf-of-a-user).
5. Click **Save**.

You can change or remove a store's access at any time from the same card. In a store's **Settings > Users**, a read-only **Service accounts** tab lists the service accounts with access to that store.

## Create an API key

1. On the service account's page, under **API keys**, click **Create key**.
2. Enter a **Name**, for example `production`.
3. Set **Expires on**. It defaults to one year from today. Leave it empty for a key that never expires.
4. Click **Create**, then copy the key.

Keys start with `cfk_`. Store the key in your integration's secret manager: anyone holding it can act as the service account. Organization admins can show an active key again later with **Reveal** on the key's row.

## Authenticate with a key

Send the key as a bearer token on Clarifeye REST API requests:

```bash theme={null}
curl https://eu.app.clarifeye.ai/api/v1/users/me/ \
  -H "Authorization: Bearer cfk_your_key"
```

Replace `eu.app.clarifeye.ai` with your own server if you're on another environment or a dedicated deployment.

A request with a revoked, expired, or invalid key, or with a key of a disabled service account, is refused with HTTP `403`.

## Act on behalf of a user

With the **Impersonate** permission on a store, an integration can act as a specific member of that store by adding the `X-Impersonate-Email` header:

```bash theme={null}
curl https://eu.app.clarifeye.ai/api/v1/projects/<project_id>/playground-conversations/ \
  -H "Authorization: Bearer cfk_your_key" \
  -H "X-Impersonate-Email: jane@example.com"
```

The request then runs with that member's permissions. If the service account doesn't have **Impersonate** on the store, or the email isn't a member of the store, the request is refused.

## Rotate a key

Several keys can be active at once, so you can rotate without downtime:

1. Create a new key.
2. Switch your integration to the new key.
3. Click **Revoke** on the old key's row.

Revoking refuses requests that use the key immediately. Revoked keys stay listed, greyed out, and can't be revealed again.

## Set a usage limit

Under **Usage limit**, choose:

* **Organization default**: the per-user limits set on the [Usage](/guides/usage#usage-limits-and-alerts) page.
* **Custom limit for this service account**: set **Notify them at** and **Block them at**, in CCU.
* **No limit**.

The card shows how much the service account has used in the current period.

## Disable a service account

Turn off **Enabled** on the service account's page. While it's disabled, every key of the account is refused. Its store access and the data it created are kept, and turning it back on restores access. Service accounts can't be deleted.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.