http-api.md

HTTP API reference

Every route the library serves when every built-in plugin is wired, mounted at /auth as the examples do. This file is generated by task docs:api from the operation list auth.New builds; do not edit it by hand, task check fails when it is stale. An app serves only the routes of the plugins it wires, and the OAuth routes exist once per configured provider (here google and github). The same routes with their input and output schemas are in openapi.json, an OpenAPI 3.1 document; an app serves its own with authhttp.OpenAPI.

Every mutation is a POST with a JSON body; every query is a GET with its input in the query string. A mutation sent with a session cookie must carry a trusted Origin header. The requirement column is what the request must have before the operation runs: public anyone, signed_in a session, fresh_sign_in a session created within the fresh window, pending_second_factor a session waiting for its second step. Errors come back as {"error":{"code":…,"message":…}} with the status of the code; the codes are listed in errors.

Method	Path	Requirement	Operation	Plugin
POST	/auth/account/delete	fresh_sign_in	core.account-delete	core
POST	/auth/account/delete/confirm	public	core.account-delete-confirm	core
GET	/auth/admin/all-sessions	signed_in	admin.all-sessions	admin
GET	/auth/admin/audit	signed_in	admin.audit	admin
POST	/auth/admin/ban	fresh_sign_in	admin.ban	admin
POST	/auth/admin/create-user	fresh_sign_in	admin.create-user	admin
POST	/auth/admin/disable-two-factor	fresh_sign_in	admin.disable-two-factor	admin
POST	/auth/admin/enable-two-factor	fresh_sign_in	admin.enable-two-factor	admin
POST	/auth/admin/has-permission	signed_in	admin.has-permission	admin
POST	/auth/admin/impersonate	fresh_sign_in	admin.impersonate	admin
POST	/auth/admin/remove-user	fresh_sign_in	admin.remove-user	admin
POST	/auth/admin/reset-two-factor	fresh_sign_in	admin.reset-two-factor	admin
POST	/auth/admin/revoke-session	fresh_sign_in	admin.revoke-session	admin
POST	/auth/admin/revoke-sessions	fresh_sign_in	admin.revoke-sessions	admin
GET	/auth/admin/search-users	signed_in	admin.search-users	admin
GET	/auth/admin/sessions	signed_in	admin.sessions	admin
POST	/auth/admin/set-admin	fresh_sign_in	admin.set-admin	admin
POST	/auth/admin/set-email	fresh_sign_in	admin.set-email	admin
POST	/auth/admin/set-password	fresh_sign_in	admin.set-password	admin
POST	/auth/admin/set-role	fresh_sign_in	admin.set-role	admin
POST	/auth/admin/stop-impersonating	signed_in	admin.stop-impersonating	admin
GET	/auth/admin/two-factor	signed_in	admin.two-factor	admin
POST	/auth/admin/unban	fresh_sign_in	admin.unban	admin
POST	/auth/admin/update-user	fresh_sign_in	admin.update-user	admin
GET	/auth/admin/user	signed_in	admin.user	admin
GET	/auth/admin/users	signed_in	admin.users	admin
POST	/auth/anonymous/delete	signed_in	anonymous.delete	anonymous
POST	/auth/anonymous/sign-in	public	anonymous.sign-in	anonymous
POST	/auth/apikey/create	fresh_sign_in	apikey.create	apikey
GET	/auth/apikey/get	signed_in	apikey.get	apikey
GET	/auth/apikey/list	signed_in	apikey.list	apikey
POST	/auth/apikey/revoke	signed_in	apikey.revoke	apikey
POST	/auth/apikey/update	fresh_sign_in	apikey.update	apikey
GET	/auth/audit/my-events	signed_in	audit.my-events	audit
GET	/auth/device-sessions	signed_in	core.device-sessions	core
POST	/auth/device-sessions/revoke	signed_in	core.device-sessions-revoke	core
POST	/auth/device-sessions/switch	signed_in	core.device-sessions-switch	core
POST	/auth/device/approve	signed_in	device.approve	device
POST	/auth/device/code	public	device.code	device
POST	/auth/device/deny	signed_in	device.deny	device
POST	/auth/device/token	public	device.token	device
GET	/auth/device/verify	public	device.verify	device
POST	/auth/email/add	signed_in	email.add	email
POST	/auth/email/change	fresh_sign_in	email.change	email
POST	/auth/email/check-code	public	email.check-code	email
POST	/auth/email/confirm-change	public	email.confirm-change	email
POST	/auth/email/confirm-change-code	signed_in	email.confirm-change-code	email
GET	/auth/email/list	signed_in	email.list	email
POST	/auth/email/make-primary	fresh_sign_in	email.make-primary	email
POST	/auth/email/remove	fresh_sign_in	email.remove	email
POST	/auth/email/resend	public	email.resend	email
POST	/auth/email/send-code	public	email.send-code	email
POST	/auth/email/sign-in-code	public	email.sign-in-code	email
POST	/auth/email/undo-change	public	email.undo-change	email
POST	/auth/email/verify	public	email.verify	email
POST	/auth/email/verify-code	public	email.verify-code	email
POST	/auth/emailchallenge/approve	public	emailchallenge.approve	emailchallenge
GET	/auth/emailchallenge/context	public	emailchallenge.context	emailchallenge
POST	/auth/emailchallenge/poll	public	emailchallenge.poll	emailchallenge
POST	/auth/emailchallenge/start	public	emailchallenge.start	emailchallenge
POST	/auth/emailchallenge/verify-otp	public	emailchallenge.verify-otp	emailchallenge
POST	/auth/handoff/generate	signed_in	handoff.generate	handoff
POST	/auth/handoff/verify	public	handoff.verify	handoff
POST	/auth/invite/activate	public	invite.activate	invite
POST	/auth/invite/cancel	signed_in	invite.cancel	invite
POST	/auth/invite/create	signed_in	invite.create	invite
GET	/auth/invite/get	public	invite.get	invite
GET	/auth/invite/list	signed_in	invite.list	invite
POST	/auth/invite/reject	signed_in	invite.reject	invite
GET	/auth/jwt/jwks	public	jwt.jwks	jwt
POST	/auth/jwt/template	signed_in	jwt.template	jwt
POST	/auth/jwt/token	signed_in	jwt.token	jwt
POST	/auth/ldap/sign-in	public	ldap.sign-in	ldap
POST	/auth/magiclink/send	public	magiclink.send	magiclink
POST	/auth/magiclink/sign-in	public	magiclink.sign-in	magiclink
GET	/auth/metadata/admin-get	signed_in	metadata.admin-get	metadata
POST	/auth/metadata/admin-update	fresh_sign_in	metadata.admin-update	metadata
GET	/auth/metadata/get	signed_in	metadata.get	metadata
POST	/auth/metadata/update	signed_in	metadata.update	metadata
POST	/auth/oauth/access-token	signed_in	oauth.access_token	oauth
GET	/auth/oauth/accounts	signed_in	oauth.accounts	oauth
GET	/auth/oauth/github/callback	public	oauth.github-callback	oauth
POST	/auth/oauth/github/id-token	public	oauth.github-id-token	oauth
POST	/auth/oauth/github/logout	signed_in	oauth.github-logout	oauth
GET	/auth/oauth/github/start	public	oauth.github-start	oauth
GET	/auth/oauth/google/callback	public	oauth.google-callback	oauth
POST	/auth/oauth/google/id-token	public	oauth.google-id-token	oauth
POST	/auth/oauth/google/logout	signed_in	oauth.google-logout	oauth
GET	/auth/oauth/google/start	public	oauth.google-start	oauth
POST	/auth/oauth/logout	signed_in	oauth.logout	oauth
GET	/auth/oauth/providers	public	oauth.providers	oauth
POST	/auth/oauth/reauthenticate	signed_in	oauth.reauthenticate	oauth
POST	/auth/oauth/reauthenticate-id-token	signed_in	oauth.reauthenticate-id-token	oauth
POST	/auth/oauth/unlink	fresh_sign_in	oauth.unlink	oauth
GET	/auth/oauthprovider/client	signed_in	oauthprovider.get_client	oauthprovider
GET	/auth/oauthprovider/clients	signed_in	oauthprovider.list_clients	oauthprovider
POST	/auth/oauthprovider/consent	signed_in	oauthprovider.consent	oauthprovider
GET	/auth/oauthprovider/consents	signed_in	oauthprovider.list_consents	oauthprovider
POST	/auth/oauthprovider/continue	signed_in	oauthprovider.continue	oauthprovider
POST	/auth/oauthprovider/create-client	fresh_sign_in	oauthprovider.create_client	oauthprovider
POST	/auth/oauthprovider/delete-client	signed_in	oauthprovider.delete_client	oauthprovider
GET	/auth/oauthprovider/get-consent	signed_in	oauthprovider.get_consent	oauthprovider
GET	/auth/oauthprovider/public-client	signed_in	oauthprovider.public_client	oauthprovider
POST	/auth/oauthprovider/public-client-prelogin	public	oauthprovider.public_client_prelogin	oauthprovider
POST	/auth/oauthprovider/revoke-consent	signed_in	oauthprovider.revoke_consent	oauthprovider
POST	/auth/oauthprovider/rotate-secret	fresh_sign_in	oauthprovider.rotate_secret	oauthprovider
POST	/auth/oauthprovider/update-client	fresh_sign_in	oauthprovider.update_client	oauthprovider
POST	/auth/oauthprovider/update-consent	signed_in	oauthprovider.update_consent	oauthprovider
POST	/auth/organization/accept	signed_in	organization.accept	organization
POST	/auth/organization/accept-suggestion	signed_in	organization.accept-suggestion	organization
GET	/auth/organization/active	signed_in	organization.active	organization
POST	/auth/organization/add-domain	signed_in	organization.add-domain	organization
POST	/auth/organization/add-team-member	signed_in	organization.add-team-member	organization
POST	/auth/organization/approve-membership-request	signed_in	organization.approve-membership-request	organization
POST	/auth/organization/cancel-invitation	signed_in	organization.cancel	organization
GET	/auth/organization/check-slug	signed_in	organization.check-slug	organization
POST	/auth/organization/create	signed_in	organization.create	organization
POST	/auth/organization/create-role	signed_in	organization.create-role	organization
POST	/auth/organization/create-team	signed_in	organization.create-team	organization
POST	/auth/organization/delete	signed_in	organization.delete	organization
POST	/auth/organization/delete-role	signed_in	organization.delete-role	organization
GET	/auth/organization/domain-suggestions	signed_in	organization.domain-suggestions	organization
GET	/auth/organization/get-full-organization	signed_in	organization.get-full	organization
GET	/auth/organization/get-organization	signed_in	organization.get	organization
GET	/auth/organization/get-role	signed_in	organization.get-role	organization
POST	/auth/organization/has-permission	signed_in	organization.has-permission	organization
GET	/auth/organization/invite	signed_in	organization.invitation	organization
POST	/auth/organization/invite	signed_in	organization.invite	organization
GET	/auth/organization/invites	signed_in	organization.invites	organization
GET	/auth/organization/list	signed_in	organization.list	organization
GET	/auth/organization/list-domains	signed_in	organization.list-domains	organization
GET	/auth/organization/list-invitations	signed_in	organization.list-invitations	organization
GET	/auth/organization/list-membership-requests	signed_in	organization.list-membership-requests	organization
GET	/auth/organization/list-roles	signed_in	organization.list-roles	organization
GET	/auth/organization/list-team-members	signed_in	organization.list-team-members	organization
GET	/auth/organization/list-teams	signed_in	organization.list-teams	organization
GET	/auth/organization/list-user-teams	signed_in	organization.list-user-teams	organization
GET	/auth/organization/members	signed_in	organization.members	organization
POST	/auth/organization/reject-invitation	signed_in	organization.reject	organization
POST	/auth/organization/reject-membership-request	signed_in	organization.reject-membership-request	organization
POST	/auth/organization/remove-domain	signed_in	organization.remove-domain	organization
POST	/auth/organization/remove-member	signed_in	organization.remove-member	organization
POST	/auth/organization/remove-team	signed_in	organization.remove-team	organization
POST	/auth/organization/remove-team-member	signed_in	organization.remove-team-member	organization
GET	/auth/organization/role	signed_in	organization.role	organization
POST	/auth/organization/set-active	signed_in	organization.set-active	organization
POST	/auth/organization/set-active-team	signed_in	organization.set-active-team	organization
POST	/auth/organization/set-role	signed_in	organization.set-role	organization
POST	/auth/organization/update	signed_in	organization.update	organization
POST	/auth/organization/update-domain	signed_in	organization.update-domain	organization
POST	/auth/organization/update-role	signed_in	organization.update-role	organization
POST	/auth/organization/update-team	signed_in	organization.update-team	organization
POST	/auth/organization/verify-domain	signed_in	organization.verify-domain	organization
GET	/auth/passkey/list	signed_in	passkey.list	passkey
POST	/auth/passkey/login-begin	public	passkey.login-begin	passkey
POST	/auth/passkey/login-finish	public	passkey.login-finish	passkey
POST	/auth/passkey/reauthenticate-begin	signed_in	passkey.reauthenticate-begin	passkey
POST	/auth/passkey/reauthenticate-finish	signed_in	passkey.reauthenticate-finish	passkey
POST	/auth/passkey/register-begin	fresh_sign_in	passkey.register-begin	passkey
POST	/auth/passkey/register-finish	fresh_sign_in	passkey.register-finish	passkey
POST	/auth/passkey/remove	fresh_sign_in	passkey.remove	passkey
POST	/auth/passkey/rename	signed_in	passkey.rename	passkey
POST	/auth/passkey/sign-up-begin	public	passkey.sign-up-begin	passkey
POST	/auth/passkey/sign-up-finish	public	passkey.sign-up-finish	passkey
POST	/auth/password/change	fresh_sign_in	password.change	password
POST	/auth/password/forgot	public	password.forgot	password
POST	/auth/password/reauthenticate	signed_in	password.reauthenticate	password
POST	/auth/password/reset	public	password.reset	password
POST	/auth/password/sign-in	public	password.sign-in	password
POST	/auth/password/sign-up	public	password.sign-up	password
POST	/auth/password/verify	signed_in	password.verify	password
POST	/auth/phone/add	signed_in	phone.add	phone
POST	/auth/phone/change	fresh_sign_in	phone.change	phone
POST	/auth/phone/confirm-change	signed_in	phone.confirm-change	phone
GET	/auth/phone/list	signed_in	phone.list	phone
POST	/auth/phone/make-primary	fresh_sign_in	phone.make-primary	phone
POST	/auth/phone/remove	fresh_sign_in	phone.remove	phone
POST	/auth/phone/resend	signed_in	phone.resend	phone
POST	/auth/phone/send-code	public	phone.send-code	phone
POST	/auth/phone/sign-in	public	phone.sign-in	phone
POST	/auth/phone/verify	signed_in	phone.verify	phone
POST	/auth/pow/challenge	public	pow.challenge	pow
POST	/auth/profile	signed_in	core.profile	core
GET	/auth/referral/dashboard	signed_in	referral.dashboard	referral
GET	/auth/referral/list	signed_in	referral.list	referral
POST	/auth/referral/remember	public	referral.remember	referral
GET	/auth/session	signed_in	core.session	core
POST	/auth/session/refresh	signed_in	core.session-refresh	core
GET	/auth/sessions	signed_in	core.sessions	core
POST	/auth/sessions/revoke	signed_in	core.sessions-revoke	core
POST	/auth/sign-out	signed_in	core.sign-out	core
POST	/auth/sign-out-all	signed_in	core.sign-out-all	core
POST	/auth/siwe/link	fresh_sign_in	siwe.link	siwe
POST	/auth/siwe/nonce	public	siwe.nonce	siwe
POST	/auth/siwe/unlink	fresh_sign_in	siwe.unlink	siwe
POST	/auth/siwe/verify	public	siwe.verify	siwe
GET	/auth/siwe/wallets	signed_in	siwe.wallets	siwe
POST	/auth/terms/accept	signed_in	terms.accept	terms
POST	/auth/twofactor/check	signed_in	twofactor.check	twofactor
POST	/auth/twofactor/confirm	fresh_sign_in	twofactor.confirm	twofactor
GET	/auth/twofactor/devices	signed_in	twofactor.devices	twofactor
POST	/auth/twofactor/devices/forget	fresh_sign_in	twofactor.forget-device	twofactor
POST	/auth/twofactor/disable	fresh_sign_in	twofactor.disable	twofactor
POST	/auth/twofactor/enroll	fresh_sign_in	twofactor.enroll	twofactor
POST	/auth/twofactor/reauthenticate	signed_in	twofactor.reauthenticate	twofactor
POST	/auth/twofactor/recovery-codes	fresh_sign_in	twofactor.recovery-codes	twofactor
POST	/auth/twofactor/recovery-codes/view	fresh_sign_in	twofactor.view-recovery-codes	twofactor
POST	/auth/twofactor/remove-factor	fresh_sign_in	twofactor.remove-factor	twofactor
POST	/auth/twofactor/security-key/challenge	signed_in_or_pending	twofactor.security-key-challenge	twofactor
POST	/auth/twofactor/security-key/register-begin	fresh_sign_in	twofactor.security-key-register-begin	twofactor
POST	/auth/twofactor/security-key/register-finish	fresh_sign_in	twofactor.security-key-register-finish	twofactor
POST	/auth/twofactor/send	signed_in_or_pending	twofactor.send	twofactor
GET	/auth/twofactor/status	signed_in_or_pending	twofactor.status	twofactor
POST	/auth/twofactor/totp-uri	fresh_sign_in	twofactor.totp-uri	twofactor
POST	/auth/twofactor/verify	pending_second_factor	twofactor.verify	twofactor
GET	/auth/username/available	public	username.available	username
POST	/auth/username/set	signed_in	username.set	username

Read the plugin guides in plugins for each flow end to end, and each plugin's README for its options, tables and errors.