Skip to main content

Identity & Access API reference

Sign-in, sessions, MFA, passkeys and identity providers for your application’s end users.

Sign-in & Sessions

Signing your application's end users in and keeping them signed in: sign-up, sign-in, sign-out, passwordless magic links and one-time codes, passkeys, MFA enrolment, password reset, token refresh, whoami, and listing or revoking sessions.

The SDK surface is k9o.gate.*, with gate.signUp, gate.signIn, gate.signOut and gate.whoami at the root.

End users are a trust zone separate from operators, and in Native mode the tokens Gate issues scope every data query to the rows that user may see.

  • POSTSign Up/gate/signup

    Creates a new end-user account on the project using email and password credentials.

  • POSTSign In/gate/signin

    Authenticates a project-scoped end-user with email and password credentials and returns a Gate JWT plus refresh token on success.

  • POSTRefresh Session/gate/refresh

    Exchanges a refresh token for a new Gate access JWT and a new refresh token, extending the end user's session under the project's session policy.

  • POSTVerify Session/gate/verify-session

    Validates a Gate-issued end-user access JWT, confirming it is properly signed and within its TTL.

  • GETGet Current User/gate/whoami

    Returns the identity record of the currently authenticated end-user, including their eu_-prefixed ID, email, assigned roles (such as PROJECT_END_USER), and group memberships.

  • POSTSign Out/gate/signout

    Terminates the calling end-user's current project session by revoking the active refresh-token chain.

  • POSTRevoke All Sessions/auth/sessions/revoke-all

    Ends every live session of the calling end user in this project, on every device, this one included.

  • GETList Sessions/auth/sessions

    Returns a cursor-paginated list of active sessions for all users within the project.

  • POSTRequest OTP/gate/otp/request

    Sends a 6-digit one-time password to the end-user's email address, initiating a passwordless sign-in or step-up flow.

  • POSTVerify OTP/gate/otp/verify

    Verifies a one-time password previously sent to the end-user's email and, on success, issues a Gate JWT and refresh token.

  • POSTSend Magic Link/gate/magic-link/send

    Sends a single-use magic link to the end-user's email address to initiate passwordless sign-in.

  • POSTRedeem Magic Link/gate/magic-link/redeem

    Completes magic-link sign-in by verifying the token from the emailed link and issuing a Gate JWT and refresh token on success.

  • POSTBegin Passkey Registration/gate/passkeys/register/begin

    Initiates WebAuthn passkey registration for the authenticated end-user by returning a credential creation challenge.

  • POSTFinish Passkey Registration/gate/passkeys/register/finish

    Completes WebAuthn passkey registration by verifying the authenticator's attestation response and persisting the new pky_-prefixed credential.

  • POSTBegin Passkey Sign-In/gate/passkeys/signin/begin

    Initiates WebAuthn passkey authentication for an end-user by returning an assertion challenge.

  • POSTFinish Passkey Sign-In/gate/passkeys/signin/finish

    Completes WebAuthn passkey authentication by verifying the authenticator's assertion response, checking the signature counter for replay protection, and issuing a Gate JWT and refresh token on succ…

  • POSTEnroll TOTP/gate/mfa/totp/enroll

    Initiates TOTP (time-based one-time password) MFA enrollment for the authenticated end-user, returning a provisioning QR code and the raw TOTP secret for scanning with an authenticator app.

  • POSTConfirm TOTP/gate/mfa/totp/confirm

    Activates a pending TOTP MFA enrollment by verifying the first valid code from the authenticator app.

  • GETList MFA Methods/gate/mfa/methods

    Returns the active MFA factor enrollments for the authenticated end-user, including TOTP and WebAuthn factors.

  • DELETEDelete MFA Method/gate/mfa/methods/{methodId}

    Removes a specific enrolled MFA factor (identified by methodId) from the end-user's account, deactivating that factor for future sign-in challenges.

  • POSTRequest Password Reset/gate/password-reset/request

    Initiates a password reset flow for the specified email address by dispatching a single-use reset token.

  • POSTRedeem Password Reset/gate/password-reset/redeem

    Completes a password reset by accepting the single-use reset token and the new password.

  • POSTRedeem Invitation/gate/invitations/redeem

    Accepts a pending end-user invitation by presenting the single-use invitation token.

Federation

Letting your end users sign in with an outside identity provider: the OAuth2, OIDC and SAML 2.0 providers a project configures, the authorize and callback hops a browser or provider calls during sign-in, and the project's SAML service-provider metadata.

Federation for your own operators is configured separately, under Identity Providers.

  • POSTCreate Identity Provider/identity-providers

    Creates a new end-user federation provider configuration for the project.

  • GETList Identity Providers/identity-providers

    Returns the paginated list of end-user federation provider configurations attached to the project.

  • GETGet Identity Provider/identity-providers/{epcId}

    Retrieves a single end-user federation provider configuration.

  • PATCHUpdate Identity Provider/identity-providers/{epcId}

    Partially updates a project-scoped end-user federation provider configuration.

  • DELETEDelete Identity Provider/identity-providers/{epcId}

    Deletes a project-scoped end-user federation provider configuration.

  • POSTStart IdP Sign-In/gate/idp/{provider}/authorize

    Starts a redirect sign-in for an end user of this project.

  • GETReceive OAuth Callback/gate/idp/{provider}/callback

    Receives the authorization code and state from the identity provider after an end user authenticates.

  • POSTReceive SAML Callback/gate/saml/callback

    Receives the SAML 2.0 SAMLResponse and RelayState from the identity provider after a sign-in started at authorize.

Auth Settings

How your project's sign-in is configured: the JWKS that verifies the tokens Gate issues, the end-user session policy, service tokens, allowed origins and sign-in flows.

Changes apply to every end user of the project.

  • GETGet JWKS/auth/jwks

    Returns the public JSON Web Key Set used to verify bearer JWTs issued for this project.