Skip to content

All resources

auth

22 endpoints

post /auth/change-password

Change password

Requires authentication

Changes the authenticated user's password.

Request body: dto.ChangePasswordRequest

NameTypeRequiredDescription
currentPasswordstringyes
newPasswordstringyes

Responses

  • 200 OK · object
  • 400 Bad Request · apimodel.ErrorEnvelope
  • 401 Unauthorized · apimodel.ErrorEnvelope

post /auth/email-verification

Confirm the caller's email address

Requires authentication

Checks the code mailed by POST /auth/email-verification/code. The account keeps its password and sessions. 400 VERIFICATION_CODE_INVALID for a wrong, expired, used or exhausted code. An address already confirmed answers 200 unchanged. Rate-limited per user.

Request body: apimodel.VerifyEmailRequest

NameTypeRequiredDescription
codestringno

Responses

  • 200 OK · object
  • 400 Bad Request · apimodel.ErrorEnvelope
  • 401 Unauthorized · apimodel.ErrorEnvelope
  • 429 Too Many Requests · apimodel.ErrorEnvelope

post /auth/email-verification/code

Mail a code that confirms the caller's email address

Requires authentication

Replaces any outstanding confirmation code of the signed-in account with a new one (10 minutes, 5 attempts) and mails it. 409 EMAIL_ALREADY_VERIFIED when the address is already confirmed. Rate-limited per user.

Responses

  • 200 OK · object
  • 401 Unauthorized · apimodel.ErrorEnvelope
  • 409 Conflict · apimodel.ErrorEnvelope
  • 429 Too Many Requests · apimodel.ErrorEnvelope

post /auth/forgot-password

Request a password reset

No authentication

Emails a reset link. Always returns success to prevent email enumeration.

Request body: dto.ForgotPasswordRequest

NameTypeRequiredDescription
emailstringyes

Responses

  • 200 OK · object
  • 400 Bad Request · apimodel.ErrorEnvelope

get /auth/identities

List linked social accounts

Requires authentication

Returns the caller's linked provider accounts for the settings page.

Responses

  • 200 OK · object
  • 401 Unauthorized · apimodel.ErrorEnvelope

delete /auth/identities/{id}

Disconnect a linked social account

Requires authentication

Removes one linked provider account. Refused when it is the caller's only remaining way to sign in.

Parameters

NameInTypeRequiredDescription
idpathintegeryesIdentity id

Responses

  • 200 OK · object
  • 404 Not Found · apimodel.ErrorEnvelope
  • 409 Conflict · apimodel.ErrorEnvelope

post /auth/login

Log in with email + password

No authentication

Exchanges credentials for a JWT bearer token plus the user object.

Request body: dto.LoginRequest

NameTypeRequiredDescription
emailstringyes
passwordstringyes

Responses

  • 200 OK · object
  • 400 Bad Request · apimodel.ErrorEnvelope
  • 401 Unauthorized · apimodel.ErrorEnvelope

post /auth/logout

Log out

Requires authentication

Invalidates the caller's bearer token AND every refresh-token chain that session backs, so a stored refresh token cannot revive it.

Responses

  • 200 OK · object
  • 401 Unauthorized · apimodel.ErrorEnvelope

get /auth/me

Get the current user

Requires authentication

Returns the authenticated user plus their role in the active org.

Responses

  • 200 OK · object
  • 401 Unauthorized · apimodel.ErrorEnvelope

get /auth/oauth/{provider}/callback

Provider redirect target

No authentication

Consumes the authorization code and redirects back into the app with a single-use handoff ticket. Registered as the callback URL at the provider.

Parameters

NameInTypeRequiredDescription
providerpathstringyesgoogle or github
codequerystringnoAuthorization code
statequerystringnoOpaque state minted by /start

Responses

  • 302 Found

get /auth/oauth/{provider}/start

Begin a social sign-in

No authentication

Redirects the browser to the provider's consent screen. Not an API call — navigate to it.

Parameters

NameInTypeRequiredDescription
providerpathstringyesgoogle or github
redirectquerystringnoSame-origin path to land on afterwards, or the literal \
invitequerystringnoOrg invite token to consume on signup

Responses

  • 302 Found

post /auth/oauth/exchange

Exchange a social sign-in ticket for a session

No authentication

Redeems the single-use ticket from the callback redirect. Same response shape as register/verify-code.

Request body: apimodel.OAuthExchangeRequest

NameTypeRequiredDescription
ticketstringno

Responses

  • 200 OK · object
  • 400 Bad Request · apimodel.ErrorEnvelope

get /auth/oauth/providers

List available social sign-in providers

No authentication

Returns the provider names this deployment has credentials for, so the sign-in screen only renders buttons that can work.

Responses

  • 200 OK · object

post /auth/refresh

Refresh the session token

Requires authentication

Issues a fresh token for the current session, extending it by a full expiry window.

Responses

  • 200 OK · object
  • 401 Unauthorized · apimodel.ErrorEnvelope

post /auth/refresh-token

Redeem a refresh token for a new session

No authentication

Public. Exchanges a refresh token for a fresh access token plus its successor refresh token (rotation). Presenting an already-spent token destroys the whole chain — it is treated as a leak.

Request body: apimodel.RefreshTokenRequest

NameTypeRequiredDescription
refreshTokenstringno

Responses

  • 200 OK · object
  • 400 Bad Request · apimodel.ErrorEnvelope
  • 401 Unauthorized · apimodel.ErrorEnvelope

post /auth/register

Register a new user

No authentication

Creates a user. With an inviteToken the user joins the inviting org; otherwise a new org is created with the user as owner.

Request body: dto.RegisterRequest

NameTypeRequiredDescription
displayNamestringnoDisplayName is the person's own name, and it is OPTIONAL. Optional because requiring it would break every existing caller — the e2e suite, the MCP onboarding flow and the web sign-up form all post without it — and because a name is a courtesy to teammates, not a credential. Omitting it leaves users.display_name = "" and the reader falls back to the email's local part (domain.User.DisplayLabel), which is what happened before this field existed. Bounded at 80 to match ck_users_display_name_len (migration 0049).
emailstringyes
inviteTokenstringno
orgNamestringno
passwordstringyes

Responses

  • 200 OK · object
  • 400 Bad Request · apimodel.ErrorEnvelope
  • 409 Conflict · apimodel.ErrorEnvelope

post /auth/request-code

Request a passwordless login code

No authentication

Emails a 6-digit login code. Always returns {sent:true} — never reveals whether the email has an account.

Request body: apimodel.RequestCodeRequest

NameTypeRequiredDescription
emailstringno

Responses

  • 200 OK · object
  • 400 Bad Request · apimodel.ErrorEnvelope

post /auth/reset-password

Reset a password with a token

No authentication

Sets a new password given a valid reset token.

Request body: dto.ResetPasswordRequest

NameTypeRequiredDescription
newPasswordstringyes
tokenstringyes

Responses

  • 200 OK · object
  • 400 Bad Request · apimodel.ErrorEnvelope

post /auth/token

Create an API token

Requires authentication

Mints a personal API token scoped to the caller's active org. The raw token is returned once.

Request body: apimodel.CreateAPITokenRequest

NameTypeRequiredDescription
expiresInDaysintegerno
namestringno

Responses

  • 201 Created · object
  • 400 Bad Request · apimodel.ErrorEnvelope
  • 401 Unauthorized · apimodel.ErrorEnvelope

get /auth/tokens

List API tokens

Requires authentication

Returns the caller's API tokens (safe projection — never the raw token or hash).

Responses

  • 200 OK · object
  • 401 Unauthorized · apimodel.ErrorEnvelope

delete /auth/tokens/{id}

Delete an API token

Requires authentication

Revokes one of the caller's API tokens.

Parameters

NameInTypeRequiredDescription
idpathintegeryesToken id

Responses

  • 200 OK · object
  • 400 Bad Request · apimodel.ErrorEnvelope
  • 401 Unauthorized · apimodel.ErrorEnvelope

post /auth/verify-code

Verify a passwordless login code

No authentication

Exchanges an emailed 6-digit code for a session. First-time emails get an account + default org. Same shape as register.

Request body: apimodel.VerifyCodeRequest

NameTypeRequiredDescription
codestringno
emailstringno

Responses

  • 200 OK · object
  • 400 Bad Request · apimodel.ErrorEnvelope
  • 401 Unauthorized · apimodel.ErrorEnvelope