# Authentication

> Send your Ur Next Door API key as a Bearer token or an X-API-Key header, on the apex domain only. What a key can do, and the 401 and 421 errors.

Source: https://docs.urnextdoor.com/getting-started/authentication/

Every request except `GET /api/v1/openapi.json` must carry your API key in a header.

## Send the key in a header

Use either header. They are equivalent; pick whichever your tool supports.

```http
Authorization: Bearer und_sk_...
```

```http
X-API-Key: und_sk_...
```

- **Never put the key in the URL** (for example `?api_key=`). Query strings are not accepted, and URLs end up in logs and browser history.
- Some hosting setups strip the `Authorization` header from a request. If a tool reports `missing_api_key` although you set the Bearer header, switch to `X-API-Key`.
- Call the API only over `https://`.

In code, read the key from the `UND_API_KEY` environment variable instead of writing it into the file:

**cURL**

```bash
curl "https://urnextdoor.com/api/v1/me" \
  -H "Authorization: Bearer $UND_API_KEY"
```

**JavaScript**

```js
const res = await fetch("https://urnextdoor.com/api/v1/me", {
  headers: {
    Authorization: `Bearer ${process.env.UND_API_KEY}`,
  },
});
console.log(res.status, await res.json());
```

**Python**

```python
import os

import requests

api_key = os.environ["UND_API_KEY"]

response = requests.get(
    "https://urnextdoor.com/api/v1/me",
    headers={
        "Authorization": f"Bearer {api_key}",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

**PHP**

```php
<?php
$apiKey = getenv('UND_API_KEY');

$ch = curl_init('https://urnextdoor.com/api/v1/me');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
    ],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

echo $status, PHP_EOL, $body, PHP_EOL;
```

Sample response: `200 OK`

```json
{
  "ok": true,
  "user": {
    "id": 7,
    "username": "aarav",
    "display_name": "Aarav",
    "plan": "free",
    "profile_url": "https://urnextdoor.com/users/aarav"
  },
  "key": {
    "id": 3,
    "name": "Claude Code",
    "prefix": "und_sk_7Hq2x",
    "scopes": [
      "content",
      "media",
      "schedule",
      "read"
    ],
    "created_at": "2026-10-15T09:00:00Z",
    "expires_at": "2027-01-13T09:00:00Z"
  },
  "request_id": "9f8e7d6c5b4a3921"
}
```

## Use the apex domain

The base URL is always `https://urnextdoor.com/api/v1`. Community pages live on their own subdomains (for example `mom-to-be.urnextdoor.com`), but the API does not: a call to a subdomain answers `421` with the code `wrong_host`. To post inside a community, call the apex domain and send `community_id` or `community` in the body.

## What a key looks like

A key is `und_sk_` followed by 49 letters and digits: 43 random characters and a 6 character checksum, 56 characters in all. The prefix and checksum let secret scanners spot a leaked key and tell a real key from a typo. Only the first 12 characters (for example `und_sk_7Hq2x`) and the last 4 are ever shown again after creation.

## What a key can and cannot do

A key acts as the member who created it:

- It can do what its [scopes](https://docs.urnextdoor.com/getting-started/scopes.md) allow, and never more than you could do yourself on the website. For example, posting into a community needs you to be an editor (or above) of that community, or the request answers `403 forbidden`.
- It cannot see or change your password, email, billing or other keys. Keys are managed only in Settings, behind your normal sign in.
- It stops working when you revoke it, when it expires, when you reset your password (all keys are revoked), or while your account is suspended. If a suspended account is reinstated, its keys work again unless they were revoked.

## Servers, CLIs and agents only

The API sends no CORS headers, so a web browser will refuse to call it from a page's JavaScript. This is deliberate: a key placed in a web page can be read by anyone who opens the page. Call the API from a server, a script, a command line tool, an automation platform or an AI agent.

## Authentication errors

| Status | Code | Meaning | What to do |
| --- | --- | --- | --- |
| 401 | `missing_api_key` | No key header was sent. | Check the header name and that `UND_API_KEY` is set in that process. |
| 401 | `invalid_api_key` | The key is unknown, mistyped, revoked or expired, or the account is not active. | Check the key, or create a new one. |
| 403 | `insufficient_scope` | The key is valid but lacks the scope this endpoint needs. | Create a key with that scope. |
| 421 | `wrong_host` | You called a community subdomain. | Use `https://urnextdoor.com/api/v1`. |
| 429 | `rate_limited` | Too many requests, or too many failed key checks from your address. | Wait for the `Retry-After` seconds. |

Repeated failed key checks from one network address are limited, so keys cannot be guessed. Fix the key before retrying in a loop.

## Next steps

- [Scopes](https://docs.urnextdoor.com/getting-started/scopes.md): choose what each key may do.
- [Make your first request](https://docs.urnextdoor.com/getting-started/first-request.md).
- [Errors](https://docs.urnextdoor.com/errors.md): the full list of codes.