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 for the base URL, request
bodies, content negotiation, pagination, and status codes that every endpoint shares.

You are not logged in. Examples below use placeholders. Log in and
reload this page to see ready-to-copy examples with your own API key.

Your API key is a UUID shown on your profile page.
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 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:

curl -H "X-API-KEY: YOUR_API_KEY" \
  https://devplace.net/notifications

3. Bearer token#

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

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://devplace.net/notifications

4. HTTP Basic#

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

curl -u YOUR_USERNAME:YOUR_PASSWORD \
  https://devplace.net/notifications

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

curl -H "Authorization: Basic $(printf '%s' 'YOUR_USERNAME:YOUR_PASSWORD' | base64)" \
  https://devplace.net/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.

curl -X POST https://devplace.net/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email": "YOUR_EMAIL", "password": "YOUR_PASSWORD"}'

The response is an OAuth2-style JSON object:

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

Use the returned access_token as a Bearer token:

TOKEN="<access_token from above>"
curl -H "Authorization: Bearer $TOKEN" \
  https://devplace.net/notifications

Or with the X-API-KEY header:

curl -H "X-API-KEY: $TOKEN" \
  https://devplace.net/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 <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 for how to obtain one.

curl -H "Authorization: Bearer YOUR_DEVRANT_TOKEN_KEY" \
  https://devplace.net/notifications

Or with the X-API-KEY header:

curl -H "X-API-KEY: YOUR_DEVRANT_TOKEN_KEY" \
  https://devplace.net/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:

curl -X POST https://devplace.net/auth/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"email": "YOU@EXAMPLE.COM", "password": "YOUR_PASSWORD"}'

{
  "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:

curl -H "X-API-KEY: $DEVPLACE_API_KEY" \
  -H "Accept: application/json" \
  https://devplace.net/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:

curl -X POST -H "X-API-KEY: YOUR_API_KEY" \
  https://devplace.net/follow/SOME_USERNAME

Create a post:

curl -X POST -H "X-API-KEY: YOUR_API_KEY" \
  -d "topic=devlog" -d "title=Hello" -d "content=Posted from a script" \
  https://devplace.net/posts/create

With a DevRant auth token:

curl -X POST -H "Authorization: Bearer YOUR_DEVRANT_TOKEN_KEY" \
  -d "topic=devlog" -d "title=Hello" -d "content=Posted from a script" \
  https://devplace.net/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.