# Managing your API keys

Source: https://help.didit.me/account-organization/api-keys
Updated: 2026-10-12

Create API keys under Developers, API keys in the console. Give each service its own scoped key, keep keys server-side, rotate them safely, fix 401s and 403s.

**Developers → API keys**, scoped to the application you have selected. Every
application has a **Primary** key, and you can create more, one per service, each
with its own access and expiry. A key is a
server-side secret: never in frontend code or an app bundle.

[Video: Set up API keys and test your webhooks - Didit Academy](https://www.youtube.com/watch?v=thOMIGbNLP0&t=38)

[Video: KYC API integration in 5 steps, with an AI setup prompt for Cursor - Didit Academy](https://www.youtube.com/watch?v=kTAarcImy7E)

Your API keys live under **Developers → API keys** in the console, scoped to the application you're working in. Treat every key like a password: it grants API access on that application's behalf.

## Finding your key

1. **Log in to the Business Console**

   Go to [business.didit.me](https://business.didit.me) and sign in.

2. **Select your application**

   Pick the application from the application card at the top of the sidebar. Each application has its own keys.

3. **Open Developers, then API keys**

   The **Keys** tab lists every key, starting with the **Primary** key, with its access, when it was last used and when it expires.

![The API keys page in the Didit console with the list of keys](https://help.didit.me/screenshots/api-keys-light.webp)

*Every key for this application: the Primary key first, then the ones you created.*

## Creating a key

Give each service that calls Didit its own key, so you can see what each one does and revoke it alone.

1. **Press Create key**

   On **Developers → API keys**.

2. **Name it and pick the environment**

   Name the key after the service that will use it, choose **Live** (real verifications, billed) or **Sandbox** (test data, never billed; the key is created in your organization's Sandbox application), and choose when it expires: never, after 30 days, 90 days or a year, or on a date you pick.

3. **Choose its access**

   **Full access** reads and writes everything, for your own backend. **Read only** sees sessions, decisions and media but can't change anything, for a partner that only needs results. **Custom** lets you pick, resource by resource. Untick **Include media** when the service only needs the decision, not ID images, selfies, videos or PDF reports.

4. **Review and copy the secret**

   The full secret is shown once, when the key is created. Copy it straight into your secret manager.

The **Primary** key is the application's original secret. It always has full access and can be rotated but not revoked.

## The API key and the signing secret are different things

Worth stating plainly, because mixing them up produces confusing errors:

| | What it's for | Where |
|---|---|---|
| **API key** | Authenticating your calls to Didit, in the `x-api-key` header | Per application, as many as you need |
| **Webhook signing secret** | Verifying that an incoming webhook really came from Didit | Per webhook **endpoint** |

Sending the signing secret as your API key produces a 401. Verifying a webhook with your API key produces a signature mismatch. Both are common.

> **Warning:** Your API key is a secret. Never put it in frontend code, a public repository, or a
> mobile app bundle - keep it server-side only. A key in a shipped app bundle is a
> key an attacker has. See
> [API authentication](https://docs.didit.me/getting-started/api-authentication).

## Getting a key for testing

You don't test against production. Switch the console to **Sandbox** and create a key there, or pick **Sandbox** as the environment when you create one. Sandbox sessions mock every external check, are never billed, and don't touch real user data.

A key belongs to one application, and with it to that application's environment: a sandbox key never creates a live verification, and a live key never creates a sandbox one. It's worth naming your keys unambiguously in whatever holds your secrets. See [testing in sandbox](https://help.didit.me/getting-started/sandbox-and-testing).

## Rotating your key

If a key may have been exposed, open it and choose **Rotate key**. You get a new secret, and the old one keeps working for **24 hours**, so you can deploy the new secret without downtime. After that, every request with the old secret returns a 401.

If a key must stop working right now, **Revoke key** instead. Revoking stops it at once and can't be undone. The Primary key can only be rotated.

Rotating on a schedule is good practice. Plan it as a deploy, not a click.

## Fixing 401 and 403

| Error | Cause | Fix |
|---|---|---|
| `401` | The key is missing, malformed, expired, revoked, or rotated more than 24 hours ago | Check the key under **Developers → API keys** for that application. Look for stray whitespace or quotes, and check you didn't paste a signing secret |
| `403` | The key is valid but this call isn't allowed | Usually the wrong application, a sandbox-only field on a live key (or the reverse), access the key wasn't given (a read-only key trying to write, for example), or a feature not enabled on your account |

A `403` on a specific workflow almost always means the key belongs to a **different application** than the one that owns that workflow. Switch application in the console and use one of its keys instead. Full breakdown: [API errors and what they mean](https://help.didit.me/integration/api-errors).

## Restricting what a key can do

Pick the access when you create the key, and change it later with **Edit access** (the secret stays the same; the Primary key's access can't be edited). **Read only** keeps a partner from changing anything, **Custom** sets None, Read or Write per resource (sessions, decisions, media, people, companies and more), and leaving **Include media** off keeps a service from downloading ID images, selfies, videos and PDF reports. Under **Limits**, a key can also be held to some workflows, to approved sessions only, or to a list of IP addresses: a request from outside the list answers 403, and a session outside the key's workflows or statuses answers 404. Open a key to see exactly what it can do; a key can never do more than its access allows.

## Who on your team can see keys

Key visibility follows role: seeing the page needs permission to read API keys, which the **Developer** role includes. Secrets stay masked in the console. If a teammate can't find the page, check their role before reporting it. See [inviting team members and setting roles](https://help.didit.me/account-organization/team-members-and-roles).

## Every call is logged

API-key requests appear in the **Audit log** attributed to the key rather than to a person. That's exactly why a shared key across several services makes an incident harder to investigate: one key per consumer is easier to reason about. See [using audit logs](https://help.didit.me/account-organization/audit-logs).