Workspace API
Manage organization settings, members, operator preferences, notifications, and API credentials.
Workspace endpoints control organization-wide behavior and access. Use least-privilege credentials and reserve membership, settings, and credential mutations for administrative workflows.
/v1/workspaceResource Groups
| Prefix | Capabilities | Primary response schemas |
|---|---|---|
/users | current user profile and preferences | UserResponse and preference envelopes |
/organizations | current organization and members | OrganizationResponse, OrganizationMembersResponse |
/settings | profile, company, payment, and defaults | SettingsResponse and update responses |
/notifications | lists, unread state, preferences, subscriptions, tests | notification list and action responses |
/credentials | list, create, update, and revoke API keys | ApiKeysResponse, ApiKeyResponse, ApiKeyCreatedResponse |
Current User and Organization
GET /v1/workspace/users/me
PATCH /v1/workspace/users/me
GET /v1/workspace/users/me/preferences
PATCH /v1/workspace/users/me/preferences
GET /v1/workspace/organizations/current
PATCH /v1/workspace/organizations/current
GET /v1/workspace/organizations/current/membersTreat the returned organization and user IDs as the authoritative scope for later API calls. Preference updates are partial. Send only the settings that the operator changed on purpose.
Settings
GET /v1/workspace/settings returns profile, company, payment, and default configuration. Update each group through its specific endpoint:
PATCH /v1/workspace/settings/profile
PATCH /v1/workspace/settings/company
PATCH /v1/workspace/settings/payment
PATCH /v1/workspace/settings/defaultsRefresh invoice creation and document-preview state after you change defaults. Those views can derive currency, invoice numbers, payment terms, and branding from workspace configuration.
API Credentials
| Method | Path | Request schema | Success response |
|---|---|---|---|
GET | /credentials | query: limit, offset, includeRevoked | ApiKeysResponse |
POST | /credentials | CreateApiKeyRequest | ApiKeyCreatedResponse |
GET | /credentials/{id} | none | ApiKeyResponse |
PATCH | /credentials/{id} | UpdateApiKeyRequest | ApiKeyResponse |
DELETE | /credentials/{id} | none | DeleteApiKeyResponse |
Creation needs a 1–255 character name, 1–50 scopes, an optional environment (live or test), and an optional ISO 8601 expiresAt.
The raw key appears only in ApiKeyCreatedResponse. Store it immediately in a secrets manager. Later list and get responses show only metadata and keyPrefix. They never return the raw credential or key hash.
When you update scopes, the new list replaces the complete scope list. Revocation is permanent. Rotate consumers to a replacement key before you delete the old credential.
Notifications
Notification endpoints give paginated notifications, unread count, delivery preferences, read actions, subscription changes, and test delivery. For read-many, send the documented identifier array. Use the returned count to reconcile partial or already-read records.