Skip to main content
Ayase Quart uses bearer token authentication for API access. The application supports two authentication modes: cookie-based authentication for web requests and bearer token authentication for API requests.

​
Authentication overview

API authentication

Bearer tokens for programmatic access

Web authentication

Cookie-based sessions for browser access

​
Obtaining a bearer token

To access protected API endpoints, you must first obtain a bearer token by authenticating with your username and password.

​
Login endpoint

POST /api/v1/login
The login endpoint path can be customized in your configuration file under app.login_endpoint. The default is /api/v1/login.
Request body:
​
username
string
required
Your username
​
password
string
required
Your password
Rate limit: 3 requests per day per IP Example request: 
curl -X POST https://your-domain.com/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_username",
    "password": "your_password"
  }'
Response:
​
token
string | null
Bearer token for authentication (null on error)
​
error
string | null
Error message if authentication failed (null on success)
Success response (200): 
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "error": null
}
Error responses: 
{
  "token": null,
  "error": "Bad request"
}
Occurs when username or password is empty after stripping whitespace.
{
  "token": null,
  "error": "Bad credentials"
}
Occurs when the username/password combination is invalid.

​
Using bearer tokens

Once you have a bearer token, include it in the Authorization header of your API requests.

​
Authorization header format

Authorization: bearer YOUR_TOKEN
The authorization scheme must be lowercase bearer (not Bearer). The token validation checks for the lowercase format.
Example authenticated request: 
curl https://your-domain.com/api/v1/reports?public_access=v&mod_status=o \
  -H "Authorization: bearer YOUR_TOKEN"

​
Token validation errors

When making authenticated requests, you may encounter these errors: 
{
  "error": "Missing Authorization header"
}
The request did not include an Authorization header.
{
  "error": "Authorization header should be \"bearer <token>\""
}
The Authorization header is not in the correct format. Make sure it starts with bearer (lowercase, with a space).
{
  "error": "Empty token"
}
The Authorization header was provided but the token value is empty.
{
  "error": "Bad token"
}
The token is invalid, expired, or has been invalidated.
{
  "error": "User not active"
}
The user account has been deactivated.
{
  "error": "User not permitted"
}
The user does not have the required permissions for the requested operation.
{
  "error": "User not admin"
}
The endpoint requires admin privileges.

​
Token lifetime

Tokens have a configurable lifetime set in your application’s configuration: 
[moderation.auth]
bearer_duration = 3600  # Token lifetime in seconds (1 hour)
After the token expires, you must obtain a new token by logging in again.
There is no token logout or revocation endpoint. To invalidate all tokens before their expiration, the application’s secret key must be changed in the configuration.

​
Authentication decorators

The API uses several authentication and authorization decorators to protect endpoints:
1

login_api_usr_required

Validates the bearer token and extracts the user ID. Returns 400/401 errors if the token is missing or invalid.Used by: All protected API endpoints
2

require_api_usr_is_active

Ensures the authenticated user’s account is active. Returns 401 if the user is inactive.Used by: Most moderation and admin endpoints
3

require_api_usr_permissions

Checks that the user has specific permissions. Admin users automatically pass this check.Used by: Endpoints requiring specific permissions (e.g., report_read, user_create)
4

require_api_usr_is_admin

Requires the user to have admin privileges.Used by: High-privilege admin operations

​
Optional authentication

Some endpoints support optional authentication using the api_usr_authenticated decorator:
  • /api/v1/{board}/catalog.json
  • /api/v1/{board}/thread/{thread_id}.json
  • /api/v1/{board}/{page_num}.json
These endpoints work without authentication but provide additional functionality when authenticated. For example, authenticated moderators can view reported posts that are hidden from unauthenticated users. Example with optional authentication: 
# Returns data with reported posts filtered out
curl https://your-domain.com/api/v1/g/catalog.json

​
Security configuration

Authentication behavior is configured in the [moderation.auth] section of your config file: 
[moderation.auth]
# Bearer token settings (API authentication)
bearer_salt = "your-random-salt-here"
bearer_duration = 3600  # 1 hour

# Cookie settings (web authentication)
cookie_name = "ayase_auth"
cookie_salt = "another-random-salt"
cookie_duration = 86400  # 24 hours
cookie_secure = true
cookie_http_only = true
cookie_samesite = "Lax"
Always use strong, unique salt values for both bearer and cookie authentication. Never use the default values in production.

​
Password security

User passwords are hashed using the scrypt algorithm with a 16-byte salt: 
# From user.py:190
def gen_pwd(password: str) -> str:
    return generate_password_hash(password, method='scrypt', salt_length=16)
Passwords are validated using constant-time comparison to prevent timing attacks: 
# From user.py:284
check_password_hash(user.password, password_candidate)

​
Best practices

Store tokens securely

Never expose tokens in URLs, logs, or client-side code

Use HTTPS

Always use HTTPS in production to protect tokens in transit

Rotate tokens regularly

Implement token refresh or re-authentication for long-running applications

Monitor rate limits

Track login attempts to avoid hitting the 3 requests/day limit

​
Troubleshooting

The login endpoint is limited to 3 requests per day. If you’re locked out:
  1. Wait 24 hours for the rate limit to reset
  2. Contact an administrator to adjust the rate limit configuration
  3. Check your application for authentication retry loops
Your token has likely expired. Check the bearer_duration configuration and implement token refresh logic in your application.
Ensure you’re using lowercase bearer (not Bearer) in the Authorization header:
Authorization: bearer YOUR_TOKEN
Not:
Authorization: Bearer YOUR_TOKEN
Check if the user account is active. Inactive users cannot access protected endpoints even with valid tokens and permissions.

API overview

View all available API endpoints

User management

Learn about managing users and permissions

Build docs developers (and LLMs) love

Get started for freeTalk to us