API Authentication: Secure KYC API Requests

Finding Your API Key

In Didit, API keys are scoped to a specific Application within your account. An Application is a workspace where you can configure workflows and manage verifications for a particular project or environment. Every Application gets a primary API key with full access when you create it. You can add more keys next to it, each with only the access a service or partner needs. To find your keys:

Go to the Didit Business Console and sign in.

Select your Application

Choose the Application you want to work with from the dropdown menu at the top.

Open API keys

Navigate to Developers -> API keys in the left-hand sidebar.

Copy or create a key

The Primary key is the Application’s own secret. Create a new key to give a service or partner its own secret, with the access it needs.

Your API Key is a Secret — treat it like a password.The primary key provides full access to the API on behalf of your Application. Never expose it in frontend code, public repositories, or client-side bundles. Always keep it server-side only.

API key format

New API keys start with sk_live_ for a live application or sk_test_ for a sandbox application, followed by 43 URL-safe characters (letters, digits, - and _). Keys created before this format have no prefix and keep working unchanged. Send the whole key, prefix included, in the x-api-key header, and do not reject a key because it has no prefix.

Find your organization ID

Your Organization ID is the UUID that identifies your organization. You use it in organization-scoped API paths such as /auth/v2/organizations/me/{org_id}/applications/. You can copy it directly from the Business Console, with no API call needed:

Open organization settings

In the Didit Business Console, go to Organization Settings.

Copy the organization ID

The Organization ID field shows your org’s UUID next to the organization name, with a copy-to-clipboard button.

Making Authenticated Requests

To authenticate an API request, include your secret API key in the x-api-key HTTP header. Here is an example of an authenticated request to the Create Session endpoint:

cURL

curl --request POST \
     --url https://verification.didit.me/v3/session/ \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: YOUR_API_KEY' \
     --data '
{
  "workflow_id": "WORKFLOW_ID",
  "vendor_data": "USER_ID",
  "callback": "CALLBACK_URL"
}
'

Error Handling

If your API key is wrong, malformed or revoked, the API returns 401 Unauthorized:

{
  "detail": "Authentication credentials were not provided or are invalid."
}

An expired key also returns 401, with "detail": "This API key has expired.". A request with no key returns 403 with "detail": "You do not have permission to perform this action.".

Status Code	Meaning
401	API key is wrong, malformed, revoked or expired
403	No API key was sent, the key does not have access to the requested resource or action, or the request came from an address outside the key’s IP list
403 with `"code": "application_deleted"`	The key belongs to an application that was deleted. The API answers this for a few minutes after the deletion, then refuses the key like any invalid key. Do not retry: the application and its keys no longer exist.
404	On a session route: the session is outside the key’s workflows or statuses

The API errors page lists every status, body and code.

Scoped API keys

Give each service or partner its own key instead of sharing the primary one. Each key has its own access: none, read or write for every resource (sessions, decisions, media, people, companies, transactions, workflows, webhooks, application settings, analytics), and optional limits to some workflows, to approved sessions only, to a list of IP addresses, and to an expiry date. You can rotate a key with a 24-hour overlap, and revoke it at once. Keys created before scoped access existed keep full access. See API keys for the presets, the resources each one covers, and how the API answers a scoped key.

If you receive a 401 error, double-check that you are using the correct API key for the right Application and that it has not been regenerated.

Overview

Pricing

Workflows & Verification

Review & Operations

Entities (Users & Businesses)

Settings & Customization

Security & Compliance

Didit Academy

Resources

API Authentication: Secure KYC API Requests

Finding Your API Key

API key format

Find your organization ID

Making Authenticated Requests

Error Handling

Scoped API keys