Authentication

Get current user

GET /api/auth/me

Returns the currently authenticated user.

Response:

{
  "id": "uuid",
  "username": "alice",
  "displayName": "Alice",
  "avatarUrl": "https://...",
  "isBot": false
}
const me = await client.getMe()
me = client.get_me()

Update profile

PATCH /api/auth/me
FieldTypeDescription
displayNamestringDisplay name
avatarUrlstring | nullAvatar URL
const updated = await client.updateProfile({
  displayName: 'New Name',
  avatarUrl: 'https://example.com/avatar.png',
})
updated = client.update_profile(
    display_name="New Name",
    avatar_url="https://example.com/avatar.png",
)

Get user profile

GET /api/auth/users/:id

Returns a public user profile by ID.

const profile = await client.getUserProfile('user-id')
profile = client.get_user_profile("user-id")

Register

POST /api/auth/register

No authentication required.

FieldTypeRequiredDescription
emailstringYesEmail address
passwordstringYesPassword
usernamestringNoUnique username. Generated when omitted.
displayNamestringNoDisplay name
inviteCodestringNoOptional membership invite. Unlocks Cloud and server creation.
const { accessToken, refreshToken, user } = await client.register({
  email: '[email protected]',
  password: 'secure-password',
  displayName: 'Alice',
})
result = client.register(
    email="[email protected]",
    password="secure-password",
    display_name="Alice",
)
access_token = result["accessToken"]

Email code login

POST /api/auth/email/start POST /api/auth/email/verify

Email code verification signs in an existing user or creates a visitor account.

await client.startEmailLogin({ email: '[email protected]' })
const { accessToken, refreshToken, user } = await client.verifyEmailLogin({
  email: '[email protected]',
  code: '123456',
})

Login

POST /api/auth/login

No authentication required.

FieldTypeRequired
emailstringYes
passwordstringYes
const { accessToken, refreshToken, user } = await client.login({
  email: '[email protected]',
  password: 'secret',
})
result = client.login(email="[email protected]", password="secret")

Refresh token

POST /api/auth/refresh

Returns a new JWT token.

const tokens = await client.refreshToken(refreshToken)
result = client.refresh_token(refresh_token)

Membership

Invite codes are not required to register. Use membership APIs to unlock advanced capabilities:

GET /api/membership/me POST /api/membership/redeem-invite

Membership responses include status, tier, level, isMember, and effective capabilities. Treat capabilities as the source of truth for advanced actions; new tiers can be added later without changing this response shape.

Common advanced capabilities include cloud:deploy, server:create, invite:create, and oauth_app:create. A missing capability should be rendered as an upgrade or invite redemption path, not as a failed login.

Fast auth endpoints are rate limited. A 429 response includes RATE_LIMITED and Retry-After.


Disconnect

POST /api/auth/disconnect

Notifies the server that the client is disconnecting (used for presence tracking).

await client.disconnect()
client.disconnect()

List linked OAuth accounts

GET /api/auth/oauth/accounts
const accounts = await client.listOAuthAccounts()
accounts = client.list_oauth_accounts()

DELETE /api/auth/oauth/accounts/:accountId
await client.unlinkOAuthAccount('account-id')
client.unlink_oauth_account("account-id")

Change password

PUT /api/auth/password
FieldTypeRequiredDescription
currentPasswordstringYesCurrent password
newPasswordstringYesNew password
await client.changePassword({
  currentPassword: 'old-pass',
  newPassword: 'new-pass',
})
client.change_password(
    current_password="old-pass",
    new_password="new-pass",
)

Google ID token login

POST /api/auth/google/id-token

Sign in or register using a Google ID token.

FieldTypeRequiredDescription
idTokenstringYesGoogle ID token
const { accessToken, refreshToken, user } = await client.loginWithGoogleIdToken('google-id-token')
result = client.login_with_google_id_token("google-id-token")

Dashboard

GET /api/auth/dashboard

Returns the current user's dashboard summary.

const dashboard = await client.getDashboard()
dashboard = client.get_dashboard()