Security & Authorization

These rules define baseline authentication and authorization expectations and how to document them for consumers.

Related guides:

• Authentication, authorization, & scopes
• OpenAPI authoring

Related reference:

• Review checklist

#300 - Secure Endpoints with OAuth 2.0

Intent: make sure every operation has explicit auth requirements.

Secure all API endpoints using OAuth 2.0.

Requirements:

• Each operation MUST declare its security requirements in OpenAPI (security).
• Each operation MUST specify whether it is user-context (userAuth) and/or system/service-context (applicationAuth).
• Required scopes MUST be listed per operation (do not rely on global defaults when behavior differs).

Guidance:

• Use least privilege: keep required scope sets minimal.
• If an operation supports both user and service contexts, document the difference in behavior and required scopes/capabilities.

Testability:

• OpenAPI includes an OAuth 2.0 security scheme.
• Every operation has a non-empty security requirement with the documented scopes.
• Docs state the execution context (user vs service) and any additional authorization gates.

#301 - Define and Assign Scopes

Intent: make authorization predictable by using stable scopes and assigning them consistently.

Define OAuth scopes for your API and assign required scopes per endpoint.

Requirements:

• Required scopes MUST be documented per operation using OpenAPI security.
• Scope requirements for an operation MUST be unambiguous:
  • If multiple scopes are listed in a single security requirement, they are treated as AND (all required).
  • If multiple security requirements are listed, they are treated as OR (any requirement satisfies auth).

Guidance:

• Prefer least privilege and minimal scope sets.
• If an operation behaves differently depending on scopes, consider splitting it into separate operations/endpoints rather than overloading one behavior.

Testability:

• OpenAPI security requirements match the documented expectations for AND vs OR.
• For each operation, a reviewer can answer: "Which single token/scopes are required to call this?"

#303 - Define User Capabilities for userAuth Endpoints

Intent: make authorization requirements explicit beyond OAuth scopes.

For endpoints that use userAuth, APIs MUST document the required user capability levels/roles in addition to OAuth scopes.

Requirements:

• State the required user level/role(s) for the operation.
• If authorization differs by operation mode (read vs write), document the differences.
• If the requirement is conditional (feature flags, tenant config), document the condition.

Where to document:

• In the OpenAPI operation description.
• Prefer a consistent vendor extension if tooling consumes it (if available in your platform).

Testability:

• A reviewer can answer: "Which scopes are required?" and "Which user roles/capabilities are required?" from the OpenAPI + docs.

#302 - Document Required Licenses for API Collections

Intent: prevent failed integrations caused by hidden licensing requirements.

If any API collection (tag/group) or operation requires a specific license add-on, entitlement, or feature flag, teams MUST document that requirement.

Where to document:

• In OpenAPI tag descriptions for collection-wide requirements.
• In operation descriptions when requirements differ per endpoint.
• In guides/user manuals for how a customer enables the add-on.

Recommended OpenAPI approach:

• Use a consistent vendor extension so tooling can surface it (example):

tags:
  - name: Accounts
    description: Manage accounts.
    x-license-addons:
      - IdentitySecurityCloud_Core
      - LifecycleManagement

And for endpoint-specific requirements:

paths:
  /accounts/imports:
    post:
      summary: Create account import
      description: Requires the LifecycleManagement add-on.
      x-license-addons: [LifecycleManagement]

Rules:

• Requirements MUST be explicit and machine-discoverable where feasible (extensions + docs).
• Do not rely on support tickets or product UIs as the only source of truth.

Testability:

• Reviewers can determine licensing prerequisites from the published OpenAPI and docs.

#304 - Require HTTPS/TLS for All Endpoints

All API endpoints MUST be accessible only via HTTPS with proper TLS encryption to protect data in transit and prevent man-in-the-middle attacks.

#305 - Never Put Secrets or Credentials in URLs

Never include sensitive information such as secrets, credentials, API keys, or tokens in URL paths or query parameters. Always use HTTP headers or the request body for sensitive data.

#306 - Authenticate and Authorize Before Processing Payloads

Validate authentication and authorization before parsing or processing request payloads to reduce risk from malicious payloads.