Governing API Access
Scoped, owned, auditable machine credentials for external systems that call the RapidValue API.
The problem: machines need governed access too
RapidValue already authenticates humans (a session token in the browser) and the on-premise agent (a keypair). But a governance platform is also called by other machines: a customer's human-resources feed pushing joiner and leaver events, an integration flow reading access requests, a script, a security-monitoring pull. Each of those callers needs a credential to reach the RapidValue API (application programming interface — the programmatic entry point to the platform).
The classic anti-pattern is a static, all-powerful secret pasted into a configuration file: nobody owns it, nobody knows what it may do, it never expires, and it never gets reviewed. API access governance treats that machine credential as a first-class governed object instead — scoped, owned, expiring, revocable, and attributed on every call.
A credential is bound to scopes, not a role
The central rule: an API credential carries an explicit set of scopes, and its power is exactly those scopes — never a role. A scope is a narrow permission such as identities:write or access-requests:read. When an admin issues a credential, they pick the minimum scopes the external system actually needs.
- The human-resources system that pushes joiner and leaver events gets
identities:writeonly — not full administrative reach. - The integration flow that reads access requests gets
access-requests:read— nothing more.
This is least privilege by construction. A credential can never exceed its declared scopes, and there is no "admin" shortcut that widens it. Each scope also carries a risk flag (low, medium, high) so the person granting it can see what they are handing out.
| Property | What it means |
|---|---|
scopes |
The exact permissions this credential holds — resource plus read or write |
type |
A static API key, or an OAuth2 client-credentials client |
expires_at |
When the credential stops working (no expiry is discouraged) |
last_used_at |
When it last made a call — the dormancy signal |
status |
active, expired, or revoked |
owner |
The accountable team or person, resolved through the ownership model |
The secret is shown once, then stored only as a hash
When a credential is created or rotated, its secret value is displayed exactly once, in a "copy it now, you won't see this again" moment. RapidValue never stores the secret in plaintext and never returns it again — only a one-way hash is kept, enough to verify a caller but not to reproduce the secret.
💡 Tip
Because the secret is shown once, rotation is the safe way to recover from a lost or leaked secret: rotate to mint a new secret, and the old one is invalidated. Revoke instantly if a credential is known to be compromised — authentication stops immediately.
Scope is enforced on every request — out of scope is denied and audited
Every authenticated call is checked against the credential's scopes at request time. A call that falls outside the credential's scopes is refused (denied), and the denial is written to the immutable audit trail, attributed to that credential. Every successful call is likewise attributed to the credential in the audit log.
The effect is that an auditor can answer, from the audit trail alone: which external systems can call our platform, with what rights, who owns them, when they were last used — and see proof that a credential was held to least privilege, including the attempts it was denied.
An API credential is an ownable object, reviewed like any access
A credential is registered as an ownable object, so it flows through the same governance the platform applies to everything else:
- It has an owner — the integration team or person accountable for it — assigned through the standard ownership model, not an ad-hoc field.
- It is subject to access reviews: periodically the owner attests that the credential is still needed. A credential that is never attested is flagged.
This is what turns a machine secret into governed access. The same review discipline that keeps human access clean keeps the machine estate clean.
Dormant and over-scoped credentials are surfaced, not left to rot
Two hygiene signals are computed and raised through the Platform Advisor (the platform's single recommendation inbox), reusing the same dormancy pattern applied to unused assignments:
- Dormant — a credential unused for an extended period (for example 90 days or more). A likely candidate to revoke.
- Over-scoped — a credential granted scopes it has never actually exercised. Those unused scopes should be trimmed back toward least privilege.
Usage is tracked as counters (calls in the last 24 hours, calls in the last 90 days, top endpoints) rather than raw call rows, so the "is this still needed, and is it right-sized?" question is answerable at a glance.
What this is not
API access governance is deliberately kept separate from two neighbouring concepts:
- The agent's own machine identity — the on-premise agent authenticates with its own keypair. That is the agent proving it is the agent, a different thing from a tenant issuing outbound-integration credentials.
- The vendor's platform-admin key — a platform-internal credential used by RapidValue itself, not a tenant-facing surface.
API credentials are the tenant's own governed keys for the external systems that integrate with their platform. They are managed under Environment & connections, the technical tenant-setup surface.