> ## Documentation Index > Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt > Use this file to discover all available pages before exploring further. # Settings API > Org settings, user preferences, team management, API keys, sender IDs, and notification rules. # Settings API Everything that shows up under the dashboard's **Settings** tab — the organization profile, user preferences, in-app notifications, team & invites, API keys, sender IDs, single sign-on (SAML & SCIM), HIPAA controls, privacy, compliance policies, and keyword / opt-out rules. **Base path:** `/api/v1/settings` **Authentication:** Session JWT (most operations are admin/owner-gated). ## Organization | Method | Path | Purpose | | ------ | ------------------------------- | ----------------------- | | `GET` | `/api/v1/settings/organization` | Read org profile | | `GET` | `/api/v1/settings/general` | General settings | | `PUT` | `/api/v1/settings/general` | Update general settings | ## User preferences | Method | Path | Purpose | | ------ | ------------------------------ | ---------------------------------------------- | | `GET` | `/api/v1/settings/preferences` | Read the calling user's preferences | | `PUT` | `/api/v1/settings/preferences` | Update preferences (theme, language, timezone) | ## Notifications | Method | Path | Purpose | | -------- | ------------------------------------------ | ----------------------------------------------------------------------------------------- | | `GET` | `/api/v1/settings/notifications` | List all notifications (read and unread) | | `DELETE` | `/api/v1/settings/notifications` | Permanently delete all notifications (irreversible — this does **not** mark them as read) | | `PUT` | `/api/v1/settings/notifications/{id}/read` | Mark one as read | ## Team | Method | Path | Purpose | | -------- | ---------------------------------------------- | ------------------------------------------ | | `GET` | `/api/v1/settings/team` | List team members | | `GET` | `/api/v1/settings/team/activity` | Recent team activity | | `POST` | `/api/v1/settings/team/invite` | Invite a new member | | `PUT` | `/api/v1/settings/team/{userId}` | Change role | | `DELETE` | `/api/v1/settings/team/{userId}` | Remove a member | | `GET` | `/api/v1/settings/team/invites` | List pending invites | | `DELETE` | `/api/v1/settings/team/invites/{email}` | Cancel an invite | | `POST` | `/api/v1/settings/team/invites/{email}/resend` | Resend an invite | | `POST` | `/api/v1/settings/team/accept-invite` | Accept an invite (invited user calls this) | ## API keys | Method | Path | Purpose | | -------- | ------------------------------------------------ | ----------------------------------------------------- | | `GET` | `/api/v1/settings/api-keys` | List API keys | | `POST` | `/api/v1/settings/api-keys` | Issue a new API key | | `DELETE` | `/api/v1/settings/api-keys/{id}` | Revoke immediately | | `POST` | `/api/v1/settings/api-keys/{id}/rotate` | Rotate (issues new + revokes old) | | `POST` | `/api/v1/settings/api-keys/{id}/schedule-revoke` | Schedule revocation in the future (for safe rotation) | | `POST` | `/api/v1/settings/api-keys/{id}/cancel-revoke` | Cancel a scheduled revoke | ## Sender IDs | Method | Path | Purpose | | ------ | ----------------------------- | ------------------------ | | `GET` | `/api/v1/settings/sender-ids` | List sender IDs | | `POST` | `/api/v1/settings/sender-ids` | Register a new sender ID | Many countries require sender ID pre-registration before alpha-numeric sender IDs can be used. The full list of operations (including delete + status checks) is in the [auto-generated reference](#all-endpoints) below. ## Single sign-on (SAML & SCIM) Configure enterprise SSO and directory provisioning for the org. These endpoints manage the **configuration**; the login and provisioning flows your identity provider calls live on the public `/auth/saml/*` and `/scim/v2/*` paths documented under [Authentication](/authentication). | Method | Path | Purpose | | ------- | --------------------------------------- | ---------------------------------------------------------------------------------------------- | | `GET` | `/api/v1/settings/saml` | Read the current SAML config (returns the certificate fingerprint, never the raw certificate) | | `PATCH` | `/api/v1/settings/saml` | Upsert SAML config — SSO URL, entity ID, attribute mappings, `enabled`, `enforced`. Owner only | | `POST` | `/api/v1/settings/saml/test-connection` | Probe an IdP metadata URL and suggest the SSO URL / entity ID | | `GET` | `/api/v1/settings/scim` | Read the current SCIM config (returns `hasToken`, never the token) | | `POST` | `/api/v1/settings/scim/generate-token` | Generate or rotate the SCIM bearer token — shown once. Owner only | | `PATCH` | `/api/v1/settings/scim` | Update SCIM `enabled`, default role, and group-to-role mapping. Owner only | The SSO URL and metadata URL are validated to block requests to internal or private addresses. When you configure SAML for the first time, `PATCH /api/v1/settings/saml` requires an `x509Cert`; once one is stored, omit the field to change other settings without re-uploading it. ## HIPAA controls Manage covered-entity mode, the Business Associate Agreement (BAA) record, and the PHI access log. Reads require an admin; enabling, disabling, and BAA changes are owner only. | Method | Path | Purpose | | ------ | ----------------------------------------- | ----------------------------------------------------------------------------- | | `GET` | `/api/v1/settings/hipaa` | Read HIPAA status and configuration | | `PUT` | `/api/v1/settings/hipaa` | Enable or disable HIPAA mode and set the data-retention window (30–3650 days) | | `POST` | `/api/v1/settings/hipaa/reauth-challenge` | Mint a 5-minute re-auth challenge required to disable HIPAA mode. Owner only | | `GET` | `/api/v1/settings/hipaa/phi-access-log` | List the PHI access log (paginated) | | `PUT` | `/api/v1/settings/hipaa/baa` | Record BAA signed status, signing date, and document URL. Owner only | Disabling HIPAA mode is protected. `PUT /api/v1/settings/hipaa` with `enabled: false` returns `401 REAUTH_REQUIRED` unless you first call `POST /api/v1/settings/hipaa/reauth-challenge` and replay the returned token in an `X-Reauth-Challenge` header within 5 minutes. Enabling HIPAA and retention-only updates do not require re-auth. See [HIPAA compliance](/compliance/hipaa) for the full covered-entity guide. ## Privacy Control PII redaction and transcript retention for the org. Reads are available to any member; updates are owner/admin only. | Method | Path | Purpose | | ------ | -------------------------- | ----------------------- | | `GET` | `/api/v1/settings/privacy` | Read privacy settings | | `PUT` | `/api/v1/settings/privacy` | Update privacy settings | The body of `PUT /api/v1/settings/privacy` accepts: * `pii_redaction_enabled` (boolean) — mask phone numbers and email addresses on screen for viewer-tier operators. Display only; dial targets and outbound payloads still carry raw E.164. * `pii_redaction_in_transcripts` (boolean) — scrub PII from agent conversation turns at write time. Applies to new turns only; existing turns are not back-redacted. * `transcript_retention_days` (integer 1–3650, or `null` for no deletion) — the nightly retention job deletes agent conversations and messages older than this window. ## Compliance Per-org compliance and outbound-safety policies enforced on the send path. Each resource exposes a read (available to any member) and a write (owner only). | Method | Path | Purpose | | --------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------- | | `GET` / `PATCH` | `/api/v1/settings/compliance/policy-scan-mode` | Pre-send policy scanner mode (`strict`, `warn`, `off`) | | `GET` / `PATCH` | `/api/v1/settings/compliance/unknown-marketing-policy` | Marketing-send policy for contacts whose consent state is unknown | | `GET` / `PATCH` | `/api/v1/settings/compliance/consent-default-policy` | Default consent policy applied when a contact has no explicit consent record | | `GET` / `PUT` | `/api/v1/settings/compliance/country-allowlist` | Outbound destination-country allowlist and the allow-all override | | `GET` / `PUT` | `/api/v1/settings/compliance/fraud-caps` | Per-channel velocity and daily-spend caps, with the platform floor per channel | | `GET` / `PUT` | `/api/v1/settings/compliance/channel-rate-overrides` | Per-channel outbound rate-limit overrides | | `GET` / `PUT` | `/api/v1/settings/compliance/ai-turn-audit` | Toggle AI-turn audit logging | | `GET` / `PATCH` | `/api/v1/settings/compliance/inbox-ai-privacy` | Toggle inbox AI auto-categorize / auto-summarize and set the spam-handling action | The country allowlist is tenant-scoped — it constrains only your own org's outbound traffic, never another tenant's. ## Keyword & opt-out rules Automated inbound-keyword handling and STOP/START opt-out management. Keyword-rule writes require the developer role or higher; opt-out-rule writes require an admin. Both list endpoints are paginated. ### Keyword rules | Method | Path | Purpose | | -------- | ------------------------------------- | --------------------- | | `GET` | `/api/v1/settings/keyword-rules` | List keyword rules | | `POST` | `/api/v1/settings/keyword-rules` | Create a keyword rule | | `PUT` | `/api/v1/settings/keyword-rules/{id}` | Update a keyword rule | | `DELETE` | `/api/v1/settings/keyword-rules/{id}` | Delete a keyword rule | A rule matches an inbound `keyword` on a `channel` (`sms`, `whatsapp`, `rcs`, `viber`, `email`) with a `match_type` of `exact`, `contains`, `starts_with`, or `regex`, then runs an `action`: reply with `response_text`, forward to an `agent_id`, trigger a `flow_id`, or opt the contact out / back in. ### Opt-out rules | Method | Path | Purpose | | -------- | ------------------------------------- | ---------------------------------------------------------- | | `GET` | `/api/v1/settings/opt-out-rules` | List opt-out / opt-in rules | | `POST` | `/api/v1/settings/opt-out-rules` | Create an opt-out or opt-in rule | | `PUT` | `/api/v1/settings/opt-out-rules` | Bulk update opt-out / opt-in rules (up to 100 per request) | | `DELETE` | `/api/v1/settings/opt-out-rules/{id}` | Delete an opt-out / opt-in rule | Opt-out rules are keyword rules whose `action` is `opt-out` or `opt-in` (for example `STOP` and `START`). Set `auto_reply_text` to confirm the change back to the contact. See [Opt-outs & suppression](/api-reference/optouts) for how suppression is enforced at send time. ## See also * [Authentication](/authentication) — API key types and rotation patterns * [Compliance](/compliance/hipaa) — security & access logging requirements