{% 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).