{% 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 session cookie is
used by the website; the other three let you authenticate **any request** - any
page or action - without logging in through the browser, which is ideal for scripts
and automation. See also [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 for you.

## 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, which many HTTP clients support out
of the box:

```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
```

## 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
```

## Errors

If you supply credentials that are invalid, protected endpoints respond with
`401 Unauthorized`. Requests with no credentials at all 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>