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

# Authentication

> How to authenticate with the DarknetSearch API — JWT bearer tokens, refresh, and 2FA.

Everything you need to start calling the API — the base URL and how to authenticate. Every other guide assumes what's on this page.

### Base URL

All API requests go to:

```
https://client-api.leak.center/api
```

Endpoint paths throughout these guides are relative to this base.

<Info>
  The API uses **JWT bearer tokens**: exchange your credentials for an access token, send it on every request, and refresh it when it expires.
</Info>

### How it works

* **Access token** — valid for 24 hours. Sent on every request as a bearer token.
* **Refresh token** — valid for 7 days. Used to mint new access tokens without sending credentials again.

Both come back from a single login call. A typical integration logs in once, caches the tokens, and refreshes the access token each day until the refresh token expires.

### 1. Get a token

`POST` your credentials to the token endpoint. It returns an `access` and a `refresh` token.

```bash theme={"dark"}
curl https://client-api.leak.center/api/token/ \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com", "password": "YOUR_PASSWORD"}'
```

```json theme={"dark"}
{
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6..."
}
```

If the account has 2FA enabled, add a current `otp` — see [Two-factor authentication](#two-factor-authentication).

→ [`login` in the API reference](https://client-api.leak.center/scalar-docs/#tag/user-settings/POST/token/)

### 2. Authenticate every request

Send the access token in the `Authorization` header on every call. Every endpoint requires it.

```bash theme={"dark"}
curl https://client-api.leak.center/api/service/domain_quick_search/ \
  -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"search_term": "acme.com"}'
```

A missing or invalid token returns `401`.

### 3. Refresh when it expires

Access tokens are valid for 24 hours. When one expires, a request returns `401` — exchange your refresh token for a new access token instead of logging in again.

```bash theme={"dark"}
curl https://client-api.leak.center/api/token/refresh/ \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"refresh": "YOUR_REFRESH_TOKEN"}'
```

```json theme={"dark"}
{ "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6..." }
```

After 7 days the refresh token expires too; then log in again (step 1).

→ [`token_refresh` in the API reference](https://client-api.leak.center/scalar-docs/#tag/user-settings/POST/token/refresh/)

### Two-factor authentication

If an account has 2FA enabled, the login call requires a current TOTP code in the `otp` field:

```bash theme={"dark"}
-d '{"email": "you@company.com", "password": "YOUR_PASSWORD", "otp": "123456"}'
```

To enable 2FA on an account:

<Steps>
  <Step title="Start enrollment">
    [`setup_2fa`](https://client-api.leak.center/scalar-docs/#tag/user-settings/POST/service/setup_2fa/) returns a `seed` and a `qr_code_url`. Add it to your authenticator app.
  </Step>

  <Step title="Confirm">
    [`verify_2fa_enrollment`](https://client-api.leak.center/scalar-docs/#tag/user-settings/POST/service/verify_2fa_enrollment/) with a current `otp` activates 2FA and returns **backup codes** — store them securely.
  </Step>
</Steps>

<Warning>
  For system integrations, use a **dedicated service account**. If that account has 2FA enabled, your integration must generate the current TOTP code at login — so many teams keep 2FA off for machine accounts and protect the credentials another way.
</Warning>

### Best practices for integrations

* Use a dedicated service account, not a person's login.
* Store credentials in a secret manager — never in code or version control.
* Cache the access token and reuse it; refresh on `401`, re-authenticate only when refresh fails.
* Send `Authorization: Bearer <access>` on every request.

### Change a password

[`new_password`](https://client-api.leak.center/scalar-docs/#tag/user-settings/POST/service/new_password/) updates the password for the authenticated account (`password`, `new_password`, `confirm_new_password`).

### Endpoints

| Action               | Endpoint                                                                                                                                                                                                                            |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Log in (get tokens)  | [`POST /token/`](https://client-api.leak.center/scalar-docs/#tag/user-settings/POST/token/)                                                                                                                                         |
| Refresh access token | [`POST /token/refresh/`](https://client-api.leak.center/scalar-docs/#tag/user-settings/POST/token/refresh/)                                                                                                                         |
| Enable 2FA           | [`setup_2fa`](https://client-api.leak.center/scalar-docs/#tag/user-settings/POST/service/setup_2fa/) → [`verify_2fa_enrollment`](https://client-api.leak.center/scalar-docs/#tag/user-settings/POST/service/verify_2fa_enrollment/) |
| Change password      | [`new_password`](https://client-api.leak.center/scalar-docs/#tag/user-settings/POST/service/new_password/)                                                                                                                          |