# API Keys (/docs/developer/api-keys)

API keys let you authenticate programmatic requests to the Sift REST API. Each key is scoped to your organization.

## At a glance [#at-a-glance]

| | |
| --- | --- |
| Generate keys in Settings → Connections → Developer access | ✅ |
| Pass in the `X-API-Key` header | ✅ |
| Scoped to your organization | ✅ |
| Revoke any key, effective immediately | ✅ |
| Default Developer access profile | Reporting (`read`) |
| Permission profiles | Reporting, Import, Write, Read and write |
| Default expiry | 90 days |
| Retrieve a key after creation | ❌ shown only once |

## Generating a Key [#generating-a-key]

1. Go to **Settings → Connections → Developer access** (`/app/settings/api-keys`).
2. Choose a name, permission profile, and expiry. Create the key.
3. Copy the key immediately - it will not be shown again.

## Using Your Key [#using-your-key]

Pass the key in the `X-API-Key` header on every request:

```http
GET https://api.getsift.ai/v0/action/list
X-API-Key: sk_live_your_key_here
```

## Scopes [#scopes]

Developer access defaults to **Reporting**, with the `read` scope. Choose **Write** for general writes or **Read and write** for both. General write permission does not grant Custom API ingestion.

For [Custom API](/docs/integrations/custom-api), create an **Import** key under **Settings → Connections → Developer → API keys**. The source's Setup tab links there with the source preselected. It grants `ingest` and `ingest:read` for selected sources. It can validate, import, correct items, retry failed intake, and read receipts. It cannot read reporting data or send replies.

Use separate keys for ingestion and reporting. Expiry options are 30 days, 90 days, or no expiry. The default is 90 days.

## Service accounts [#service-accounts]

A service account gives a script, an integration, or an AI tool its own identity in Sift. Use one when a key needs more than the org defaults, or when you want to see which tool made a change.

* **Roles.** A service account holds your org's roles, the same roles you give people. Its keys can do what those roles allow.
* **Access.** **Read only** keys can only read, whatever the roles allow. **Read and write** keys can also make the changes the roles allow.
* **Keys.** Each account can hold several keys, so you can rotate without downtime. A key acts as its account, over the REST API and over [MCP](/docs/developer/mcp-connections).
* **Audit.** Changes made with its keys show the service account's name in the audit log.
* **Off switch.** Turn an account off to stop all of its keys at once. Delete it to remove it and its keys.

Super Admins manage service accounts in **Settings → Connections → Developer access → Service accounts**. Start from **Read only** (what a Manager can see, no changes), **Admin** (the Super Admin role, read and write), or **Custom**.

A service account cannot act on a person's own items, such as their profile, their dashboards, or their MCP connections. It cannot create service accounts or keys.

## Revoking a Key [#revoking-a-key]

You can revoke any key at any time from the same **Developer access** settings page. New requests fail after revocation. Do not assume revocation cancels a request already in progress.

## Best Practices [#best-practices]

* **One key per integration.** Don't share a single key across multiple systems. If one integration is compromised, you can revoke only that key without disrupting others.
* **Rotate regularly.** Generate a new key, update your integration, then revoke the old one.
* **Never commit keys to source control.** Store them in environment variables or a secrets manager.

<Callout type="warn">
  Treat API keys like passwords - never paste them into chat, logs, or public repositories.
</Callout>

## Related [#related]

<Cards>
  <Card href="/docs/developer/api" title="API">Use your key to call the REST API endpoints.</Card>
  <Card href="/docs/developer/query-syntax" title="Query Syntax">Filter the results your authenticated requests return.</Card>
</Cards>