Skip to content

Sign in with username and password

POST
/auth/login

Signs in with a username and password. On success the response sets the user session cookie and returns the signed-in account. Each sign-in starts its own session, and GET /account/sessions lists them.

If the account uses two-factor authentication, send the current code, or one of the account’s recovery codes, as totp_code. Without it the server answers 401 with "error": "2fa_required", so you can ask for the code and send the request again.

Other failed sign-ins also return 401, with a short reason in error. A wrong username or password, an unknown provider and a locked account all give invalid credentials, so the response doesn’t reveal which of these happened. You may also see missing credentials, account is not approved, account has expired, invalid_2fa_code or email_not_verified. Repeated attempts from one IP address or for one username get 429 for a short while.

object
username
required
string
Example
admin
password
required
string format: password
provider

The identity provider to sign in with. Leave it out to use password, the built-in username and password sign-in. LDAP and SAML providers need a license feature that isn’t available today, so in practice password is the only one; GET /auth/providers lists what your instance has. A name that isn’t registered gets the same 401 as a wrong password.

string
Example
password
totp_code

The current 6-digit code from the person’s authenticator app, or one of their recovery codes (10 characters; the hyphen is optional). Only needed when the account has two-factor authentication turned on. Each recovery code works once.

string

Signed in. The response sets the user session cookie and returns the account.

object
ref
required
integer format: int64
username
required
string
fullname
string
nullable
email
string
nullable
usergroup
integer format: int64
nullable
auth_method
required

How this request was signed in: session for the session cookie, token for an API token.

string
Allowed values: session token
language

The account’s preferred language, as a BCP 47 tag such as fr. Left out when the account hasn’t chosen one; the client can then follow the browser’s language.

string
theme

The account’s saved theme. system means follow the device’s light or dark setting. Left out when the account hasn’t chosen a theme, and the client then uses its own default.

string
Allowed values: "" light dark system
default_views

The account’s default browse settings: which feed tab opens first, the layout and the sort order. Left out when none are set. Treat them as starting values; a choice made on the device itself should win.

object
home_tab

The feed tab the browse page opens on. Empty or unset means latest.

string
Allowed values: "" latest following
browse_layout

The default browse layout, used when the operator has that layout turned on. Otherwise the app picks a default for the device from the layouts that are turned on.

string
Allowed values: "" grid masonry thumbnail list feed
browse_sort

The default sort order: newest posts first or oldest first. Empty or unset means newest.

string
Allowed values: "" newest oldest
feed_filters

The account’s feed filter settings, included only when a filter is turned on. GET /posts applies them itself; they’re here so a client can explain why the feed looks different.

object
show_restricted

Whether GET /posts keeps placeholders for assets you can’t see. It’s off by default: the feed drops those assets, and drops a post altogether when it had assets and none are left, unless you wrote it. Turn it on to keep every placeholder. Other endpoints, such as GET /posts/{id}, don’t use this setting.

boolean
browse_rail

How the person has arranged the team and tag shortcuts in the browse page’s rail: which they’ve hidden and which they’ve moved to the front. Left out when they haven’t changed anything. The server doesn’t use it to filter posts; it’s for the client to apply to the rail.

object
hidden_team_ids

Teams the person has hidden from the rail. Empty means none.

Array<string>
team_order

Followed teams the person has moved to the front, in that order. Other teams keep their usual order behind them. Empty means the server’s order.

Array<string>
hidden_tags

Followed tags the person has hidden from the rail. Hiding a tag isn’t unfollowing it: its posts still reach the following feed.

Array<string>
tag_order

Followed tags the person has moved to the front, in that order, with the rest behind them. Empty means the server’s order, most recently followed first.

Array<string>
mature_content

The account’s mature-content setting, included only when the person has opted in. Opting in isn’t enough on its own; mature_content_allowed explains the rest.

object
show

Whether the account has opted in to mature content. Absent or false means it hasn’t, which is the default.

boolean
mature_content_allowed
required

Whether this instance allows mature content. It’s the operator’s setting, not the account’s, and it’s always included. When it’s false, don’t offer the opt-in. Ordinarily an account sees mature content only when this is true and it has opted in. Two exceptions hold even when it’s false: people still see their own mature items, and system administrators see all of them. Neither exception overrides the usual permission checks.

boolean
capabilities

The account’s global capability codes, after its role, extra grants and revocations are combined. It’s the same list GET /auth/me/capabilities returns. Capabilities that apply only within a team aren’t included. Left out when capabilities_status is unavailable.

Array<string>
capabilities_status
required

Whether the capability list could be loaded for this response. resolved means capabilities is complete, and an empty list means the account has none. unavailable means the lookup failed: capabilities is left out and tells you nothing about the account. Treat that as an error you can retry, not as a lack of permission, and don’t show controls that need a capability until you have a resolved list.

string
Allowed values: resolved unavailable
impersonated_by

Present when an admin is acting as this account through POST /admin/users/{ref}/impersonate. It gives the admin’s ref and username, so a client can show who is really signed in.

object
ref
required
integer format: int64
username
required
string

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Unexpected server error

object
error
required

Human-readable error summary

string
Example
the request could not be completed

The named provider is registered on this instance, but this version can’t sign anyone in through it yet.

object
error
required

Human-readable error summary

string
Example
the request could not be completed