Auth

Auth

Sign-up, sign-in and profile endpoints for dashboard users and for front ends built on the API.

Sign-up, sign-in and profile endpoints for dashboard users. Most integrations never call these: create an API key in the dashboard and use it. They matter when you script account creation, build on the API with your own front end, or need a session to manage keys and settings.

Production sign-up may require a Cloudflare Turnstile token and email verification; GET /v1/auth/providers says what the server enforces. Sign-in and sign-up are rate limited per IP (20 and 5 per hour).

#Sign-in methods

GET/v1/auth/providersNo authentication

Which sign-in methods this server enables, whether self-serve sign-up is open, the Turnstile site key when bot protection is on, and whether email verification is required.

Returns

{password, signup_enabled, google, github, turnstile_site_key, email_verification}.
print(client.auth.providers())
curl https://api.kaimei.ai/v1/auth/providers
200 OKResponse
{
  "password": true,
  "signup_enabled": true,
  "google": true,
  "github": true,
  "turnstile_site_key": "0x4AAAAAAA…",
  "email_verification": true
}

#Create an account

POST/v1/auth/signupNo authentication

Create a user and their personal workspace (the user is its owner, and its only member). When email verification is required the response is {"status": "pending_verification", …} and a link is emailed; otherwise a session is returned straight away. If that email cannot be sent the account still exists and the response is 503 verification_email_failed; request another link, because signing up again is 409 email_taken.

Body parameters

emailstringrequired

passwordstringrequired

8 to 256 characters.

namestringoptional

Display name.

organization_namestringoptional

A name for the personal workspace. Defaults to {name}'s workspace.

turnstile_tokenstringoptional

Required when the server enforces Turnstile.

Returns

A session (access_token, expires_in, user, organization) or a pending-verification notice. 201.
session = client.auth.signup(email="you@example.com", password="correct horse battery staple",
                             name="You", organization_name="Acme Risk")
# the client now sends the session token when one was returned
curl https://api.kaimei.ai/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "correct horse battery staple", "name": "You", "organization_name": "Acme Risk"}'
201 CreatedResponse
{
  "status": "pending_verification",
  "email": "you@example.com",
  "message": "Check your email for a verification link."
}
201 Createdwhen verification is not required
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.…",
  "token_type": "bearer",
  "expires_in": 604800,
  "user": {
    "object": "user",
    "id": "usr_99d45281ca85b8a7cc92",
    "email": "demo@kaimei.ai",
    "name": "Kaimei Demo",
    "avatar_url": null,
    "auth_provider": "password",
    "role": "owner",
    "email_verified": true,
    "organization_id": "org_c72a301b93331f42b7b9",
    "created_at": "2026-10-31T22:37:25.378782Z",
    "last_login_at": "2026-10-31T22:40:22.603319Z"
  },
  "organization": {
    "object": "organization",
    "id": "org_c72a301b93331f42b7b9",
    "name": "Kaimei Demo",
    "slug": "kaimei-demo",
    "plan": "free",
    "kind": "personal",
    "settings": {},
    "quotas": null,
    "role": "owner",
    "member_count": 1,
    "features": {"members": false},
    "created_at": "2026-10-31T22:37:25.334655Z"
  }
}

#Sign in

POST/v1/auth/loginNo authentication

Exchange email and password for a session token. 401 invalid_credentials on a wrong password, 401 email_unverified when verification is pending.

Body parameters

emailstringrequired

passwordstringrequired

Returns

A session for the account's personal workspace (access_token, expires_in, user, organization). Switch to work in another organization. The Python client installs the token on the client automatically.
session = client.auth.login(email="you@example.com", password="...")
print(session.expires_in, session.user.role, session.organization.plan)
curl https://api.kaimei.ai/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "..."}'
200 OKResponse
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.…",
  "token_type": "bearer",
  "expires_in": 604800,
  "user": {
    "object": "user",
    "id": "usr_99d45281ca85b8a7cc92",
    "email": "demo@kaimei.ai",
    "name": "Kaimei Demo",
    "avatar_url": null,
    "auth_provider": "password",
    "role": "owner",
    "email_verified": true,
    "organization_id": "org_c72a301b93331f42b7b9",
    "created_at": "2026-10-31T22:37:25.378782Z",
    "last_login_at": "2026-10-31T22:40:22.603319Z"
  },
  "organization": {
    "object": "organization",
    "id": "org_c72a301b93331f42b7b9",
    "name": "Kaimei Demo",
    "slug": "kaimei-demo",
    "plan": "free",
    "kind": "personal",
    "settings": {},
    "quotas": null,
    "role": "owner",
    "member_count": 1,
    "features": {"members": false},
    "created_at": "2026-10-31T22:37:25.334655Z"
  }
}

#Switch organization

POST/v1/auth/switchSession token only

A new session for the same account in another organization it belongs to. Every other route reads and writes the organization its token names, so this is how a dashboard moves between a personal workspace and its teams. personal names the personal workspace. 404 organization_not_found for one the account is not in. It answers even when the current token's organization is one the account has left.

Body parameters

organizationstringrequired

Organization id or slug, or personal.

Returns

A session: the same shape as signing in, with organization the one switched to and user.role the account's role there.
client.auth.login(email="you@example.com", password="...")
session = client.auth.switch("acme-risk")
print(session.organization.name, session.user.role)
curl https://api.kaimei.ai/v1/auth/switch \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"organization": "acme-risk"}'
200 OKResponse
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.…",
  "token_type": "bearer",
  "expires_in": 604800,
  "user": {
    "object": "user",
    "id": "usr_99d45281ca85b8a7cc92",
    "email": "demo@kaimei.ai",
    "name": "Kaimei Demo",
    "avatar_url": null,
    "auth_provider": "password",
    "role": "admin",
    "email_verified": true,
    "organization_id": "org_c72a301b93331f42b7b9",
    "created_at": "2026-10-31T22:37:25.378782Z",
    "last_login_at": "2026-10-31T22:40:22.603319Z"
  },
  "organization": {
    "object": "organization",
    "id": "org_5b1f0c9a7d2e4f6a8c3b",
    "name": "Acme Risk",
    "slug": "acme-risk",
    "plan": "team",
    "kind": "team",
    "settings": {},
    "quotas": null,
    "role": "admin",
    "member_count": 3,
    "features": {"members": true},
    "created_at": "2026-11-18T09:12:44.118203Z"
  }
}

#Who am I

GET/v1/auth/meAPI key or session

The principal behind the token: user for a session, api_key for a key, with the organization the request acts in either way. For a session, role is the user's role in that organization and organizations lists every one they belong to.

Returns

{principal, user, organization, role, organizations, api_key}.
who = client.auth.me()
curl https://api.kaimei.ai/v1/auth/me \
  -H "Authorization: Bearer $KAIMEI_API_KEY"
200 OKResponse
{
  "principal": "user",
  "user": {
    "object": "user",
    "id": "usr_99d45281ca85b8a7cc92",
    "email": "demo@kaimei.ai",
    "name": "Kaimei Demo",
    "avatar_url": null,
    "auth_provider": "password",
    "role": "owner",
    "email_verified": true,
    "organization_id": "org_c72a301b93331f42b7b9",
    "created_at": "2026-10-31T22:37:25.378782Z",
    "last_login_at": "2026-10-31T22:40:22.603319Z"
  },
  "organization": {
    "object": "organization",
    "id": "org_c72a301b93331f42b7b9",
    "name": "Kaimei Demo",
    "slug": "kaimei-demo",
    "plan": "free",
    "kind": "personal",
    "settings": {},
    "quotas": null,
    "role": "owner",
    "member_count": 1,
    "features": {"members": false},
    "created_at": "2026-10-31T22:37:25.334655Z"
  },
  "role": "owner",
  "organizations": [
    {
      "object": "organization",
      "id": "org_c72a301b93331f42b7b9",
      "name": "Kaimei Demo",
      "slug": "kaimei-demo",
      "plan": "free",
      "kind": "personal",
      "settings": {},
      "quotas": null,
      "role": "owner",
      "member_count": 1,
      "features": {"members": false},
      "created_at": "2026-10-31T22:37:25.334655Z"
    },
    {
      "object": "organization",
      "id": "org_5b1f0c9a7d2e4f6a8c3b",
      "name": "Acme Risk",
      "slug": "acme-risk",
      "plan": "team",
      "kind": "team",
      "settings": {},
      "quotas": null,
      "role": "admin",
      "member_count": 3,
      "features": {"members": true},
      "created_at": "2026-11-18T09:12:44.118203Z"
    }
  ],
  "api_key": null
}

#Update the profile

PATCH/v1/auth/meSession token only

Change the signed-in user's name, avatar URL or password. Changing the password of a password account requires current_password.

Body parameters

namestringoptional

avatar_urlstringoptional

passwordstringoptional

8 to 256 characters.

current_passwordstringoptional

Required with password.

Returns

The User.
client.auth.update_me(name="Samson", password="new-password", current_password="old-password")
curl -X PATCH https://api.kaimei.ai/v1/auth/me \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Samson"}'
200 OKResponse
{
  "object": "user",
  "id": "usr_99d45281ca85b8a7cc92",
  "email": "demo@kaimei.ai",
  "name": "Samson",
  "avatar_url": null,
  "auth_provider": "password",
  "role": "owner",
  "email_verified": true,
  "organization_id": "org_c72a301b93331f42b7b9",
  "created_at": "2026-10-31T22:37:25.378782Z",
  "last_login_at": "2026-10-31T22:40:22.603319Z"
}

#Upload or remove a profile photo

POST/v1/auth/me/avatarSession token only

POST a base64 JPEG, PNG, WEBP or GIF under 750 KB (a data: URL prefix is accepted and stripped). The photo is served inline as a data URL in avatar_url. DELETE /v1/auth/me/avatar removes it.

Body parameters

datastringrequired

Base64 image data.

content_typestringoptional

Ignored; the type is sniffed from the bytes.

Returns

The User.
curl https://api.kaimei.ai/v1/auth/me/avatar \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"data\": \"$(base64 -w0 me.png)\"}"

curl -X DELETE https://api.kaimei.ai/v1/auth/me/avatar -H "Authorization: Bearer $SESSION_TOKEN"
200 OKResponse
{
  "object": "user",
  "id": "usr_99d45281ca85b8a7cc92",
  "email": "demo@kaimei.ai",
  "name": "Kaimei Demo",
  "avatar_url": "data:image/png;base64,iVBORw0KGgo…",
  "auth_provider": "password",
  "role": "owner",
  "email_verified": true,
  "organization_id": "org_c72a301b93331f42b7b9",
  "created_at": "2026-10-31T22:37:25.378782Z",
  "last_login_at": "2026-10-31T22:40:22.603319Z"
}

#Remove a profile photo

DELETE/v1/auth/me/avatarSession token only

Remove the signed-in user's photo. avatar_url becomes null.

Returns

The User.
curl -X DELETE https://api.kaimei.ai/v1/auth/me/avatar -H "Authorization: Bearer $SESSION_TOKEN"
200 OKResponse
{
  "object": "user",
  "id": "usr_99d45281ca85b8a7cc92",
  "email": "demo@kaimei.ai",
  "name": "Kaimei Demo",
  "avatar_url": null,
  "auth_provider": "password",
  "role": "owner",
  "email_verified": true,
  "organization_id": "org_c72a301b93331f42b7b9",
  "created_at": "2026-10-31T22:37:25.378782Z",
  "last_login_at": "2026-10-31T22:40:22.603319Z"
}

#Verify an email address

POST/v1/auth/verify-emailNo authentication

Confirm a verification token and receive a session. The mailed link uses GET /v1/auth/verify-email?token=…, which redirects to the dashboard with the session in the URL fragment. POST /v1/auth/resend-verification with {"email"} (and a Turnstile token when enforced) sends a new link and returns 204, including when the address is unknown or already verified. If the mail for a real unverified account cannot be sent, the response is 503 verification_email_failed.

Body parameters

tokenstringrequired

From the verification email.

Returns

A session.
client.auth.verify_email(token=token_from_email)
client.auth.resend_verification(email="you@example.com")
curl https://api.kaimei.ai/v1/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{"token": "…"}'

curl https://api.kaimei.ai/v1/auth/resend-verification \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'   # 204
200 OKResponse
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.…",
  "token_type": "bearer",
  "expires_in": 604800,
  "user": {
    "object": "user",
    "id": "usr_99d45281ca85b8a7cc92",
    "email": "demo@kaimei.ai",
    "name": "Kaimei Demo",
    "avatar_url": null,
    "auth_provider": "password",
    "role": "owner",
    "email_verified": true,
    "organization_id": "org_c72a301b93331f42b7b9",
    "created_at": "2026-10-31T22:37:25.378782Z",
    "last_login_at": "2026-10-31T22:40:22.603319Z"
  },
  "organization": {
    "object": "organization",
    "id": "org_c72a301b93331f42b7b9",
    "name": "Kaimei Demo",
    "slug": "kaimei-demo",
    "plan": "free",
    "kind": "personal",
    "settings": {},
    "quotas": null,
    "role": "owner",
    "member_count": 1,
    "features": {"members": false},
    "created_at": "2026-10-31T22:37:25.334655Z"
  }
}

#Resend a verification email

POST/v1/auth/resend-verificationNo authentication

Send a new verification link. The response is 204 whether or not an unverified account uses that address. A Turnstile token is required when the server enforces it. Five requests per IP and three per address each hour. If the mail for a real unverified account cannot be sent, the response is 503 verification_email_failed.

Body parameters

emailstringrequired

turnstile_tokenstringoptional

Required when the server enforces Turnstile.

Returns

Nothing. 204.
client.auth.resend_verification(email="you@example.com")
curl https://api.kaimei.ai/v1/auth/resend-verification \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'   # 204
204 No ContentResponse

#Request a password reset

POST/v1/auth/forgot-passwordNo authentication

Email a link to choose a new password. The response is 204 whether or not an account uses that address. A Turnstile token is required when the server enforces it. Five requests per IP and three per address each hour. If the mail cannot be sent the response is 503 reset_email_failed and the password is unchanged.

Body parameters

emailstringrequired

turnstile_tokenstringoptional

Required when the server enforces Turnstile.

Returns

Nothing. 204.
client.auth.forgot_password(email="you@example.com")
curl https://api.kaimei.ai/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'   # 204
204 No ContentResponse

#Choose a new password

POST/v1/auth/reset-passwordNo authentication

Set a new password from the token in the reset email and receive a session. The link is valid for one hour and works once. It also marks the email verified. 401 invalid_reset when the token is missing, expired, or already used. The reset token is not itself a session.

Body parameters

tokenstringrequired

From the reset email.

passwordstringrequired

8 to 256 characters.

Returns

A session. The Python client installs the token on the client automatically.
session = client.auth.reset_password(token=token_from_email, password="a-new-passphrase")
curl https://api.kaimei.ai/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{"token": "…", "password": "a-new-passphrase"}'
200 OKResponse
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.…",
  "token_type": "bearer",
  "expires_in": 604800,
  "user": {
    "object": "user",
    "id": "usr_99d45281ca85b8a7cc92",
    "email": "demo@kaimei.ai",
    "name": "Kaimei Demo",
    "avatar_url": null,
    "auth_provider": "password",
    "role": "owner",
    "email_verified": true,
    "organization_id": "org_c72a301b93331f42b7b9",
    "created_at": "2026-10-31T22:37:25.378782Z",
    "last_login_at": "2026-10-31T22:40:22.603319Z"
  },
  "organization": {
    "object": "organization",
    "id": "org_c72a301b93331f42b7b9",
    "name": "Kaimei Demo",
    "slug": "kaimei-demo",
    "plan": "free",
    "kind": "personal",
    "settings": {},
    "quotas": null,
    "role": "owner",
    "member_count": 1,
    "features": {"members": false},
    "created_at": "2026-10-31T22:37:25.334655Z"
  }
}

#OAuth sign-in

GET/v1/auth/oauth/{provider}/startNo authentication

Begin a Google or GitHub sign-in. The browser is redirected to the provider and back to /v1/auth/oauth/{provider}/callback, which creates or links the user and redirects to the dashboard's /auth/callback with access_token and redirect_to in the URL fragment. An existing password account with the same email is linked rather than duplicated.

Path parameters

providerstringrequired
google or github. 400 provider_disabled when not configured.

Query parameters

redirect_tostringoptionaldefault "/"

Dashboard path to return to.

Returns

302 to the provider.
# in a browser
open "https://api.kaimei.ai/v1/auth/oauth/github/start?redirect_to=/models"
302 FoundResponse
HTTP/1.1 302 Found
Location: https://github.com/login/oauth/authorize?client_id=…&redirect_uri=https%3A%2F%2Fapi.kaimei.ai%2Fv1%2Fauth%2Foauth%2Fgithub%2Fcallback&scope=read%3Auser+user%3Aemail&state=…

#OAuth callback

GET/v1/auth/oauth/{provider}/callbackNo authentication

The provider redirects the browser here. Kaimei checks state, creates or links the user, and redirects to the dashboard's /auth/callback with access_token and redirect_to in the URL fragment. This is the provider's request, not one you call yourself.

Path parameters

providerstringrequired
google or github.

Query parameters

codestringoptional

Authorization code from the provider.

statestringoptional

The signed state from the start.

errorstringoptional

Set by the provider when the person cancels.

Returns

302 to the dashboard.
# the provider sends the browser here
# https://api.kaimei.ai/v1/auth/oauth/github/callback?code=…&state=…
302 FoundResponse
HTTP/1.1 302 Found
Location: https://dashboard.kaimei.ai/auth/callback#access_token=…&redirect_to=%2F

#Sign out

POST/v1/auth/logoutAPI key or session

Sessions are stateless signed tokens, so this endpoint changes nothing server-side; it exists so clients have one place to clear their state. Returns 204.

Returns

Nothing.
client.auth.logout()
curl -X POST https://api.kaimei.ai/v1/auth/logout \
  -H "Authorization: Bearer $SESSION_TOKEN"   # 204
204 No ContentResponse