auth
22 endpoints
post /auth/change-password
Change password
Requires authentication
Changes the authenticated user's password.
Request body: dto.ChangePasswordRequest
| Name | Type | Required | Description |
|---|---|---|---|
| currentPassword | string | yes | |
| newPassword | string | yes |
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
| Name | Type | Required | Description |
|---|---|---|---|
| code | string | no |
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
| Name | Type | Required | Description |
|---|---|---|---|
| string | yes |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | integer | yes | Identity 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
| Name | Type | Required | Description |
|---|---|---|---|
| string | yes | ||
| password | string | yes |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| provider | path | string | yes | google or github |
| code | query | string | no | Authorization code |
| state | query | string | no | Opaque 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| provider | path | string | yes | google or github |
| redirect | query | string | no | Same-origin path to land on afterwards, or the literal \ |
| invite | query | string | no | Org 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
| Name | Type | Required | Description |
|---|---|---|---|
| ticket | string | no |
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
| Name | Type | Required | Description |
|---|---|---|---|
| refreshToken | string | no |
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
| Name | Type | Required | Description |
|---|---|---|---|
| displayName | string | no | DisplayName 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). |
| string | yes | ||
| inviteToken | string | no | |
| orgName | string | no | |
| password | string | yes |
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
| Name | Type | Required | Description |
|---|---|---|---|
| string | no |
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
| Name | Type | Required | Description |
|---|---|---|---|
| newPassword | string | yes | |
| token | string | yes |
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
| Name | Type | Required | Description |
|---|---|---|---|
| expiresInDays | integer | no | |
| name | string | no |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | integer | yes | Token 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
| Name | Type | Required | Description |
|---|---|---|---|
| code | string | no | |
| string | no |
Responses
- 200 OK · object
- 400 Bad Request · apimodel.ErrorEnvelope
- 401 Unauthorized · apimodel.ErrorEnvelope