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

# Authentication

> Send your access key with every call, and replace it if it leaks.

Every call needs your access key, except [`/v1/health`](https://docs.dis.dog/api-reference/endpoints/health).

## Send the key in a header

```bash theme={"system"}
curl https://api.dis.dog/v1/me \
  -H "Authorization: Bearer DD-7KQ2M-X9C4T-HB3RZ-W8N6P-YF5VA"
```

`X-API-Key: DD-…` works too, if your tool cannot set `Authorization`.

## One key for everything

DisDog accounts have no password. When you [create your account](https://dis.dog/register) you get one **access key**, and it does two jobs:

* it is your **login** on dis.dog,
* it is your **API key**.

It is `DD-` followed by five groups of five characters (letters and digits, 125 random bits). DisDog is forgiving about how you send it: case does not matter, the dashes and spaces are optional, and the `DD` prefix can be left out. These all reach the same account:

```text theme={"system"}
DD-7KQ2M-X9C4T-HB3RZ-W8N6P-YF5VA
dd-7kq2m-x9c4t-hb3rz-w8n6p-yf5va
7KQ2M X9C4T HB3RZ W8N6P YF5VA
```

> [!NOTE]
>
> DisDog checks your key against a keyed hash, and keeps an encrypted copy (AES-256-GCM) only so you can show it again: on your [account page](https://dis.dog/account) it is blurred by default, one click shows or copies it.

## Get a new key

You have one key at a time. There are two ways to replace it:

| From | How | What happens |
| - | - | - |
| Your [account page](https://dis.dog/account), signed in | **Generate a new key**, then confirm | The new key is shown right away (and stays visible on your account page). The old one stops working at once, and every other device is signed out. |
| [dis.dog/recover](https://dis.dog/recover), if you lost the key | Enter your account’s email and the 6-digit code we send | Same: a new key, the old one dead, every session signed out. Your plan and usage are kept. |

Then update the key wherever you use it.

> [!WARNING]
>
> If your key may have leaked — pushed to a repository, pasted in a chat, logged by a proxy — replace it right away. Until you do, anyone holding it can search with your quota and sign in to your account.

## Keep it private

* Your key is personal, like a password. Do not share it.
* Keep it on a server or in your own scripts, in an environment variable or a secret manager, never in your source code.
* Send it in a header, **never in the URL**: URLs end up in logs, browser history and proxies.
* The API answers browsers from any site (that is how the playground in these docs works). **Do not put your key in a web page or an app other people use**: anyone who can read the page can read the key. Call the API from your backend.

## Plans

The API comes with the **Hound** and **Alpha** plans. On Pup (free), the key works for [`/v1/me`](https://docs.dis.dog/api-reference/endpoints/me) and [`/v1/modules`](https://docs.dis.dog/api-reference/endpoints/modules) only; every other route answers `403 plan_has_no_api`. When a paid plan ends after its 30 days, the account goes back to Pup: your key keeps working on the website, and on the API for those two routes. [Limits per plan →](https://docs.dis.dog/limits.md)

## Authentication errors

| Status | Code | Meaning |
| - | - | - |
| `401` | `invalid_api_key` | No key in `Authorization` or `X-API-Key`, or a key that matches no account — mistyped, or replaced by a newer one. |
| `403` | `plan_has_no_api` | A valid key on the Pup plan, on a route other than `/v1/me` and `/v1/modules`. [Upgrade](https://dis.dog/pricing). |
| `429` | `too_many_requests` | More than 30 calls with a wrong key from your address in 15 minutes. Fix the key, then wait. |


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