Account and Organization API

Account and organization API

These application APIs serve account and workspace features. They are separate from the machine document API. Authorization is route-specific; workspace membership, administration permissions, and state rules apply. Use the normal application for credential setup unless building an approved client.

Authentication and profile

Prefix paths below with /api/v1/auth.

Method	Suffix	Purpose and input
POST	/register	email, password, optional planType (individual or teams) and companyName
POST	/verify-email	Verify registration using the private token
POST	/resend-verification	Request another verification message using email
POST	/login	email and password; may return an MFA challenge instead of a session
POST	/login/mfa	Finish an issued authenticator challenge through its approved ticket/code flow
POST	/forgot-password	Request reset using email
POST	/reset-password	Complete the private reset-token flow
POST	/logout	End the authorized session
POST	/refresh	Rotate an issued refresh session using refreshToken or the applicable cookie
GET / PUT	/profile	Read / update authorized profile settings
POST	/profile/verify-email-change	Complete an issued email-change verification
POST	/profile/change-password	Authenticated password change
POST	/mfa/setup	Begin authenticator setup
POST	/mfa/verify-setup	Confirm authenticator setup
POST	/mfa/enable, /mfa/disable	Existing MFA management routes; follow the intended setup and policy flow
GET / PUT	/mfa-enforcement	Read / change eligible organization MFA policy
GET / PUT	/session-settings	Read / update session preferences
POST	/session/validate	Validate applicable session context
POST	/delete-account	Account deletion under service rules

Normal login can return token and organisationId; a challenge can instead return mfaRequired or mfaSetupRequired and a private mfaTicket. Do not treat a successful HTTP response as proof MFA is finished. Registration and recovery responses also differ from the document DTO shape.

Refresh is rotation of an existing user refresh session. It is not a client-credentials token issuance endpoint. A consumed refresh token must not be reused. Store and transmit all credential material securely, and never publish the actual response from credential setup.

Organizations

Prefix these paths with /api/v1/organisations.

Method	Suffix	Purpose
POST	/	Create an organization with required name, optional slug, domain
GET	/my-organisations	List available organizations
POST	/switch	Switch using targetOrganisationId
GET	/me	Read current organization
PATCH	/me/settings	Change available organization settings
DELETE	/me	Delete current organization under service rules
POST	/me/upgrade-to-teams	Eligible upgrade, optional companyName
GET / PUT	/me/branding	Read / update supported branding
GET / PATCH	/me/notifications	Read / update notification preferences
GET	/me/usage	Read usage and available limits
GET / PUT	/me/compliance	Read / update policy preferences
GET	/me/audit-logs	Read authorized organization audit records
GET	/me/audit-logs/export	Export permitted audit records as CSV or JSON
GET	/me/members	List members
DELETE	/me/members/{userId}	Remove a member
PATCH	/me/members/{userId}/status	status: active or suspended
PATCH	/members/{userId}/role	Change membership role using role
GET / POST	/teams	List / create teams
POST	/teams/{id}/members	Add a member using userId
DELETE	/teams/{id}/members/{userId}	Remove a team member
GET / POST	/roles	List / create organization roles
GET / POST	/invitations	List / send invitations
DELETE	/invitations/{id}	Revoke an invitation
POST	/invitations/{id}/resend	Resend an eligible invitation
GET	/invitations/details/{token}	Read the private invited task
POST	/invitations/accept	Accept using token and required account details
GET / POST	/domains	List / add workspace domains
POST	/domains/{id}/verify	Check an added domain's verification

An invitation body supports email, role (default user), and optional teamId. Team creation requires name, with optional description and lead ID. Custom roles require name and a nonempty permissions array. Domain creation requires domain; use the instructions returned by the application for proving domain control. A configured domain is not automatically verified.

Branding supports logoUrl, primary and secondary colors, company address, sender name, and email footer. Notifications support reminders, reminder frequency (1–30 days), expiry warnings, completion emails, and a footer. These preferences do not create the background processing or email provider needed to deliver notifications.

Organization policy includes session timeout (5–1,440 minutes), MFA requirements and roles, compliance preferences, signing reauthentication preferences, and a retention setting (1–365 days). A saved policy is not proof every downstream process enforces it or that records are automatically purged; confirm deployment behavior and legal retention requirements with the operator.

Role registries and user role changes

• GET /api/v1/roles/default: default roles, requiring applicable role-read permission.
• GET /api/v1/roles/permissions: permission registry for eligible callers.
• PUT /api/v1/users/{id}/role: authorized user role assignment; separate from organization membership-role changes.

Machine API client bindings and request logs are documented in Webhooks and REST API Integration. Platform administration is described in Administration; operational access should follow the organization's approved process.