API docs

API endpoints

These examples use a placeholder client ID <clientid>. Replace it with your application's client ID in request bodies and in the x-client-id header when the endpoint is scoped to this application.

Back to home

Request basics

Application scope

Send x-client-id as <clientid> for app-scoped auth, session, account, and management calls.

User auth

Browser clients can use the cookies set by login and refresh. API clients can also pass an auth token with Authorization: Bearer token. Applications can verify those JWTs locally using /.well-known/jwks.json.

Response shape

Successful responses return { success: true, data }. Errors return { success: false, error }.

Application identity

Use these endpoints when a backend service needs to verify the application itself.

POSTCLIENT SECRET/api/applications/authenticate

Authenticate application

Checks this application's client ID and client secret and returns the safe application record when valid.

Auth: Requires application client secret.

Headers

{
  "content-type": "application/json"
}

Body

{
  "clientid": "<clientid>",
  "clientsecret": "<clientSecret>"
}

Token verification

Use the JWKS endpoint to verify HouyAuth JWTs locally in applications without making a remote call on every request.

GETPUBLIC/.well-known/jwks.json

Get auth token signing keys

Returns the public JSON Web Key Set for verifying RS256 auth tokens issued by HouyAuth.

Auth: Public endpoint.

Cache the JWKS according to the Cache-Control header.
Verify the JWT signature, issuer, audience/client ID, expiration, app ID, session ID, and roles before trusting a token.
The JWT header includes a kid value that matches the key id in this JWKS.

User authentication

Use these endpoints to register users, sign them in for this application, keep sessions alive, and end sessions.

GETPUBLIC/api/auth/register/availability?username=<username>&email=<email>

Check registration availability

Checks whether a username and/or email address is available before submitting registration.

Auth: Public endpoint.

POSTPUBLIC/api/auth/register

Register user

Creates a user account and sends an email verification link when email delivery is enabled.

Auth: Public endpoint.

Headers

{
  "content-type": "application/json"
}

Body

{
  "username": "newuser",
  "email": "newuser@example.com",
  "password": "<password>",
  "firstname": "New",
  "lastname": "User",
  "birthday": "2000-01-01"
}

POSTPUBLIC/api/auth/login

Sign in user

Authenticates a user for this application, creates a session, sets auth cookies, and returns the user's roles for this client ID.

Auth: Public endpoint with app scope.

Headers

{
  "content-type": "application/json",
  "x-client-id": "<clientid>"
}

Body

{
  "clientid": "<clientid>",
  "email": "user@example.com",
  "password": "<password>",
  "devicename": "Web browser"
}

POSTUSER/api/auth/refresh

Refresh session

Rotates the refresh token and issues a fresh auth token for this application.

Auth: Requires refresh token cookie.

Headers

{
  "x-client-id": "<clientid>"
}

POSTUSER/api/auth/logout

Log out user

Revokes the active session and clears this application's auth/session cookies.

Auth: Requires signed-in user for this application.

Headers

{
  "x-client-id": "<clientid>"
}

GETUSER/api/auth/me

Get current auth state

Returns the signed-in user, this application's user-app state, roles, client ID, and session ID.

Auth: Requires signed-in user.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

POSTPUBLIC/api/auth/email/verify

Verify email

Consumes an email verification token and marks the user's email address as verified.

Auth: Public token endpoint.

Headers

{
  "content-type": "application/json"
}

Body

{
  "token": "<verificationToken>"
}

POSTPUBLIC/api/auth/email/resend-verification

Resend verification email

Sends another verification email for a user who has not verified their address.

Auth: Public endpoint.

Headers

{
  "content-type": "application/json"
}

Body

{
  "email": "user@example.com"
}

POSTPUBLIC/api/auth/password/forgot

Request password reset

Sends a password reset link when the email belongs to an account.

Auth: Public endpoint.

Headers

{
  "content-type": "application/json"
}

Body

{
  "email": "user@example.com"
}

POSTPUBLIC/api/auth/password/reset

Reset password

Consumes a reset token, updates the user's password, and can revoke existing sessions.

Auth: Public token endpoint.

Headers

{
  "content-type": "application/json"
}

Body

{
  "token": "<resetToken>",
  "newPassword": "<newPassword>",
  "revokeAllSessions": true
}

POSTUSER/api/auth/password/change

Change password

Changes the signed-in user's password after checking their current password.

Auth: Requires signed-in user.

Headers

{
  "content-type": "application/json",
  "x-client-id": "<clientid>"
}

Body

{
  "currentPassword": "<currentPassword>",
  "newPassword": "<newPassword>",
  "revokeOtherSessions": true
}

POSTUSER/api/auth/email/change/request

Request email change

Sends a confirmation token before changing the signed-in user's email address.

Auth: Requires signed-in user.

Headers

{
  "content-type": "application/json",
  "x-client-id": "<clientid>"
}

Body

{
  "newEmail": "new-email@example.com"
}

POSTPUBLIC/api/auth/email/change/confirm

Confirm email change

Consumes an email-change token and updates the user's email address.

Auth: Public token endpoint.

Headers

{
  "content-type": "application/json"
}

Body

{
  "token": "<emailChangeToken>"
}

Sessions and account

Use these endpoints after sign-in to show account state, update profile data, and manage sessions.

GETUSER/api/auth/sessions

List sessions

Lists sessions for the signed-in user, including which one is active.

Auth: Requires signed-in user.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

DELETEUSER/api/auth/sessions/<sessionid>

Revoke session

Revokes one session owned by the signed-in user. If it revokes the current session, auth cookies are cleared.

Auth: Requires signed-in user.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

POSTUSER/api/auth/sessions/revoke-others

Revoke other sessions

Revokes every session for the signed-in user except the current session.

Auth: Requires signed-in user.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

POSTUSER/api/auth/sessions/revoke-all

Revoke all sessions

Revokes every session for the signed-in user and clears auth cookies.

Auth: Requires signed-in user.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

GETUSER/api/users/me

Get my account

Returns the signed-in user's account details.

Auth: Requires signed-in user.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

PATCHUSER/api/users/me

Update my account

Updates the signed-in user's account display name.

Auth: Requires signed-in user.

Headers

{
  "content-type": "application/json",
  "x-client-id": "<clientid>"
}

Body

{
  "displayname": "Display Name"
}

DELETEUSER/api/users/me

Delete my account

Deletes or deactivates the signed-in user's account.

Auth: Requires signed-in user.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

GETUSER/api/users/me/profile

Get my profile

Returns the signed-in user's profile fields.

Auth: Requires signed-in user.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

PATCHUSER/api/users/me/profile

Update my profile

Updates the signed-in user's profile fields.

Auth: Requires signed-in user.

Headers

{
  "content-type": "application/json",
  "x-client-id": "<clientid>"
}

Body

{
  "firstname": "First",
  "lastname": "Last",
  "birthday": "2000-01-01"
}

GETUSER/api/users/me/logs/login

Get my login logs

Returns login activity for the signed-in user's own account.

Auth: Requires signed-in user.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

GETUSER/api/users/me/logs/email

Get my email logs

Returns email delivery activity for the signed-in user's own account.

Auth: Requires signed-in user.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

Social features

Use these endpoints for friend dashboards, friend requests, friendships, and blocks.

GETUSER/api/users/me/social-state

Get my social state

Returns the signed-in user's current social relationship state.

Auth: Requires signed-in user.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

GETUSER/api/users/me/friend-dashboard

Get my friend dashboard

Returns friends, requests, and block state for the signed-in user.

Auth: Requires signed-in user.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

POSTUSER/api/users/me/friend-requests

Send friend request

Creates a friend request from the signed-in user.

Auth: Requires signed-in user.

Headers

{
  "content-type": "application/json",
  "x-client-id": "<clientid>"
}

Body

{
  "targetuserid": "<targetUserId>"
}

POSTUSER/api/users/me/friend-requests/<senderid>/respond

Respond to friend request

Accepts or rejects a friend request sent to the signed-in user.

Auth: Requires signed-in user.

Headers

{
  "content-type": "application/json",
  "x-client-id": "<clientid>"
}

Body

{
  "accept": true
}

DELETEUSER/api/users/me/friend-requests/<userid>

Rescind friend request

Cancels a pending friend request sent by the signed-in user.

Auth: Requires signed-in user.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

DELETEUSER/api/users/me/friends/<userid>

Remove friend

Removes an existing friendship for the signed-in user.

Auth: Requires signed-in user.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

PUTUSER/api/users/me/blocks/<userid>

Block user

Blocks another user for the signed-in user.

Auth: Requires signed-in user.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

DELETEUSER/api/users/me/blocks/<userid>

Remove block

Removes a block relationship for the signed-in user.

Auth: Requires signed-in user.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

Application management

Use these endpoints from admin tooling for users who have owner or admin access to this application.

GETUSER/api/applications

List my applications

Lists applications the signed-in user can access, including roles for each application.

Auth: Requires signed-in user.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

POSTDEVELOPER+/api/applications

Create application

Creates a new application and returns its one-time client secret.

Auth: Requires developer, admin, or owner role.

Headers

{
  "content-type": "application/json",
  "x-client-id": "<clientid>"
}

Body

{
  "name": "Application name",
  "requestedclientid": "optional-client-id",
  "description": "Optional public description",
  "homepageurl": "https://example.com"
}

GETPUBLIC/api/applications/directory

List application directory

Lists active registered applications that have shared a public home page URL.

Auth: Public endpoint.

GETMEMBER/api/applications/<clientid>

Get this application

Returns this application's details and caller-specific access state.

Auth: Requires access to this application.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

PATCHADMIN+/api/applications/<clientid>

Update this application

Updates this application's name or owner/admin managed fields.

Auth: Requires owner or admin role for this application.

Headers

{
  "content-type": "application/json",
  "x-client-id": "<clientid>"
}

Body

{
  "name": "Updated application name",
  "description": "Updated public description",
  "homepageurl": "https://example.com"
}

DELETEOWNER/api/applications/<clientid>

Delete this application

Deletes this application.

Auth: Requires owner role for this application.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

POSTSYSTEM + OWNER/api/applications/<clientid>/enable

Enable this application

Reactivates this application.

Auth: Requires system application auth plus owner/admin permission.

Headers

{
  "authorization": "Bearer <systemAuthToken>",
  "x-client-id": "houyauth-system"
}

POSTSYSTEM + OWNER/api/applications/<clientid>/disable

Disable this application

Disables this application and can include an admin-visible reason.

Auth: Requires system application auth plus owner/admin permission.

Headers

{
  "authorization": "Bearer <systemAuthToken>",
  "x-client-id": "houyauth-system",
  "content-type": "application/json"
}

Body

{
  "disabledreason": "Maintenance window"
}

POSTSYSTEM + OWNER/api/applications/<clientid>/rotate-secret

Rotate client secret

Creates a new one-time client secret for this application.

Auth: Requires system application auth plus owner/admin permission.

Headers

{
  "authorization": "Bearer <systemAuthToken>",
  "x-client-id": "houyauth-system"
}

POSTSYSTEM + OWNER/api/applications/<clientid>/transfer-owner

Transfer ownership

Transfers this application to another verified user.

Auth: Requires system application auth plus owner permission.

Headers

{
  "authorization": "Bearer <systemAuthToken>",
  "x-client-id": "houyauth-system",
  "content-type": "application/json"
}

Body

{
  "newowneruserid": "<userId>"
}

GETADMIN+/api/applications/<clientid>/members

List application members

Lists users who have membership in this application.

Auth: Requires owner or admin role for this application.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

POSTADMIN+/api/applications/<clientid>/members

Add application member

Adds a user to this application and assigns initial roles.

Auth: Requires owner or admin role for this application.

Headers

{
  "content-type": "application/json",
  "x-client-id": "<clientid>"
}

Body

{
  "targetuserid": "<userId>",
  "displayname": "Member display name"
}

GETADMIN+/api/applications/<clientid>/members/<userid>

Get application member

Returns one member's access state for this application.

Auth: Requires owner or admin role for this application.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

PATCHADMIN+/api/applications/<clientid>/members/<userid>

Update application member

Updates an application member's display name or active state.

Auth: Requires owner or admin role for this application.

Headers

{
  "content-type": "application/json",
  "x-client-id": "<clientid>"
}

Body

{
  "displayname": "Member display name"
}

DELETEADMIN+/api/applications/<clientid>/members/<userid>

Remove application member

Removes a user's membership from this application.

Auth: Requires owner or admin role for this application.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

POSTADMIN+/api/applications/<clientid>/members/<userid>/enable

Enable application member

Reactivates a user's membership in this application.

Auth: Requires owner or admin role for this application.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

POSTADMIN+/api/applications/<clientid>/members/<userid>/disable

Disable application member

Disables a user's membership in this application.

Auth: Requires owner or admin role for this application.

Headers

{
  "content-type": "application/json",
  "x-client-id": "<clientid>"
}

Body

{
  "disabledreason": "No longer needs access"
}

DELETEADMIN+/api/applications/<clientid>/members/<userid>/roles/<role>

Remove application member role

Removes one role from a member of this application.

Auth: Requires owner or admin role for this application.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

Admin and lookup endpoints

Use these endpoints from internal admin experiences. They are scoped by the selected client ID when they require auth.

GETUSER/api/users/search?query=<searchText>

Search users

Searches users for selection workflows such as adding members.

Auth: Requires signed-in user.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

GETADMIN+/api/users

List users

Lists users for administrative views.

Auth: Requires admin or owner role.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

GETADMIN+/api/users/<userid>

Get user

Returns one user's account details.

Auth: Requires admin/owner or permitted self access.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

PATCHADMIN+/api/users/<userid>

Update user

Updates one user's account details.

Auth: Requires admin/owner or permitted self access.

Headers

{
  "content-type": "application/json",
  "x-client-id": "<clientid>"
}

Body

{
  "displayname": "Display Name"
}

DELETEADMIN+/api/users/<userid>

Delete user

Deletes or deactivates one user account.

Auth: Requires admin/owner or permitted self access.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

POSTADMIN+/api/users/<userid>/enable

Enable user

Reactivates a disabled user account.

Auth: Requires admin or owner role.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

POSTADMIN+/api/users/<userid>/disable

Disable user

Disables a user account.

Auth: Requires admin or owner role.

Headers

{
  "content-type": "application/json",
  "x-client-id": "<clientid>"
}

Body

{
  "disabledreason": "Policy reason"
}

GETADMIN+/api/system/settings/email-sending

Get email sending setting

Returns whether global email delivery is enabled in the database setting.

Auth: Requires admin or owner role.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

PATCHADMIN+/api/system/settings/email-sending

Update email sending setting

Turns global email delivery on or off without changing environment variables.

Auth: Requires admin or owner role.

Headers

{
  "content-type": "application/json",
  "x-client-id": "<clientid>"
}

Body

{
  "enabled": true
}

GETADMIN+/api/logs/login

List login logs

Returns login activity across users.

Auth: Requires admin or owner role.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

GETADMIN+/api/logs/email

List email logs

Returns email delivery activity across users.

Auth: Requires admin or owner role.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}

GETADMIN+/api/logs/errors

List error logs

Returns server-side error log entries.

Auth: Requires admin or owner role.

Headers

{
  "authorization": "Bearer <authToken>",
  "x-client-id": "<clientid>"
}