API Reference
System Endpoints
Reference for all administrative and organizational API endpoints under /api/system/ and /api/auth/.
System Endpoints
System endpoints handle cross-workspace, organizational, and administrative operations. All system endpoints live under the /api/system/ base path. Authentication endpoints live under /api/auth/.
We recommend not directly manipulating the system schema or structure.
Authentication
Authentication endpoints are served at /api/auth/. Monospace uses JSON Web Tokens (JWT) and secure cookies for session management. Access tokens are short-lived JWTs passed via the Authorization: Bearer <token> header (with a cookie fallback). Refresh tokens are long-lived JWTs handled via HttpOnly cookies in session mode, or returned in the JSON response body in JSON mode. See the Authentication guide for usage details.
| Method | Endpoint | Description |
|---|---|---|
POST | /api/auth/login | Authenticate with email and password. Supports session (cookie) and json (token in body) modes. |
POST | /api/auth/refresh | Obtain a new access token using a refresh token (from cookie or request body). |
POST | /api/auth/logout | Invalidate the refresh token and clear session cookies. |
POST | /api/auth/password-change | Change the authenticated user's password. Requires current and new password. |
POST | /api/auth/password-reset/request | Request a password reset email for a given email address. |
GET | /api/auth/password-reset/verify | Verify a password reset token (via query parameter). |
POST | /api/auth/password-reset/confirm | Confirm a password reset with the token and a new password. |
Workspaces
| Method | Endpoint | Description |
|---|---|---|
GET | /api/system/workspaces | List all workspaces. |
POST | /api/system/workspaces | Create a new workspace. Requires workspace:create org entitlement. |
GET | /api/system/workspaces/{workspace} | Read a single workspace by name. |
PATCH | /api/system/workspaces/{workspace} | Update a workspace by name. |
DELETE | /api/system/workspaces/{workspace} | Delete a workspace by name. Requires workspace:delete:{id} org entitlement. |
Users
| Method | Endpoint | Description |
|---|---|---|
GET | /api/system/users | List all users. Requires authentication. |
GET | /api/system/users/me | Read the currently authenticated user. |
PATCH | /api/system/users/me | Update the currently authenticated user's profile. |
GET | /api/system/users/{user_id} | Read a single user by ID. Requires authentication. |
PATCH | /api/system/users/{user_id} | Update a user by ID. Requires user:update:{id} org entitlement when updating another user. |
Org Roles
| Method | Endpoint | Description |
|---|---|---|
GET | /api/system/roles | List all organization-level roles. |
POST | /api/system/users/{user_id}/role | Attach an org role to a user. Requires orgRole:assign:{id} org entitlement. |
Invites
| Method | Endpoint | Description |
|---|---|---|
GET | /api/system/invites | List all pending invitations. Requires authentication. |
POST | /api/system/invites | Invite one or more users to the organization or a workspace. |
PATCH | /api/system/invites/{invitation_id} | Renew a pending invitation (extend its TTL). |
DELETE | /api/system/invites/{invitation_id} | Revoke a pending invitation. |
POST | /api/system/invites/accept | Accept an invitation using the invite token (no authentication required). |
API Keys
| Method | Endpoint | Description |
|---|---|---|
GET | /api/system/api-keys | List all API keys. Requires apiKey:read org entitlement. |
POST | /api/system/api-keys | Create a new API key. Accepts name, TTL, and optional description. |
PATCH | /api/system/api-keys/{key_id} | Update an API key by ID. |
DELETE | /api/system/api-keys/{key_id} | Delete an API key by ID. |
Service Accounts
| Method | Endpoint | Description |
|---|---|---|
GET | /api/system/service-accounts | List all service accounts. Requires serviceAccount:read org entitlement. |
POST | /api/system/service-accounts | Create a new service account. |
GET | /api/system/service-accounts/{id} | Read a single service account by ID. |
PATCH | /api/system/service-accounts/{id} | Update a service account by ID. |
DELETE | /api/system/service-accounts/{id} | Delete a service account by ID. |
Sign-in Providers
| Method | Endpoint | Description |
|---|---|---|
GET | /api/system/auth-providers | List all sign-in providers. Requires authProvider:read org entitlement. |
POST | /api/system/auth-providers | Create a sign-in provider. Requires authProvider:create org entitlement. |
GET | /api/system/auth-providers/{id} | Read a single sign-in provider by ID. Requires authProvider:read org entitlement. |
PATCH | /api/system/auth-providers/{id} | Update a sign-in provider by ID. Requires authProvider:update org entitlement. |
DELETE | /api/system/auth-providers/{id} | Delete a sign-in provider by ID. Requires authProvider:delete org entitlement. |
The client secret is write-only — supply it on create or update, but it is never returned by GET. See Configure SSO for the full setup.
Assets & Files
| Method | Endpoint | Description |
|---|---|---|
GET | /api/system/files | List all system-level file metadata records. Requires authentication. |
GET | /api/system/files/{file_id} | Read a single file metadata record by ID. Requires authentication. |
POST | /api/system/assets | Upload a new system-level asset via multipart form. |
GET | /api/system/assets/{file_id} | Download a system-level asset by file ID. |
DELETE | /api/system/assets/{file_id} | Delete a system-level asset by file ID. |
Settings
| Method | Endpoint | Description |
|---|---|---|
GET | /api/system/settings | Read the organization settings. Requires authentication. |
PATCH | /api/system/settings | Update organization settings. Requires orgSettings:edit org entitlement. |
Audit Logs
| Method | Endpoint | Description |
|---|---|---|
GET | /api/system/audit-logs | List audit log entries. Supports fields, filter, sort, limit, and offset. Requires the auditLog:read org entitlement. See Audit Logs. |
Entitlements & OpenAPI
| Method | Endpoint | Description |
|---|---|---|
GET | /api/system/entitlements | List all available org-level entitlement descriptors. |
GET | /api/system/openapi | Serve the system-level OpenAPI specification. Requires systemOpenApiSchema:read org entitlement. |
For the complete and up-to-date schema, refer to the dynamically generated OpenAPI Specification from your running instance.