DevPlace Authentication: API Keys, Sessions, Bearer and Basic

The four interchangeable ways to authenticate any DevPlace request - session cookie, X-API-KEY header, Bearer token and HTTP Basic - plus the signup, login, logout and password-reset endpoints that issue and clear the session.

Signing a request: the four methods

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

Examples below are filled in with your account and your API key, ready to copy and paste.

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.

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

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

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

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.

Account endpoints: signup, login, logout, password reset

Create an account, sign in, recover your password, and log out. These are the only endpoints that set or clear the session cookie; every other request authenticates with the methods described in Authentication. The shared rules (content negotiation, pagination, status codes) live in Conventions and Errors.

Page vs. action

The GET endpoints render HTML sign-up, login, and password-reset forms; they also return the page data as JSON when requested with Accept: application/json (including page to distinguish the form type).

The POST endpoints are actions: they accept form fields, set or clear the session cookie, and return a 302 redirect (or the JSON envelope for JSON callers).

Sign-up requires a unique username and email plus a confirm_password that matches the password; you log in with your email and password. JSON callers receive validation errors as a 422 with the shape { "fields": {...}, "messages": [...] }.

GET /auth/signup - Sign up page

Render the registration form. Returns an HTML page.

Minimal role: Public

Sample response

{
  "page": "string",
  "next_url": "/path",
  "registration_closed": false,
  "sent": false,
  "token": "string",
  "errors": []
}

POST /auth/signup - Sign up

Create a new account. Sets the session cookie on success.

Minimal role: Public

Parameters

Signup is refused below the platform minimum age (moderationminimumage).

Accepting records the terms, privacy and activity-recording consents; third-party AI processing stays off until it is granted separately.

Sample response

{
  "ok": true,
  "redirect": "/feed",
  "data": {
    "username": "alice"
  }
}

GET /auth/login - Log in page

Render the login form. Returns an HTML page.

Minimal role: Public

Parameters

Sample response

{
  "page": "string",
  "next_url": "/path",
  "registration_closed": false,
  "sent": false,
  "token": "string",
  "errors": []
}

POST /auth/login - Log in

Authenticate with email and password. Sets the session cookie.

Minimal role: Public

Parameters

Sample response

{
  "ok": true,
  "redirect": "/feed",
  "data": null
}

GET /auth/forgot-password - Forgot password page

Render the forgot-password form. Returns an HTML page.

Minimal role: Public

Sample response

{
  "page": "string",
  "next_url": "/path",
  "registration_closed": false,
  "sent": false,
  "token": "string",
  "errors": []
}

POST /auth/forgot-password - Request password reset

Send a password-reset email with a one-time link.

Minimal role: Public

Parameters

Sample response

{
  "ok": true,
  "redirect": "/auth/forgot-password?sent=1",
  "data": null
}

GET /auth/reset-password/{token} - Reset password page

Render the password-reset form (only valid with a one-time token). Returns an HTML page.

Minimal role: Public

Parameters

Sample response

{
  "page": "string",
  "next_url": "/path",
  "registration_closed": false,
  "sent": false,
  "token": "string",
  "errors": []
}

POST /auth/reset-password/{token} - Reset password

Set a new password using a one-time reset token.

Minimal role: Public

Parameters

Sample response

{
  "ok": true,
  "redirect": "/auth/login",
  "data": null
}

GET /auth/logout - Log out

Clear the session cookie and redirect to the landing page.

Minimal role: Public

Sample response

{
  "ok": true,
  "redirect": "/",
  "data": null
}