{% set api_key = user.get('api_key') if user else 'YOUR_API_KEY' %}
{% set uname = user.get('username') if user else 'YOUR_USERNAME' %}
# Authentication
DevPlace recognizes three account credentials: your **username and password**, your
**email address and password**, and your **personal API key**. The password
credentials work everywhere a password is asked for: the login form, the JSON login,
the token endpoint, and HTTP Basic (the identifier may be the username or the email
address; usernames are case-sensitive, email addresses are not). The API key
authenticates **any request** - any page or action - without a browser login, ideal
for scripts and automation. On top of those, the `X-API-KEY` and `Bearer` headers also
accept two token kinds (native access tokens and DevRant auth tokens, sections 5
and 6). 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.
Clients and examples conventionally carry this personal key in the
`DEVPLACE_API_KEY` environment variable; DevPlace containers inject it automatically.
`DEVPLACE_API_KEY` is only the name of that variable - on the wire the value is always
sent as the `X-API-KEY` header or a `Bearer` token shown below.
Credentials are resolved in a fixed order: session cookie first, then `X-API-KEY`,
then `Authorization: Bearer`, then HTTP Basic. A valid browser session therefore wins
over header credentials sent along with it. Inactive accounts are rejected by every
method.
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=""
curl -H "Authorization: Bearer $TOKEN" \
{{ base }}/notifications
```
Or with the `X-API-KEY` header:
```bash
curl -H "X-API-KEY: $TOKEN" \
{{ base }}/notifications
```
The `email` field accepts your username or your email address (usernames are
case-sensitive, email addresses are not), and the body may be JSON or form data.
Missing fields return `400`, wrong credentials `401`, and a deactivated account `403`.
Tokens are valid for the configured session lifetime (default 7 days). Manage
tokens with the CLI: `devplace token issue `, `devplace token list `,
`devplace token revoke `, `devplace token revoke-all `.
## 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
```
## Logging in from a script
`POST /auth/login` (and `POST /auth/signup`) accept JSON as well as form data.
The `email` field accepts your username or your email address. A successful JSON
login returns the account's username, email, API key, and admin flag, so one
username/password or email/password call bootstraps every later request:
```bash
curl -X POST {{ base }}/auth/login \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"email": "YOU@EXAMPLE.COM", "password": "YOUR_PASSWORD"}'
```
```json
{
"ok": true,
"redirect": "/feed",
"data": {
"username": "YOU",
"email": "YOU@EXAMPLE.COM",
"api_key": "YOUR_API_KEY",
"is_admin": false
}
}
```
Store the `api_key` and use it as an `X-API-KEY` or Bearer credential from then
on; there is no need to log in again.
## Fetching your account with only an API key
A client that starts out knowing nothing but an API key (for example from
`DEVPLACE_API_KEY`) can fetch the account it belongs to with `GET /profile`:
```bash
curl -H "X-API-KEY: $DEVPLACE_API_KEY" \
-H "Accept: application/json" \
{{ base }}/profile
```
Every response that returns your personal API key returns your username and email
address alongside it, so the account is fully identified in one call: JSON
login/signup (`data.username`, `data.email`, `data.api_key`), the profile JSON
(`profile_user.username`, `profile_user.uid`, `email`, `api_key`), and
`POST /profile/regenerate-api-key` (`username`, `email`, `api_key`).
`GET /profile/{username}` with `Accept: application/json` reports the same picture
per profile: `profile_is_admin` tells whether the profile owner is an admin,
`viewer_is_admin` and `is_owner` describe the viewer, and `api_key` plus `email`
are filled in only for the profile's owner or an admin (`can_view_api_key`), null
for everyone else.
## 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
```
## Separate auth domains
Two surfaces deliberately do not take the credentials above. The DevRant-compatible
API under `/api/*` authenticates with its own `token_id` and `token_key` request
parameters (its `POST /api/users/auth-token` exchange does accept username or email
plus password); a personal API key, access token, Basic credentials, or session
cookie authenticate nothing there. WebSocket endpoints accept the session cookie or
an API key (header or one-time ticket, depending on the socket) but never HTTP Basic,
because browsers cannot set WebSocket headers.
## 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).