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

# Set Up Didit Authentication by API

> Enable sign-in methods, settings, branding and protection from your own code with an owner-approved grant or an authentication-scoped key.

Didit Authentication lets you enable sign-in methods and read back your application's settings by API. Use an owner-approved grant or a named API key with the `authentication` scope.

> [!WARNING]
>
> Authentication is new. Set a method up in a sandbox application first, then in your live application.

Every call below goes to your application's Authentication management API. `MANAGEMENT_BASE` is:

```text theme={null}
https://apx.didit.me/auth/v2/organizations/{org_id}/applications/{application_id}/authentication/
```

The same routes are described by `openapi-authentication.json` under the `Setup` tag, which the server SDKs regenerate from.

## Which credential to use

Any of three credentials works, and each is limited to what its owner approved.

| Credential | Sent as | What it can do |
| - | - | - |
| Named API key with the `authentication` scope | `x-api-key: <key>` | Configures its own application, and reads it. A key with `read` can only read the setup; `write` can read and change it. |
| Owner-approved grant with `didit:management` | `Authorization: Bearer <access_token>` | Configures the applications of the organizations approved at consent, within the person's role. |
| Console session | `Authorization: Bearer <console session token>` | Reads or changes settings according to the person's organization membership and role. End-user views also require a console session and the appropriate permissions. |

These credentials are refused with `403` on every setup route, whatever the request asks for:

* The application's **primary secret**.
* A token from `POST /programmatic/login`, which is minted for the application rather than for the console.
* A key **without** the `authentication` scope, including a key created with every resource at its highest level: those are listed as full access, keep `scopes` empty and are not accepted on these routes.
* A key of **another application**, a grant limited to `didit:verification`, and a grant approved for another organization.

A request with no credential at all answers `401`. A grant or a key keeps its own limits on top: the grant its scopes, organizations and the person's role, the key its scopes, IP allowlist and expiry.

## Approve access

### With a named API key

Open **Developers -> API keys** in the [Business Console](https://business.didit.me) and create a key for the application you are setting up. Give it the `authentication` resource at **read** or **write**: read covers every call that reads the setup (`GET`); write covers every call that changes it (`POST`, `PUT`, `PATCH`, `DELETE`) and also reads it. See [API keys](https://docs.didit.me/console/api-keys.md) for expiry, IP allowlists and rotation; a key belongs to one application and works only for it.

### Through an MCP connection

An agent connected to the Didit MCP server uses the grant its owner approved on the consent screen, with `didit:management`. See [MCP authentication](https://docs.didit.me/integration/mcp/authentication.md#log-in-with-didit).

### For an owner without a password

The device-code grant ([RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)) lets an owner who signs in with Google, a passkey or an emailed code approve the same access from any browser, without typing a password. See [sign in without a browser](https://docs.didit.me/integration/mcp/authentication.md#sign-in-without-a-browser-device-code).

## Enable email code

`PUT methods/{name}/` takes `enabled`, and nothing else for a method that needs no credentials.

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/code/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'
```

It answers the method as it now stands:

```json theme={null}
{"name": "code", "enabled": true}
```

When you read the configuration back, the entry for email code includes `credential_source: null`. Methods that are always on cannot be turned off: that request answers `{"enabled": "always_on"}`.

## Enable Google

A social method takes your own OAuth app's credentials, or Didit's test app on a sandbox application.

### With your own Google app

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/google/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "credentials": {"client_id": "1234.apps.googleusercontent.com", "client_secret": "GOCSPX-..."}}'
```

Register the `callback_uri` the response returns at your provider. The secret is write-only: no response returns it, and `client_id` is the only part you can read back. Switching a method on without credentials, when none were stored before, answers `{"credentials": "required"}`.

### With Didit's test app (`didit_test`)

A **sandbox application** can use Didit's own social apps instead of yours, which is enough to finish a setup and prove it works:

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/google/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "credential_source": "didit_test"}'
```

`didit_test` covers **Google, Microsoft, Apple and GitHub**, on sandbox applications only:

| Answer | When |
| - | - |
| `{"credential_source": "sandbox_only"}` | The application is live. Test apps never serve live sign-ins. |
| `{"credential_source": "unavailable"}` | The deployment has no test app for that provider, so the method stays off. |
| `200` with `configured: true` | The test app serves the method, and hosted sign-in offers it. |

`GET` on the configuration names the providers a test app can serve for this application in `didit_test_credentials`, which is `false` for all four on a live application.

## Read the setup back

`GET` on `MANAGEMENT_BASE` is the read-back: every method with `enabled` and `credential_source`, plus the callback URLs, session rules and sign-up policy.

```bash theme={null}
curl --fail-with-body "$MANAGEMENT_BASE" -H "x-api-key: $DIDIT_API_KEY"
```

```json theme={null}
{
  "enabled": true,
  "methods": [
    {"name": "code", "enabled": true, "credential_source": null},
    {"name": "google", "enabled": true, "credential_source": "didit_test", "configured": true, "client_id": "didit-test-google"},
    {"name": "password", "enabled": false, "credential_source": null}
  ],
  "didit_test_credentials": {"google": true, "microsoft": true, "apple": true, "github": true},
  "redirect_uris": ["https://app.example.com/auth/callback"]
}
```

Disabled methods are listed too, so one `GET` says what is on and what is not. `enabled` at the top is `false` when Authentication is disabled for the application. Any setup change made with a management grant or a named key then returns `409` with `{"detail": "product_disabled"}`, and nothing is written. No setup call turns Authentication on: a person turns it on for the application in the console, and your calls work from then on.

## The rest of the setup

| Route, under `MANAGEMENT_BASE` | Methods | What it holds |
| - | - | - |
| `settings/` | `GET`, `PATCH` | Agent access, organizations, the MFA policy, the default member role, disabled webhook events |
| `onboarding/` | `GET`, `PATCH` | Which setup steps are done, and whether people sign in on the hosted page or your own screens |
| `branding/` | `GET`, `PATCH` | The hosted pages' texts and legal links (the logo and colours come from Customization) |
| `protection/` | `GET`, `PATCH` | The bot protection policies ([bot protection](https://docs.didit.me/authentication/bot-protection.md)) |
| `verified/` | `GET`, `PATCH` | The sign-up verification level, step-up rules and token claims |
| `emails/`, `emails/{key}/` | `GET` | The sign-in emails this application sends, and a rendered preview |
| `domain/` | `GET`, `PUT`, `DELETE` | The hosted origin and the custom sign-in domain |
| `domain/verify/`, `domain/activate/` | `POST` | Check the domain's DNS and certificate, then make it the canonical origin |
| `native-apps/` | `GET`, `PUT` | The iOS and Android apps that share the application's passkeys |

A grant or a key gets the setup and its counters, never end-user data: `users/`, `sessions/`, `sign-ins/`, `overview/`, customer organizations, roles, imports, agent sessions and test emails still need a console session.

The `agent_humans_only` setting applies to the whole application. Only an organization owner or admin can change it. A named key receives `403 owner_or_admin_required`. Turning the setting on also requires an enrolled passkey (`passkey_required`).

## Errors

| Answer | Meaning |
| - | - |
| `401` | No credential. |
| `403` | A credential that cannot configure this application, or one of its own limits: `ip_not_allowed`, an expired key, a read-only key on a write route. |
| `409 {"detail": "product_disabled"}` | Authentication is turned off for the application, so a setup change made with a grant or a key is refused. A person turns it on in the console. |
| `400 {"<field>": "<code>"}` | `sandbox_only`, `unavailable`, `not_supported`, `required`, `always_on`, `method_unavailable`, `unknown_field`. |
| `404` | The requested resource could not be found. |


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