Create an account
POST /auth/register
Lets someone create their own account. It needs no authentication, but the operator must enable self-registration first. If it’s turned off, a valid request gets 403.
Send a username, email address and password. The username must be 3
to 32 characters, using only a-z, A-Z, 0-9, _ and -. The
password must meet the instance’s password policy. If a value breaks
those rules you get 400 with the reason in error, and if the
username or email address is already taken you get 409.
What happens next depends on whether the instance requires email
verification. If it does, you get 202 and the server tries to email
a verification link that works for an hour. The response is the same
even if sending fails, so offer POST /auth/resend-verification
when nothing arrives. The person can’t sign in until they’ve used
the link. If verification is off, you get 200 with the new account
and a user session cookie, so the person is signed in straight
away.
Repeated attempts from one IP address or for one email address get 429.
Request Body required
Section titled “Request Body required ”Details for the new account.
object
Must meet the instance’s password policy.
The person’s real name, if they want to give one. Signed-in visitors can see it on their profile; anonymous visitors can’t.
Responses
Section titled “ Responses ”Account created and signed in. You get this when the instance doesn’t require email verification; the response sets the user session cookie.
object
How this request was signed in: session for the session cookie, token for an API token.
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.
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.
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
The feed tab the browse page opens on. Empty or unset means
latest.
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.
The default sort order: newest posts first or oldest first.
Empty or unset means newest.
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
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.
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
Teams the person has hidden from the rail. Empty means none.
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.
Followed tags the person has hidden from the rail. Hiding a tag isn’t unfollowing it: its posts still reach the following feed.
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.
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
Whether the account has opted in to mature content. Absent or
false means it hasn’t, which is the default.
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.
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.
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.
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
Account created. The person has to verify their email address before they can sign in.
The account that was created. No session is started and no cookie is set.
object
A short message for the person, telling them to look for the verification email.
Malformed request
object
Human-readable error summary
Example
the request could not be completedSelf-registration is turned off on this instance.
object
Human-readable error summary
Example
the request could not be completedUsername or email already in use.
object
Human-readable error summary
Example
the request could not be completedToo many recent attempts from your IP address or for this email address. Wait a little and try again.
object
Human-readable error summary
Example
the request could not be completed