Skip to main content
Password-based authentication uses email and password credentials. The typical new-user flow is: send an email verification → create the user account → sign in.

​
Send email verification


POST https://api-staging.knowledgestack.ai/v1/auth/pw/email_verification Send a verification email to the provided address. The email contains a token that you pass to the create user endpoint. This is the first step when registering a new password-based user.

​
Request body

​
email
string
required
The email address to verify. Must be a valid email format.

​
Response

Returns an EmailSentResponse on success.
​
email_id
string (uuid)
ID of the sent email message.

​
Example

curl -X POST https://api-staging.knowledgestack.ai/v1/auth/pw/email_verification \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

{
  "email_id": "3f2a1b4c-0000-0000-0000-000000000000"
}

​
Create user


POST https://api-staging.knowledgestack.ai/v1/auth/pw/user Create a new password-based user account. You must complete email verification first and supply the token from that email.

​
Request body

​
password
string
required
The user’s password. Minimum 8 characters.
​
email_token
string
required
The email verification token received from the verification email.
​
first_name
string
User’s first name (optional).
​
last_name
string
User’s last name (optional).

​
Response 201

Returns a UserResponse on success.
​
id
string (uuid)
User ID.
​
email
string
User’s email address.
​
first_name
string
First name.
​
last_name
string
Last name.
​
idp_type
string
Identity provider type. One of PASSWORD, GOOGLE, TENANT.
​
current_tenant_id
string (uuid)
The tenant the user is currently scoped to.
​
current_tenant_role
string
The user’s role in the current tenant.
​
default_tenant_id
string (uuid)
The tenant the user is signed into by default.

​
Example

curl -X POST https://api-staging.knowledgestack.ai/v1/auth/pw/user \
  -H "Content-Type: application/json" \
  -d '{
    "password": "s3cur3p@ss",
    "email_token": "<token-from-email>",
    "first_name": "Ada",
    "last_name": "Lovelace"
  }'

​
Sign in


POST https://api-staging.knowledgestack.ai/v1/auth/pw/signin Validate email and password credentials. On success, the server sets a ks_uat session cookie containing the user access token and returns the user record.

​
Request body

​
email
string
required
The user’s email address.
​
password
string
required
The user’s password.
​
tenant_id
string (uuid)
Target tenant to sign into. If omitted, the user’s default tenant is used.

​
Response 200

Returns a UserResponse. See Create user for field descriptions.
The ks_uat cookie returned by this endpoint is your user access token (UAT). Pass it as Authorization: Bearer <uat> on subsequent requests, or let the browser send it automatically via the cookie.

​
Example

curl -X POST https://api-staging.knowledgestack.ai/v1/auth/pw/signin \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "s3cur3p@ss"
  }'

​
Send password reset email


POST https://api-staging.knowledgestack.ai/v1/auth/pw/send_reset_email Send a password reset email to the given address. The email contains a token that you pass to reset with token.

​
Request body

​
email
string
required
The email address associated with the account.

​
Response 200

Returns an EmailSentResponse.
​
email_id
string (uuid)
ID of the sent email message.

​
Example

curl -X POST https://api-staging.knowledgestack.ai/v1/auth/pw/send_reset_email \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

​
Reset password


POST https://api-staging.knowledgestack.ai/v1/auth/pw/reset Reset the password for the currently authenticated user using their existing password. Requires a valid UAT.

​
Request body

​
old_password
string
required
The user’s current password.
​
new_password
string
required
The new password. Minimum 8 characters.

​
Response 200

Returns a UserResponse reflecting the updated user.

​
Example

curl -X POST https://api-staging.knowledgestack.ai/v1/auth/pw/reset \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "old_password": "s3cur3p@ss",
    "new_password": "n3wp@ssw0rd"
  }'

​
Reset password with token


POST https://api-staging.knowledgestack.ai/v1/auth/pw/reset_with_token Reset the password using an email verification token from the send reset email flow. This does not require an existing session.

​
Request body

​
email_token
string
required
The password reset token from the reset email.
​
new_password
string
required
The new password. Minimum 8 characters.

​
Response 200

Returns a UserResponse.

​
Example

curl -X POST https://api-staging.knowledgestack.ai/v1/auth/pw/reset_with_token \
  -H "Content-Type: application/json" \
  -d '{
    "email_token": "<token-from-email>",
    "new_password": "n3wp@ssw0rd"
  }'

​
Refresh UAT


POST https://api-staging.knowledgestack.ai/v1/auth/uat Refresh the user access token or switch the active tenant. Call this when the current UAT has expired or when you want to operate under a different tenant.

​
Query parameters

​
tenant_id
string (uuid)
Target tenant ID to switch to. Omit to refresh the current tenant.

​
Response 200

Returns a UserResponse with the updated current_tenant_id.

​
Example

# Refresh current tenant
curl -X POST https://api-staging.knowledgestack.ai/v1/auth/uat \
  -H "Authorization: Bearer <your-api-key>"

# Switch tenant
curl -X POST "https://api-staging.knowledgestack.ai/v1/auth/uat?tenant_id=<tenant-id>" \
  -H "Authorization: Bearer <your-api-key>"

​
Sign out


POST https://api-staging.knowledgestack.ai/v1/auth/signout Invalidate the current session and clear the ks_uat cookie.

​
Response 200

Returns an empty JSON object {}.

​
Example

curl -X POST https://api-staging.knowledgestack.ai/v1/auth/signout \
  -H "Authorization: Bearer <your-api-key>"