---
title: "DevPlace Authentication: API Keys, Sessions, Bearer and Basic"
description: "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."
language: null
framework: null
category: authentication_authorization
tags:
  - devplace
  - api
  - http-api
  - authentication
  - api-key
  - session
  - bearer-token
  - http-basic
  - rest
  - automation
keywords:
  - devplace api key header X-API-KEY
  - devplace bearer token authentication
  - devplace session cookie login endpoint
  - devplace http basic auth username password
  - devplace regenerate api key
last_updated: 2026-08-12
difficulty: beginner
version: "DevPlace (devplace.net), documented 2026-08"
related:
  - conventions_and_errors.md
  - devrant_compatible_api.md
  - ../../core/security/secure_coding.md
  - ../../core/security/owasp_top_10.md
  - README.md
search_priority: high
status: published
---

# DevPlace Authentication: API Keys, Sessions, Bearer and Basic

## 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](conventions_and_errors.md) 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](https://devplace.net/profile/<your-username>).
You can regenerate it there at any time; the previous key stops working immediately.

The interactive panels throughout the [API reference](https://devplace.net/docs/#doc-index) 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: <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:

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

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

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

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

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

Use the returned `access_token` as a Bearer token:

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

Or with the `X-API-KEY` header:

```bash
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](devrant_compatible_api.md) for how to obtain one.

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

Or with the `X-API-KEY` header:

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

```bash
curl -X POST -H "X-API-KEY: <your-api-key>" \
  https://devplace.net/follow/SOME_USERNAME
```

Create a post:

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

```bash
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](conventions_and_errors.md).

## 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](#signing-a-request-the-four-methods). The shared rules (content
negotiation, pagination, status codes) live in [Conventions and Errors](conventions_and_errors.md).

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

```json
{
  "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**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `username` | form | string | yes | Username, 3-32 characters (letters, numbers, hyphens, underscores). |
| `email` | form | string | yes | Email address; must be unique and contain an @. |
| `password` | form | string | yes | Password, 6+ characters. |
| `confirm_password` | form | string | yes | Must match password. |
| `birth_date` | form | string | yes | Date of birth, DD/MM/YYYY or YYYY-MM-DD. Only the derived age band is stored; the date is discarded. |
| `accept_terms` | form | enum | yes | Acceptance of the Terms of Service and Community Guidelines. Allowed: 1. |

> Signup is refused below the platform minimum age (`moderation_minimum_age`).

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

**Sample response**

```json
{
  "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**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `next` | query | string | no | Redirect target after login. |

**Sample response**

```json
{
  "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**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `email` | form | string | yes | Your registered email. |
| `password` | form | string | yes | Your password. |
| `remember_me` | form | string | no | Send 'on' to extend the session to the remember-me lifetime. |
| `next` | form | string | no | Redirect target after login. |

**Sample response**

```json
{
  "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**

```json
{
  "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**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `email` | form | string | yes | Your registered email. |

**Sample response**

```json
{
  "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**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `token` | path | string | yes | The one-time reset token from the email. |

**Sample response**

```json
{
  "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**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `token` | path | string | yes | The one-time reset token from the email. |
| `password` | form | string | yes | New password, 6+ characters. |
| `confirm_password` | form | string | yes | Must match password. |

**Sample response**

```json
{
  "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**

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