OAuth & Machine Clients

What Is This Feature?

Not all users of your platform are people sitting at a keyboard. Often, the most important "users" are other software systems — a CRM pulling conversation data, a backend service sending automated messages, a data pipeline exporting analytics. These machine-to-machine connections are handled through OAuth and API credentials: a secure way for external systems to authenticate and interact with your platform programmatically.

---

Why It Matters to Your Business

API integrations are a major part of enterprise deals. When a large customer wants to connect your platform to their internal tools, they need a secure, auditable, and manageable way to do it. This feature is what makes that possible.

• Enables integrations. Customers can connect your platform to their existing tech stack without manual intervention for every request.
• Security you can audit. Every connection has its own credentials. If one gets compromised, you revoke just that one — not everything. The audit trail shows exactly what each connection has been doing.
• Usage limits per integration. You can cap how many requests a given integration can make per day, protecting you from unexpected cost spikes caused by a runaway script or misconfigured third-party tool.
• Smooth incident response. If a customer's API key is leaked, the process to revoke it, issue new credentials, and notify them is streamlined and well-documented — minimizing damage and downtime.

---

How It Works (No Technical Jargon)

1. An administrator registers a new integration in the admin panel, giving it a name and defining what it's allowed to do (its scopes) and how many requests it can make.
2. The system generates credentials — a client ID and a secret. The secret is shown exactly once, then stored only as a secure hash (like a password — even the platform can't see it again after creation).
3. The external system authenticates using those credentials to get a time-limited access token, which it includes with every request.
4. Every token request is logged — what integration, from which IP address, for which organization. This creates a complete audit trail.
5. Usage is tracked in real time. When an integration approaches its daily limit, it starts receiving warning headers. When it hits the limit, requests are rejected with a clear error message rather than silently failing.

---

Rotating Credentials (Keeping Things Secure Over Time)

API credentials should not live forever. The platform supports credential rotation — generating new credentials while giving the integration owner a short window to update their systems, then invalidating the old credentials. This is important for:

• Routine security hygiene (rotating credentials on a schedule)
• Post-incident recovery (immediately replacing compromised credentials)
• Offboarding (permanently revoking access when a partnership ends)

---

What You Can Do as an Administrator

• Create, view, and revoke integrations from the admin dashboard
• See a log of recent activity per integration (when it authenticated, how many requests it made)
• Rotate credentials with a guided UI flow
• Set per-integration daily request quotas
• Immediately disable any integration with a single click if something looks suspicious

---

What to Expect on the Roadmap

The team is building:

1. Hashed credential storage and a credential rotation UI (estimated 2 weeks)
2. Per-integration quota enforcement with real-time usage tracking (estimated 3 weeks)

Once live, these features will give you and your customers the visibility and control needed for secure, enterprise-grade integrations.