Settings
Configure your Aforo organization — identity, default currency, billing anchors, provider COGS rates, data retention, and theme — plus quick access to billing entities, SCIM provisioning, and rate-limit policies.
Settings
The Settings hub is your organization-level control panel. Open it from Governance → Settings in the sidebar. It groups four related surfaces into one place:
The rest of this page covers the General tab. Each subsection persists to organization_settings (one row per tenant) via PATCH /api/v1/organization-settings. Every save fires the standard audit trail.
Looking for Members, API Keys, SSO, Audit Log, or Active Sessions? Those live in the Admin Panel, opened from the tenant popover at the bottom of the sidebar — they're access-control surfaces, not org-wide preferences.
Who can change what
When VITE_RBAC_ENABLED=true, inputs render disabled and save buttons are hidden for any role other than OWNER / ADMIN. You can still browse and copy values.
Organization Profile
The identity card your organization shows on every internal surface — T&C documents, plan agreements, and the workspace switcher.
Display name and legal name appear in every customer-facing T&C document. Pick the legal name your counsel signs off on — changing it later doesn't retroactively rewrite documents customers have already accepted.
Where you'll see this stored: organization_settings.display_name / legal_name / logo_url columns. Logo uploads use a dedicated PATCH /api/v1/organization-settings/logo endpoint with magic-byte validation, so a renamed .exe won't sneak through.
Financial Preferences
Two settings that influence how new rate cards and offerings are scaffolded.
Default currency
The ISO 4217 currency code (USD, EUR, GBP, CAD, AUD, SGD, INR, JPY) prefilled when you create a new rate card or offering. It does not force existing rate cards to convert — each rate card pins its own currency at creation time.
Don't change this once you've launched. Switching the org default doesn't migrate any existing rate cards, offerings, or invoices — and the dropdown picker in the create wizards always lets you override it per artifact. If you're juggling multiple currencies routinely, use Billing Entities (per-issuer base currency) instead of leaning on a single org default.
Rate card billing anchor
Controls which billing cycle anchors appear in the Rate Card wizard, and which one is preselected:
Default billing anchor — the option preselected for new rate cards.
Allowed billing anchors — checkboxes for which options the wizard offers. Leave both checked to let operators pick per rate card; check only one to lock every new rate card to that anchor (the field disappears from the wizard).
This setting only affects new rate cards. Existing rate cards keep whichever anchor they were created with. To change an existing rate card's anchor, open it in the wizard and edit it — the audit log will capture the change.
Provider Cost Registry
Where you record your wholesale cost from upstream LLM providers — OpenAI, Anthropic, Google, AWS Bedrock, Azure OpenAI — so Aforo can compute COGS and margins on every agentic API call.
The registry is read by the usage-ingestor service on every event via an internal endpoint: GET /api/v1/provider-costs/rate?provider=...&model=...&occurredAt=.... The matching rate determines the per-event cost recorded in the cogs_events stream that powers your COGS & Margins dashboard.
A rate row
Why it has effective dates
Provider prices change. When OpenAI cut GPT-4o pricing in Q1 2026, your historical COGS for events before the cut should still reflect the old rate. By stamping effectiveFrom and effectiveTo on each row, the registry returns the rate that was active at the time the usage event happened — not the current rate.
Add a new row each time a provider's price changes. Older rows automatically retire when their effectiveTo passes.
Quick start
If your org bills agentic APIs and you haven't seeded the registry yet, click Seed Defaults to populate the registry with current public prices for the major providers and models. Then edit each row to match your actual contracted rates.
The seed populates public list prices. Enterprise tenants with negotiated rates should overwrite each row with your actual cost — Aforo never reaches out to provider APIs to verify pricing.
Data Retention
Compliance-grade controls for how long Aforo keeps each category of customer data after a customer cancels or their account expires. A nightly job (3:00 AM UTC) walks every category and enforces the policy automatically.
What you can configure per policy
Defaults
If you've never configured retention, click Load Defaults to seed the recommended policies for invoice history, audit logs, support tickets, and so on. Each comes with industry-standard defaults you can refine.
Enforcement Log
Click Enforcement Log to see what the nightly job did most recently — data type, action, count of affected records, completed-at timestamp. Useful for the auditor question "prove your DPA's retention clause is actually enforced."
DELETE is irreversible. The nightly job removes the row + cascades; there's no soft-delete recovery. Use ARCHIVE or ANONYMIZE if you need to keep the structure for compliance reporting.
Appearance
A four-way theme switcher that's instant and personal:
Themes apply instantly without a page refresh. The selection is saved both to the backend (organization_settings.ui_theme) and to localStorage as aforo_theme, so it survives session expiration and works offline.
The theme is per-tenant, not per-user. If you want different themes per teammate, each user can override locally by toggling here — the backend write is a best-effort sync, so a network failure doesn't block the local switch.
Terms & Conditions
A rich-text editor for your organization's standard T&Cs. The document is rendered:
- On the customer signup flow (with explicit accept-and-agree)
- As part of every signed quote acceptance (CPQ)
- In the customer portal under "Legal & Compliance"
Changes here apply to new acceptances only. Customers who've already accepted a prior version keep their accepted copy in their audit record — you don't accidentally rewrite history when you tighten a clause.
For per-product T&Cs (e.g. an AI-services rider), use Products → Terms & Conditions on the individual product detail page instead.
What's not on this page anymore
If you've used Aforo before and remember some of these fields, here's where they moved on 2026-06-14:
If your scripts were calling PATCH /api/v1/organization-settings with any of these field names, they'll continue to return 200 — the backend ignores unknown fields rather than rejecting the request — but the values won't persist.
API reference
For each subsection above, here's the underlying call:
# Read current settings
GET /api/v1/organization-settings
X-Tenant-Id: <your tenant id>
# Update any subset of fields
PATCH /api/v1/organization-settings
X-Tenant-Id: <your tenant id>
Content-Type: application/json
{
"displayName": "SmartAI Inc.",
"legalName": "SmartAI Technologies Inc.",
"currency": "USD",
"defaultBillingAnchor": "ANNIVERSARY",
"allowedBillingAnchors": ["ANNIVERSARY", "CALENDAR"],
"uiTheme": "default"
}
# Upload a new logo (1MB raw cap, magic-byte validated)
PATCH /api/v1/organization-settings/logo
X-Tenant-Id: <your tenant id>
Content-Type: application/json
{ "logoUrl": "data:image/png;base64,..." }
# Provider Cost Registry
GET /api/v1/provider-costs
POST /api/v1/provider-costs
PUT /api/v1/provider-costs/{id}
DELETE /api/v1/provider-costs/{id}
POST /api/v1/provider-costs/seed-defaults
# Data Retention
GET /api/v1/retention-policies
PATCH /api/v1/retention-policies/{id}
POST /api/v1/retention-policies/seed-defaults
GET /api/v1/retention-policies/action-log
All endpoints require a Bearer token in Authorization and your X-Tenant-Id. See Authentication for how to mint one.
Common tasks
I'm onboarding a new tenant — what should I configure first?
- Set the display name and legal name under Organization Profile.
- Upload a logo so customer-facing T&Cs render with your branding.
- Pick the default currency that matches your primary market.
- If you bill agentic APIs, click Seed Defaults in the Provider Cost Registry, then edit each row to match your contracted rates.
- Click Load Defaults under Data Retention to start with industry-standard policies; adjust later.
- Skim Billing Entities to confirm the default issuing entity matches your operating jurisdiction.
My team uses multiple currencies. Which should I pick as the default? Pick the currency you use for the majority of new rate cards. The dropdown in the Rate Card wizard always lets you override it per artifact. If you operate distinct subsidiaries (US Inc., Acme EU GmbH, …), set each up as its own Billing Entity with its own base currency — that's the supported pattern for multi-currency operation.
Where's the audit log? Admin Panel → Audit Log (in the tenant popover, not on the Settings page itself). It records every change to fields on the Settings page, plus member invites, API key creation, SSO config, and SCIM token mints.
I changed my logo and customers still see the old one. The org logo is uploaded as a base64 data URL embedded in the settings response, so there's no CDN cache to bust. Hard-refresh the customer portal once (Cmd+Shift+R / Ctrl+Shift+R). If the issue persists, check the Enforcement Log under Data Retention — if a recent retention run archived a stale config, restore it.