auth

The auth domain has 9 actions. On the meta surface they are all reached through arcane_auth; on the individual surface each one is its own tool; on the dynamic surface run them with arcane_execute_action and the canonical ID.

Summary

Action	Title	Kind
auth.avatar_delete	Delete own avatar	destructive
auth.avatar_upload	Upload own avatar	write
auth.change_password	Change password	destructive
auth.login	Login	write
auth.logout	Logout	write
auth.logout_other_sessions	Logout all other sessions	destructive
auth.me	Get current user	read
auth.profile_update	Update own profile	write
auth.refresh	Refresh token	write

Actions

auth.avatar_delete

Delete own avatar

Remove the current user’s custom profile picture, reverting to the default avatar.

• Kind: destructive — requires confirm: true
• Required parameters: none
• Meta tool: arcane_auth with "action": "avatar_delete"
• Individual tool: arcane_auth_avatar_delete
• Arcane route: DELETE /api/auth/me/avatar
• Operation ID: delete-my-avatar
• Usage: Removes the caller’s custom profile picture so the default avatar is shown, and succeeds even when none was set. Returns the updated user without avatarUrl. To replace the picture use auth.avatar_upload directly.
• Related actions: auth.avatar_upload, user.avatar

auth.avatar_upload

Upload own avatar

Upload a custom profile picture (PNG, JPEG or WebP). Replaces any existing avatar.

• Kind: write
• Required parameters: none
• Meta tool: arcane_auth with "action": "avatar_upload"
• Individual tool: arcane_auth_avatar_upload
• Arcane route: POST /api/auth/me/avatar
• Operation ID: upload-my-avatar
• Usage: Sets the caller’s profile picture, replacing any existing one. file is a file object (filename, contentBase64) holding a PNG, JPEG or WebP no larger than the avatarMaxUploadSizeMb setting (default 2 MB). An opaque PNG may be stored re-encoded as JPEG. Returns the updated user. Read the image back with user.avatar using the id from auth.me.
• Related actions: auth.avatar_delete, user.avatar, auth.me

auth.change_password

Change password

Change the current user’s password

• Kind: destructive — requires confirm: true
• Required parameters: newPassword
• Meta tool: arcane_auth with "action": "change_password"
• Individual tool: arcane_auth_change_password
• Arcane route: POST /api/auth/password
• Operation ID: change-password
• Usage: Changes the caller’s own password: currentPassword is required in practice, newPassword must satisfy the authPasswordPolicy setting (settings.get). A wrong currentPassword fails with 401. Clears requiresPasswordChange and revokes every other session of the account (with an API key, all of them). If this is the account in ARCANE_PASSWORD, update that setting or this server can no longer log in. To set another user’s password use user.update.
• Related actions: user.update, settings.get, auth.logout_other_sessions

auth.login

Login

Authenticate a user with username and password

• Kind: write
• Required parameters: password, username
• Meta tool: arcane_auth with "action": "login"
• Individual tool: arcane_auth_login
• Arcane route: POST /api/auth/login
• Operation ID: login
• Usage: Checks a username (or account email) and password (fails when local authentication is disabled) and returns status authenticated with token, refreshToken, expiresAt and user, or status mfa_required with mfa.transactionId: pass it to passkey.mfa_begin then passkey.mfa_finish, or to passkey.recovery_code_use. An authenticated login opens a new session but only returns its tokens. This server keeps using its own configured credentials. Rate limited to 5 calls per minute per client IP, a budget this server’s own session logins also use.
• Related actions: auth.refresh, passkey.mfa_begin, passkey.recovery_code_use, passkey.login_begin

auth.logout

Logout

Clear authentication session

• Kind: write
• Required parameters: none
• Meta tool: arcane_auth with "action": "logout"
• Individual tool: arcane_auth_logout
• Arcane route: POST /api/auth/logout
• Operation ID: logout
• Usage: Ends the session this server opened with ARCANE_USERNAME and ARCANE_PASSWORD (also when an API key is configured as well). The next call that needs a session logs in again. With only an API key there is no session: the call succeeds but ends nothing, unless refreshToken (from auth.login or auth.refresh) is given, which revokes that token’s session in any case (the refresh and __Secure-refresh cookie parameters are the browser’s way to send it). Returns a message. To revoke the account’s other sessions use auth.logout_other_sessions.
• Related actions: auth.logout_other_sessions, auth.login

auth.logout_other_sessions

Logout all other sessions

Revoke every session for the current user except the one making this request

• Kind: destructive — requires confirm: true
• Required parameters: none
• Meta tool: arcane_auth with "action": "logout_other_sessions"
• Individual tool: arcane_auth_logout_other_sessions
• Arcane route: POST /api/auth/sessions/logout-all
• Operation ID: logout-all-other-sessions
• Usage: Signs the caller’s account out everywhere else: every other session is revoked and its refresh token stops working. Called with an API key there is no current session, so every session of the key’s owner is revoked. API keys themselves keep working (revoke those with api_key.my_delete).
• Related actions: auth.logout, auth.change_password, api_key.my_list

auth.me

Get current user

Get the currently authenticated user’s information

• Kind: read
• Required parameters: none
• Meta tool: arcane_auth with "action": "me"
• Individual tool: arcane_auth_me
• Arcane route: GET /api/auth/me
• Operation ID: get-current-user
• Usage: The user behind this server’s credential (for a personal API key, the key’s owner): id, username, displayName, email, roleAssignments, permissionsByEnv (‘global’ covers every environment), requiresPasswordChange and avatarUrl. Needs no permission. Use it to learn your own userId or check what you may do. To read another user use user.get.
• Related actions: auth.profile_update, auth.change_password, user.get, api_key.my_list

auth.profile_update

Update own profile

Update the current user’s display name and email. Forbidden for OIDC-managed accounts.

• Kind: write
• Required parameters: none
• Meta tool: arcane_auth with "action": "profile_update"
• Individual tool: arcane_auth_profile_update
• Arcane route: PUT /api/auth/me/profile
• Operation ID: update-my-profile
• Usage: Edits the caller’s own profile. Only the fields sent change: displayName, email, locale, timeFormat (auto, 12h, 24h), fontSize (12-20) and preferences (merged field by field, e.g. themeMode, applicationTheme, accentColor, defaultLandingPage, while environmentColors replaces its whole map). OIDC accounts get 403 for displayName or email. Returns the updated user. To edit another user (or a username) use user.update.
• Related actions: auth.me, user.update

auth.refresh

Refresh token

Obtain a new access token using a refresh token

• Kind: write
• Required parameters: none
• Meta tool: arcane_auth with "action": "refresh"
• Individual tool: arcane_auth_refresh
• Arcane route: POST /api/auth/refresh
• Operation ID: refresh-token
• Usage: Exchanges a refreshToken from auth.login (or an earlier auth.refresh) for a new token and refreshToken. The refresh token rotates, so the one passed in stops working, and it fails with 401 once its session was revoked (auth.logout, auth.logout_other_sessions, auth.change_password) or when no refreshToken is given. The refresh and __Secure-refresh cookie parameters are how browsers send the same token, so pass refreshToken instead. Rate limited to 30 calls per minute per client IP.
• Related actions: auth.login