{% set api_key = user.get('api_key') if user else 'YOUR_API_KEY' %}
{% set uname = user.get('username') if user else 'YOUR_USERNAME' %}
<div class="docs-content" data-render>
# Authentication

DevPlace accepts four interchangeable authentication methods. The website uses the
session cookie; the other three authenticate **any request** - any page or action -
without a browser login, ideal for scripts and automation. See
[Conventions & Errors](/docs/conventions.html) for the base URL, request bodies,
content negotiation, pagination, and status codes that every endpoint shares.

{% if not user %}
> You are not logged in. Examples below use placeholders. [Log in](/auth/login) and
> reload this page to see ready-to-copy examples with your own API key.
{% else %}
> Examples below are filled in with your account (`{{ uname }}`) and your API key,
> ready to copy and paste.
{% endif %}

Your API key is a UUID shown on your [profile page]({% if user %}/profile/{{ uname }}{% else %}/profile/YOUR_USERNAME{% endif %}).
You can regenerate it there at any time; the previous key stops working immediately.

The interactive panels throughout the [API reference](/docs/index.html) pre-fill your API
key, so you can run user-level calls directly from these pages. Vote, reaction, bookmark, and
poll endpoints require an `X-Requested-With: fetch` header to return JSON instead of a
redirect; the panels and generated snippets add it automatically.

## 1. Session cookie

The website signs you in with a `session` cookie after you log in. Browsers send it
automatically - nothing to configure.

## 2. X-API-KEY header

Send your API key in the `X-API-KEY` header:

```bash
curl -H "X-API-KEY: {{ api_key }}" \
  {{ base }}/notifications
```

## 3. Bearer token

The same API key also works as a Bearer token, supported out of the box by many HTTP clients:

```bash
curl -H "Authorization: Bearer {{ api_key }}" \
  {{ base }}/notifications
```

## 4. HTTP Basic

Authenticate with your username (or email) and password. `curl -u` base64-encodes
the credentials for you:

```bash
curl -u {{ uname }}:YOUR_PASSWORD \
  {{ base }}/notifications
```

This sends an `Authorization: Basic base64(username:password)` header. You can also
build the header yourself:

```bash
curl -H "Authorization: Basic $(printf '%s' '{{ uname }}:YOUR_PASSWORD' | base64)" \
  {{ base }}/notifications
```

## 5. Access token (native)

DevPlace's own token endpoint issues short-lived access tokens that work as
Bearer / `X-API-KEY` credentials on every endpoint. Request a token once, use
it everywhere until it expires.

```bash
curl -X POST {{ base }}/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email": "YOUR_EMAIL", "password": "YOUR_PASSWORD"}'
```

The response is an OAuth2-style JSON object:

```json
{
  "access_token": "<64-char hex token>",
  "token_type": "bearer",
  "expires_in": 604800
}
```

Use the returned `access_token` as a Bearer token:

```bash
TOKEN="<access_token from above>"
curl -H "Authorization: Bearer $TOKEN" \
  {{ base }}/notifications
```

Or with the `X-API-KEY` header:

```bash
curl -H "X-API-KEY: $TOKEN" \
  {{ base }}/notifications
```

Tokens are valid for the configured session lifetime (default 7 days).  Manage
tokens with the CLI: `devplace token issue <user>`, `devplace token list <user>`,
`devplace token revoke <uid>`, `devplace token revoke-all <user>`.

## 6. DevRant auth token

If you have a DevRant auth token (the `key` field from the `POST /users/auth-token`
response), you can also use it as a Bearer token or `X-API-KEY` header on **any**
DevPlace API endpoint. The token must not be expired (default 7 days). See
[DevRant authentication](/docs/devrant-auth.html) for how to obtain one.

```bash
curl -H "Authorization: Bearer YOUR_DEVRANT_TOKEN_KEY" \
  {{ base }}/notifications
```

Or with the `X-API-KEY` header:

```bash
curl -H "X-API-KEY: YOUR_DEVRANT_TOKEN_KEY" \
  {{ base }}/notifications
```

## Performing actions

The same methods work on POST actions. For example, follow another user:

```bash
curl -X POST -H "X-API-KEY: {{ api_key }}" \
  {{ base }}/follow/SOME_USERNAME
```

Create a post:

```bash
curl -X POST -H "X-API-KEY: {{ api_key }}" \
  -d "topic=devlog" -d "title=Hello" -d "content=Posted from a script" \
  {{ base }}/posts/create
```

With a DevRant auth token:

```bash
curl -X POST -H "Authorization: Bearer YOUR_DEVRANT_TOKEN_KEY" \
  -d "topic=devlog" -d "title=Hello" -d "content=Posted from a script" \
  {{ base }}/posts/create
```

## Errors

Invalid credentials make protected endpoints respond with `401 Unauthorized`. Requests
with no credentials are treated as anonymous, and protected actions redirect to the login
page as in the browser. The full status-code and error-shape reference lives in
[Conventions & Errors](/docs/conventions.html).
</div>