Permissions and API access
How Secani applies least privilege across organizations, workspaces, governance scopes, agents, and OSCAL API keys.
Secani separates identity, resource membership, and individual capabilities. Access is evaluated at the organization, workspace, or governance-scope boundary, so a person or connected agent receives only the context required for its assigned work. A broad sign-in does not imply broad data access.
Permission boundaries
| Boundary | Typical content | Examples of capability effects |
|---|---|---|
| Organization | Members, roles, settings, catalogs, API keys | read, sensitive read, write, admin |
| Workspace | Integrations, imports, exports, scopes | read, write, sensitive read, admin |
| Governance scope | Controls, evidence, risks, obligations, assessments, OSCAL | read, sensitive read, write, approve, admin |
Capabilities use stable, task-specific names such as evidence.read, evidence.create, risk.read, risk.write, oscal.read, and oscal.export. Read, sensitive-read, write, approval, and administration are separate effects rather than one all-purpose access flag.
Agent least privilege
Only capabilities explicitly marked as agent-assignable can be granted to an agent registration. Human accountability remains a hard boundary: capabilities for approving evidence, accepting risks, publishing assurance results, managing permissions, executing privacy operations, or approving an agent's own proposal are not agent-assignable.
Start an integration with read-only capabilities at the narrowest governance scope. Add sensitive-read or write capabilities only when the workflow requires them. Keep approval with a named human, review proposed changes before execution, and retire access when the task ends.
Public OSCAL API
The public OSCAL Validation API has two access modes:
- Anonymous requests require no account or credential and receive the documented base rate limits.
- An optional
sk_oscal_bearer key raises validation rate limits. It is a single-purpose credential: it does not grant access to organizations, workspaces, governance scopes, evidence, or product administration.
Organization administrators create and revoke OSCAL API keys in organization settings. Each secret is displayed exactly once. Store it in a secret manager, send it only in the Authorization: Bearer header, and rotate or revoke it if exposed. An invalid key fails with 401 ERR_INVALID_API_KEY; it never silently falls back to anonymous access.
Authentication versus authorization
Secani uses WorkOS for user authentication. Authentication establishes who is calling; Secani's membership and capability checks decide what that identity may access. The current sign-in scope identifies the user and must not be interpreted as permission to read or modify every Secani resource.
Every client should handle 401 as missing or invalid authentication and 403 as authenticated but insufficient authorization. Do not retry either response with broader access automatically. Ask an administrator for the smallest capability set and resource boundary that permits the intended task.
See the OSCAL API guide, API error recovery, and canonical OpenAPI specification.