Security-Sensitive API

Scenario

You maintain an API containing sensitive operations such as:

• changing account email;
• changing passwords;
• deleting accounts;
• modifying organization roles;
• creating API keys.

These endpoints deserve stricter guidance than ordinary read-only operations.

You want coding agents to preserve existing protections instead of simplifying security-sensitive flows while implementing features.

Repository Structure

account-api/
├── src/
│   ├── routes/
│   │   ├── account.ts
│   │   └── organization.ts
│   ├── services/
│   ├── auth/
│   ├── authorization/
│   ├── audit/
│   └── rate-limit/
├── tests/
│   └── security/
└── AGENTS.md

AGENTS.md

# Project Instructions

## Sensitive Operations

Treat operations that change credentials, identity, permissions, ownership, or destructive account state as security-sensitive.

Preserve existing protections such as:

- authentication;
- authorization;
- re-authentication;
- rate limiting;
- audit logging;
- confirmation workflows.

Do not remove or bypass these protections merely to simplify implementation.

## Input

- Validate untrusted input at the API boundary.
- Do not trust user IDs, organization IDs, roles, or ownership claims supplied by the client.
- Derive trusted identity information from the authenticated server-side context.

## Responses

- Avoid returning secrets or unnecessary sensitive fields.
- Preserve existing error handling that avoids exposing internal security details.

## Audit

- Preserve required audit events for security-sensitive state changes.
- Do not include credentials or secret values in audit payloads.

## Testing

For sensitive endpoint changes, test:

- successful authorized access;
- unauthenticated access;
- authenticated but unauthorized access;
- invalid input;
- relevant rate-limit or confirmation behavior;
- cross-user or cross-tenant access where applicable.

What This Does

This tells the agent that certain endpoints have additional invariants.

For example:

Change organization owner

may require more than:

valid request body
+
database update

The actual workflow may require:

authentication
      ↓
authorization
      ↓
re-authentication
      ↓
validation
      ↓
state change
      ↓
audit event

An agent should preserve those controls unless changing them is explicitly part of the task.

What This Does NOT Do

The file does not prescribe identical protections for every endpoint.

A public health-check endpoint does not need the same controls as:

POST /api-keys

Security should be proportional to the operation.

The file also does not say that every sensitive endpoint must implement custom security logic.

Existing middleware and shared policies should be reused.

Why These Instructions Matter

Security protections can look like unnecessary complexity when viewed only from the local implementation.

Suppose an account deletion endpoint asks the user to re-authenticate.

An agent implementing a UI improvement might think:

The user is already logged in. This extra verification is redundant.

But the protection may exist because a stolen session should not automatically allow permanent account destruction.

Likewise, rate limiting on an authentication-related endpoint may look unrelated to the endpoint's main business logic.

Removing it can change the threat model.

AGENTS.md helps communicate:

These controls are part of the feature's correctness.

Key Decisions

Security controls are behavior

Authentication, authorization, audit logging, and confirmation flows are not decorative middleware.

They can be part of the endpoint's required behavior.

Derive trusted identity server-side

Avoid patterns such as:

{
  "userId": "user-123",
  "role": "admin"
}

being treated as proof that the caller is user 123 or an administrator.

Return the minimum necessary information

Sensitive endpoints should not expose internal fields simply because they are available.

Preserve auditability

High-impact actions often need an audit trail.

That trail should record useful metadata without storing credentials.

Test abuse paths

Security-sensitive testing should include attempts that should fail, not only the intended happy path.

When to Use This Pattern

Use this pattern when endpoints can:

• change credentials;
• modify permissions;
• expose sensitive information;
• delete important data;
• create access tokens;
• transfer ownership;
• perform other high-impact operations.

For these endpoints, security controls should be treated as part of functional correctness.