Your account

The signed-in person: their password, second factors, sessions and linked identities.

GET /v1/me

Current principal, roles, and permissions.

kind is user, key or agent. permissions lists the permissions the principal holds in at least one environment; assignments say which. An agent key also reports onBehalfOf, the user it acts for, and never has more access than that user. mustChangePassword is true for a user who has to choose a new password first; mfaEnrolmentRequired for one who has to set up MFA first. A user's password says whether they have one: false for a user who signs in only through a provider, who has no password to change and no MFA in reportd.

Responses

Status	Description	Body
200	Principal
429	The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.	object

POST /v1/me/password

Change the signed-in user's own password.

Needs the current password. The new one has at least 10 characters and isn't the username. Clears mustChangePassword and ends the user's other sessions; this one stays. Login sessions only, not API keys.

Request body (application/json)

Field	Type	Required	Description
currentPassword	string	yes
newPassword	string	yes

Responses

Status	Description	Body
200	The principal, without mustChangePassword
400	The new password is too short, is the username, or is the current one; or the user has no password (they sign in through a provider)
403	The current password is wrong (wrong-password)
429	The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.	object

GET /v1/me/mfa

The signed-in user's second factors.

{totp, passkeys: [{id, name, createdAt, lastUsedAt}], recoveryCodesLeft, required, passkeysAvailable, passkeysOff?}. passkeysAvailable is false when publicURL can't be the passkeys' relying party, and passkeysOff says why: no-public-url (unset), ip-address (its host is an IP address, which browsers refuse; localhost works) or public-url (anything else; the log says what). required is true when auth.mfa says this user must have MFA. Every change under /v1/me/mfa needs the user's current password in the body (password), is throttled as a sign-in is (429), and ends the user's other sessions. A wrong password is 403 wrong-password. The first factor a user adds comes with 10 recovery codes, answered once as recoveryCodes. Changes answer {mfa, principal, recoveryCodes?}.

Responses

Status	Description	Body
200	The user's factors
400	Not a signed-in user (keys have no MFA)
429	The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.	object

POST /v1/me/mfa/totp

Start setting up an authenticator app.

Answers {secret (base32), otpauthUrl, qrSvg, expiresIn}. The secret waits 10 minutes for POST /v1/me/mfa/totp/confirm. Starting again replaces it.

Request body (application/json)

Field	Type	Required	Description
password	string	yes

Responses

Status	Description	Body
200	The secret, as text, a URL and a QR code
403	The password is wrong (wrong-password)
429	Too many failed attempts, or the write rate limit; Retry-After says how many seconds to wait

DELETE /v1/me/mfa/totp

Turn the authenticator app off.

When it was the last factor, the recovery codes go too. A user who must have MFA can't remove their last factor (409 mfa-required).

Request body (application/json)

Field	Type	Required	Description
password	string	yes

Responses

Status	Description	Body
200	Turned off
403	The password is wrong (wrong-password)
404	The user has no authenticator app
409	It is the last factor and MFA is required (mfa-required)
429	The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.	object

POST /v1/me/mfa/totp/confirm

Turn the authenticator app on with its first code.

Request body (application/json)

Field	Type	Required	Description
password	string	yes
code	string	yes

Responses

Status	Description	Body
200	On; recoveryCodes when it is the user's first factor
400	The code is wrong (wrong-code)
403	The password is wrong (wrong-password)
409	No setup in progress, or it ran out (no-enrolment)
429	The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.	object

POST /v1/me/mfa/passkeys/options

Start adding a passkey.

Answers {publicKey: PublicKeyCredentialCreationOptions}, for navigator.credentials.create. Attestation is none; user verification and resident keys are preferred. The ceremony waits 10 minutes for POST /v1/me/mfa/passkeys.

Request body (application/json)

Field	Type	Required	Description
password	string	yes

Responses

Status	Description	Body
200	The creation options
403	The password is wrong (wrong-password)
409	Passkeys are off without publicURL (passkeys-off)
429	The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.	object

POST /v1/me/mfa/passkeys

Add the passkey just made.

credential is the browser's PublicKeyCredential, as JSON. name (at most 64 characters) shows in the list; empty is "Passkey".

Request body (application/json)

Field	Type	Required	Description
password	string	yes
name	string
credential	object	yes

Responses

Status	Description	Body
200	Added; recoveryCodes when it is the user's first factor
400	The credential doesn't check out (invalid-passkey)
403	The password is wrong (wrong-password)
409	No ceremony in progress, or it ran out (no-enrolment), or the passkey is added already
429	The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.	object

DELETE /v1/me/mfa/passkeys/{id}

Remove one of the user's passkeys.

As DELETE /v1/me/mfa/totp, for one passkey.

Parameters

Name	In	Type	Required	Description
id	path	string	yes

Request body (application/json)

Field	Type	Required	Description
password	string	yes

Responses

Status	Description	Body
200	Removed
403	The password is wrong (wrong-password)
404	The user has no such passkey
409	It is the last factor and MFA is required (mfa-required)
429	The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.	object

POST /v1/me/mfa/recovery-codes

Make new recovery codes.

The 10 new codes replace the old ones and are answered once.

Request body (application/json)

Field	Type	Required	Description
password	string	yes

Responses

Status	Description	Body
200
400	The user has no second factor yet
403	The password is wrong (wrong-password)
429	The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.	object

GET /v1/me/sessions

The signed-in user's sessions.

{sessions: [Session]}, the most recently used first, with the one this request uses marked current. A session's lastUsed is written at most once a minute. Sessions from before sessions had detail have null created and lastUsed and empty method, userAgent and address. Only a user signed in with a session has sessions (400 for a key).

Responses

Status	Description	Body
200	The sessions	object
400	Not a user signed in with a session
429	The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.	object

200 body (application/json)

Field	Type	Required	Description
sessions	array of Session

DELETE /v1/me/sessions

End the signed-in user's other sessions.

Needs ?others=true: ends every session of the user's but this one, on every node, and wipes the viewer sessions made under them. Each is audited as user.sign-out <name> (session <id>). Answers {ended}.

Parameters

Name	In	Type	Required	Description
others	query	true	yes

Responses

Status	Description	Body
200
400	Without ?others=true, or not a user signed in with a session
429	The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.	object

DELETE /v1/me/sessions/{id}

End one of the signed-in user's sessions.

Ends the session at once, on every node, and wipes the viewer sessions made under it; audited as user.sign-out <name> (session <id>). Ending the current one signs this browser out, as POST /v1/logout does.

Parameters

Name	In	Type	Required	Description
id	path	string	yes

Responses

Status	Description	Body
204	Ended
400	Not a user signed in with a session
404	The user has no session with this id
429	The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.	object

POST /v1/me/identities/{provider}

Start linking another OIDC or SAML identity to the signed-in user.

Starts the provider's sign-in flow with the user in the sealed rf_oidc or rf_saml cookie and answers {url}, the provider's authorization URL or the IdP's HTTP-Redirect URL, for the page to navigate to. The callback (or, for SAML, the ACS and then /v1/auth/saml/{provider}/link) links the identity to this user, if the browser is still signed in as them, and returns to next; it signs no one in. A user has one identity per provider, and an identity belongs to one user (else signInError=failed). A SAML IdP that takes only HTTP-POST can't be linked this way (400).

Parameters

Name	In	Type	Required	Description
provider	path	string	yes
next	query	string

Responses

Status	Description	Body
200
400	Not a signed-in user (keys have no identities)
404	No such provider
429	The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.	object
503	The provider isn't available yet

DELETE /v1/me/identities/{provider}

Unlink one of the signed-in user's identities.

Refused (409) when it is the user's only way to sign in.

Parameters

Name	In	Type	Required	Description
provider	path	string	yes

Responses

Status	Description	Body
204	Unlinked
404	The user has no identity from this provider
409	It is the user's only way to sign in
429	The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class.	object