Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tudoumono/Sherpa/llms.txt

Use this file to discover all available pages before exploring further.

Sherpa authenticates API clients using an HttpOnly session cookie named sherpa_session. After a successful login the server sets this cookie and subsequent requests must include it. The server validates the cookie on every protected endpoint, looks up the session in PostgreSQL, and resolves the caller’s uid and role before processing the request.

​
Auth Modes

Sherpa has two authentication modes. The active mode is determined at startup from environment variables.

Compatibility mode (default)

When SHERPA_AUTH_ENABLED is not set, all requests are treated as coming from a synthetic admin user. No cookie is checked. This is the default for local development and CI pipelines — it means existing tests and scripts work without any login step.Force compatibility mode at any time with SHERPA_AUTH_DISABLED=1, even if SHERPA_AUTH_ENABLED=1 is present in the environment.

Auth mode

Set SHERPA_AUTH_ENABLED=1 to require authentication. Every non-public endpoint checks the sherpa_session cookie. An unauthenticated request returns 401. Admin-only endpoints additionally require role = admin and return 403 for regular users.
In compatibility mode the server never reads or validates any cookie. You can call every endpoint — including admin endpoints — from curl without any -b flag. Do not run in compatibility mode in production.

​
POST /auth/login

Log in with a username (uid) and password. On success, the server creates a session in PostgreSQL, sets the sherpa_session cookie, and returns the caller’s uid.

​
Request body

​
username
string
required
The user’s uid. Must match the slug pattern ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$.
​
password
string
required
The user’s password in plain text. Transmitted over HTTPS; stored as a pbkdf2 hash server-side.

​
Responses

​
ok
boolean
true on success.
​
uid
string
The uid of the authenticated user.
Success (HTTP 200) 
{
  "ok": true,
  "uid": "alice"
}
Failure (HTTP 401) 
{
  "detail": "ユーザー名またはパスワードが正しくありません"
}
The same generic message is returned whether the user does not exist, the account is disabled, or the password is wrong — to prevent user enumeration.

​
Admin bootstrap

The very first login as admin is special. If no admin row exists in the database, the server checks whether SHERPA_ADMIN_PASSWORD is set and whether the supplied password matches it. If it does, the admin account is created on the fly (bootstrapped). If SHERPA_ADMIN_PASSWORD is not set, or the password does not match, a generic 401 is returned.
Never set SHERPA_ADMIN_PASSWORD to a weak or well-known value in production. This environment variable is the only credential protecting the initial admin account before any user management UI is available. Use a randomly generated password of at least 20 characters, store it in a secrets manager, and rotate or unset it after the admin account is confirmed.

​
GET /auth/me

Return the current user’s profile. Useful for front-end applications to verify the session and display the logged-in user’s name and role.

​
Responses

​
uid
string
The authenticated user’s uid.
​
email
string | null
Email address, if set.
​
display_name
string | null
Human-readable display name, if set.
​
role
string
Either "admin" or "user".
Success (HTTP 200) 
{
  "uid": "alice",
  "email": "alice@example.com",
  "display_name": "Alice",
  "role": "user"
}
Unauthenticated (HTTP 401) 
{
  "detail": "ログインが必要です"
}

​
POST /auth/logout

Revoke the current session and clear the sherpa_session cookie. The session record is deleted from PostgreSQL so the token cannot be reused even if an attacker captures it after logout.

​
Responses

​
ok
boolean
Always true on a successful logout.
Success (HTTP 200) 
{
  "ok": true
}
Logout is always a success response — even if no cookie was present or the session had already expired.
PropertyValue
Namesherpa_session
HttpOnlyYes — not accessible from JavaScript
SameSiteLax
Path/
SecureSet when SHERPA_ENV is not dev, development, or empty
Max ageSHERPA_SESSION_DAYS × 86400 seconds (default: 7 days)
The cookie value is a random token generated by secrets.token_urlsafe(). Only the SHA-256 hash of this token is stored in PostgreSQL — the plain token never persists server-side. Configure session lifetime with the SHERPA_SESSION_DAYS environment variable (default 7): 
SHERPA_SESSION_DAYS=30   # extend sessions to 30 days

​
Using the API from the Command Line

The examples below use a cookie jar file (cookies.txt) to persist the session across requests. 
# Log in — the -c flag writes the Set-Cookie header to cookies.txt
curl -s -c cookies.txt \
  -X POST http://127.0.0.1:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "password": "s3cr3t"}' | jq .
# → {"ok": true, "uid": "alice"}

​
Full Login Flow

1

POST /auth/login

Send username and password as a JSON body. The server validates the credentials, creates a session, and sets the sherpa_session cookie in the Set-Cookie response header.
2

Include the cookie on every request

Your HTTP client must send the sherpa_session cookie on every subsequent request. Browsers do this automatically. CLI tools like curl need a cookie jar (-c / -b). Language SDKs should use a persistent CookieJar or Session object.
3

Check session with GET /auth/me

Optionally verify the session is active and retrieve the current user’s role before making role-sensitive requests.
4

POST /auth/logout when done

Revoke the session server-side and clear the cookie. Always log out on application shutdown or user sign-out to invalidate the token immediately rather than waiting for it to expire.

​
Error Reference

HTTP statusScenario
401No cookie present ("ログインが必要です") or session not found / expired ("セッションが無効です").
403Logged in but insufficient role — e.g., a user calling an admin-only endpoint ("管理者権限が必要です").
500Audit-log write failure during login. Sherpa is fail-closed: the session is revoked and a 500 is returned rather than issuing a cookie without an audit record.

Build docs developers (and LLMs) love

Get started for freeTalk to us