Skip to main content
POST
cURL
Didit’s Create Application API creates a separate application for each customer, brand or environment. Use this endpoint when you need to separate verification traffic, credentials, branding, or reporting inside the same organization. This is especially useful for resellers that create one application per customer. It also works well when your own company has multiple products, brands, regions, staging/production environments, or use cases that should not share the same API key and application-level settings.
All Auth API endpoints use https://apx.didit.me/auth/v2. Use the returned api_key as x-api-key when calling https://verification.didit.me/v3/... endpoints such as sessions and workflows.

Data location

Each application stores and processes its verification data in one place, its data location, chosen when you create it with data_location. Today the only location is eu, the European Union (Ireland), which is also the default when you leave the field out. Australia (Sydney, au), Mexico (mx), the United Arab Emirates (ae) and the United States (N. Virginia, us) are coming soon: a request that names them answers 400 This data location is not available yet. and creates nothing. Every read of the application returns its data_location, and it can’t be changed after the application is created. See Data location.

Admin sign-in URL

Set initiate_login_uri to the application page that starts a fresh authorization request, for example https://acme.example/login with website_url: "https://acme.example". It defaults to an empty string. It is separate from the OAuth callback in redirect_uris. A nonempty URI must use HTTPS on the exact registered website hostname, with no userinfo, query, fragment, whitespace or port other than 443. Subdomains must match. A policy violation returns HTTP 400 with an initiate_login_uri field error, https_url_on_registered_website_required. Changing website_url also revalidates the saved URI: update it to the new hostname or clear it in the same PATCH. Read the admin-sent sign-in handoff before implementing this page.

Authorizations

Authorization
string
header
required

RS256-signed JWT access_token returned by POST /programmatic/login/ or POST /programmatic/verify-email/. Send as Authorization: Bearer <access_token>. Default lifetime is 86400 seconds (24h). This token is only valid against the Account Management endpoints on apx.didit.me/auth/v2. The verification API (verification.didit.me/v3) uses the long-lived api_key as x-api-key instead.

Path Parameters

org_id
string<uuid>
required

UUID of the organization. Look it up with GET /organizations/me/.

Example:

"a1b2c3d4-5678-90ab-cdef-111111111111"

Body

application/json

All fields are optional. Omitting the body creates an application with default name "<organization name> App" and no public URLs configured.

All fields are optional. Sending an empty body creates an application with a default name, in the European Union.

name
string

Application display name. Defaults to "<organization name> App".

Example:

"Acme Customer App"

website_url
string

Website or app URL associated with this application.

Example:

"https://acme.example"

redirect_uris
string[]

Allowed redirect URIs for OAuth-style and verification redirect flows.

Example:
terms_url
string

Terms of service URL shown in the verification flow.

Example:

"https://acme.example/terms"

privacy_url
string

Privacy policy URL shown in the verification flow.

Example:

"https://acme.example/privacy"

description
string

Internal description for the application (not shown to end users).

data_location
enum<string>

Where the application's verification data is stored and processed, chosen when the application is created. eu is the European Union (Ireland), the default. au (Australia, Sydney), mx (Mexico), ae (United Arab Emirates) and us (United States, N. Virginia) are coming soon: a request that names them answers 400 This data location is not available yet. An organization's Sandbox application is always in the European Union.

Available options:
eu,
au,
mx,
ae,
us
Example:

"eu"

initiate_login_uri
string
default:""

Application sign-in URL for an admin-sent sign-in link. Optional; an empty string disables sending. A nonempty value must use HTTPS and the exact hostname of website_url (subdomains must match), with no userinfo, query, fragment or whitespace and no port other than 443. The server also revalidates the saved URI when website_url changes; update or clear initiate_login_uri in the same PATCH if needed. The hosted handoff adds iss and login_hint, but creates no session or tokens. See /authentication/sign-in-methods#admin-sent-sign-in-link.

Maximum string length: 2048
Example:

"https://acme.example/login"

Response

Application created. The response includes the long-lived api_key; persist it now and use it as the x-api-key header on every https://verification.didit.me/v3/... call.

Full application record. uuid, client_id, and api_key never change after creation. data_location doesn't either, except once on the live application created with your organization, before it is used (see the update request).

uuid
string<uuid>

Application UUID. Use as {app_id} in subsequent calls.

Example:

"b2c3d4e5-6789-01bc-defg-222222222222"

name
string

Application display name shown in the Didit console.

Example:

"Acme Production App"

client_id
string

Public client identifier, safe to embed in OAuth-style flows.

Example:

"S9LIYGSoWNuGMLHsvEt9dQ"

api_key
string

Long-lived secret (also called client_secret). Use as the x-api-key header for every call to https://verification.didit.me/v3/... (sessions, workflows, AML, etc.). Treat as a credential; never expose client-side. New keys start with sk_live_ (live application) or sk_test_ (sandbox application), followed by 43 URL-safe characters (letters, digits, - and _). Keys created before this format have no prefix and keep working unchanged. For 72 hours after you recovered your account, list, retrieve and update return an empty string here instead of the key.

Example:

"sk_live_example_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

website_url
string | null

Website or app URL associated with this application.

Example:

"https://acme.example"

redirect_uris
string[]

Allowed redirect URIs for OAuth-style and verification redirect flows.

Example:
terms_url
string | null

Terms of service URL shown in the verification flow.

Example:

"https://acme.example/terms"

privacy_url
string | null

Privacy policy URL shown in the verification flow.

Example:

"https://acme.example/privacy"

description
string | null

Internal description for the application (not shown to end users).

created_at
string<date-time>
Example:

"2025-06-01T10:00:00Z"

data_location
enum<string>

Where the application's verification data is stored and processed, chosen when the application is created. eu is the European Union (Ireland), the default. au (Australia, Sydney), mx (Mexico), ae (United Arab Emirates) and us (United States, N. Virginia) are coming soon: a request that names them answers 400 This data location is not available yet. An organization's Sandbox application is always in the European Union.

Available options:
eu,
au,
mx,
ae,
us
Example:

"eu"

products
object[]
read-only

The application's products. Always all three, in this order: identity, transactions, authentication. A new application has identity enabled with every module on, and transactions and authentication disabled. Read-only: a products key in a create or update body is ignored.

Example:
mode
enum<string>
read-only

The application's environment. A live application bills every verification session and check created with its key. A sandbox application mocks every check and is never billed, so it is where you test (each sandbox application can create 500 test sessions every 24 hours). Read this field to pick the application: never infer the environment from the name.

Available options:
live,
sandbox
Example:

"live"

initiate_login_uri
string
default:""

Application sign-in URL for an admin-sent sign-in link. Optional; an empty string disables sending. A nonempty value must use HTTPS and the exact hostname of website_url (subdomains must match), with no userinfo, query, fragment or whitespace and no port other than 443. The server also revalidates the saved URI when website_url changes; update or clear initiate_login_uri in the same PATCH if needed. The hosted handoff adds iss and login_hint, but creates no session or tokens. See /authentication/sign-in-methods#admin-sent-sign-in-link.

Maximum string length: 2048
Example:

"https://acme.example/login"

Last modified on November 13, 2026