ometere123/the-skills-bible/api-auth-access-engineer

API Authentication and Access Engineer

Purpose

Build and operate verified API principals with least authority for each resource and operation.

Use this skill when

• Design API credentials, tokens, scopes, claims, delegation, tenant context, consent, revocation, and policy enforcement.
• Independent producers and consumers need an explicit, supported contract.
• Interface behaviour must remain reliable across versions, failures, and organisational boundaries.
• Developer experience and operational evidence are part of the delivery outcome.

Do not use this skill as the primary workflow when

• The work is entirely internal to one module with no independent consumer contract.
• A previously defined generic architecture or security workflow is the dominant task.
• The requested change cannot be authorised, observed, or supported through its lifecycle.

Required inputs

• Consumer workflows, constraints, and expected outcomes.
• Current specifications, schemas, examples, SDKs, and implementation behaviour.
• Identity, tenant, data, permission, and secret requirements.
• Workload, payload, latency, quota, and dependency limits.
• Supported versions, release policy, incidents, and consumer inventory.

Classify missing information as blocking, important, or optional. Inspect the actual specifications, code, gateway policies, SDKs, credentials, usage, delivery evidence, and support history before asking for information that can be verified directly.

Core operating principles

• Design interfaces around stable consumer outcomes rather than internal implementation structure.
• Treat schemas, examples, documentation, SDKs, policies, and compatibility rules as versioned production artefacts.
• Prefer explicit contracts, deterministic validation, idempotent effects, and bounded failure semantics.
• Keep identity, tenant, permission, quota, and ownership decisions authoritative and server-enforced.
• Preserve backward compatibility deliberately and make breaking changes visible, testable, and migratable.
• Design retries, timeouts, cancellation, pagination, ordering, and partial failure as part of the public contract.
• Protect consumers from implementation churn while avoiding abstractions that hide important differences.
• Make integrations observable end to end through stable identifiers, correlation, delivery state, and reconciliation.
• Provide realistic examples, sandboxes, diagnostics, and migration guidance so consumers can succeed independently.
• Govern the full lifecycle from discovery and onboarding through change, deprecation, offboarding, and retirement.

Workflow

1. Define the consumer outcome

• State the required outcome for verified API principals with least authority for each resource and operation.
• Identify unacceptable ambiguity, side effects, and consumer failure.

2. Map actors and trust boundaries

• Map end users, first-party applications, third-party applications, services, devices, partners, and administrators.
• Assign provider, consumer, platform, security, support, and decision ownership.

3. Define the public contract

• Specify credential types, token claims, scopes, resources, operations, delegation, consent, and audit context.
• Separate public semantics from internal implementation and document authoritative behaviour.

4. Secure identity and data

• Design issuer and audience validation, proof of possession, tenant authority, object permissions, revocation, and secret lifecycle.
• Validate every trust decision at the authoritative boundary and minimise exposed data.

5. Engineer reliability

• Define token expiry, key rotation, provider outage, session revocation, step-up, and emergency access.
• Make partial success, unknown outcomes, cancellation, and recovery visible to consumers.

6. Bound scalability and cost

• Control token validation cost, authorisation caching, policy propagation, credential quotas, and tenant scale.
• Set explicit limits, fair-use rules, capacity assumptions, and dependency protections.

7. Design developer experience

• Provide onboarding credentials, scope guidance, test identities, rotation instructions, consent screens, and diagnostic errors.
• Ensure a new consumer can complete the critical workflow without undocumented support knowledge.

8. Validate compatibility

• Test old token formats, key overlap, scope migration, client upgrades, and mixed provider versions.
• Use supported consumers, generated clients, contract fixtures, and mixed-version scenarios.

9. Instrument operations

• Observe credential issuance, denied requests, scope use, revocation lag, key age, delegated actors, and suspicious access.
• Correlate consumer-visible failures with provider, dependency, contract, and release evidence.

10. Govern the lifecycle

• Define publication, ownership, support, change review, deprecation, offboarding, and retirement.
• Record residual risks, exceptions, migration deadlines, and review triggers.

Decision rules

Required outputs

• Consumer outcome and scope.
• Actor, ownership, and trust map.
• Versioned interface or integration contract.
• Identity, permission, and data controls.
• Reliability and recovery semantics.
• Limits, capacity, and fairness policy.
• Developer onboarding and diagnostic assets.
• Compatibility and migration evidence.
• Operational telemetry and support model.
• Lifecycle, exception, and retirement record.

API, SDK, and integration quality gates

• Consumer gate: Target consumers, workflows, constraints, and success outcomes are explicit.
• Contract gate: Inputs, outputs, errors, state changes, ordering, retries, and limits are precise.
• Identity gate: Authentication, authorisation, tenant, delegation, and credential lifecycle are enforced.
• Compatibility gate: Supported versions, additive changes, breaking changes, and migration paths are documented and tested.
• Reliability gate: Timeouts, idempotency, retries, partial failure, reconciliation, and degraded behaviour are operational.
• Security gate: Untrusted inputs, callbacks, secrets, permissions, and third-party data are bounded.
• Developer gate: Documentation, examples, diagnostics, sandbox behaviour, and SDK ergonomics support independent adoption.
• Observability gate: Requests, deliveries, retries, transformations, failures, and partner outcomes are traceable.
• Scalability gate: Quotas, pagination, payload limits, batching, concurrency, and dependency ceilings are explicit.
• Lifecycle gate: Onboarding, change, deprecation, offboarding, data deletion, and retirement have accountable owners.

Evidence standard

For consequential conclusions, identify the exact API or protocol version, schema, SDK version, environment, consumer, identity, tenant, payload, dependency state, request or delivery identifier, and time window. Distinguish observed contract behaviour, supported inference, and undocumented assumptions. Do not claim compatibility from schema comparison alone when semantics or side effects differ.

Failure handling and escalation

Pause or escalate when:

• The authoritative contract, owner, or consumer expectation is unclear.
• Credentials, tenant boundaries, permissions, callback destinations, or data rights cannot be verified.
• Retrying may duplicate money movement, messages, records, or other external side effects.
• A breaking change affects unknown or uncontactable consumers.
• Third-party behaviour conflicts with documented guarantees or creates active data loss.
• Production testing could send real communications, incur charges, or affect external users.
• Residual integration, security, privacy, or operational risk exceeds delegated authority.

Report the exact blocker, verified state, affected consumers, evidence, safe options, and smallest required decision.

Common anti-patterns

• Trusting tenant identifiers from request bodies.
• Treating API keys as user identities.
• One admin scope for every operation.
• Accepting tokens without audience validation.
• Delegation losing the human actor.
• Credentials that never expire.

Completion checklist

• [ ] Consumer outcomes and exclusions are explicit.
• [ ] Provider and consumer ownership is recorded.
• [ ] The contract includes failure and side-effect semantics.
• [ ] Identity, tenant, and data boundaries are enforced.
• [ ] Retries, timeouts, and unknown outcomes are safe.
• [ ] Limits and dependency ceilings are explicit.
• [ ] Independent consumers can integrate from published assets.
• [ ] Supported versions pass compatibility tests.
• [ ] Operations can correlate and reconcile failures.
• [ ] Deprecation and retirement are executable.

Interface and integration record

# Interface and Integration Record
 
## Outcome
[Consumer workflow, partner exchange, SDK use case, or integration result]
 
## Scope
[Providers, consumers, environments, identities, tenants, data, and exclusions]
 
## Contract
[Operations, schemas, errors, ordering, pagination, quotas, and side effects]
 
## Compatibility
[Versions, supported clients, additive rules, breaking changes, and migration]
 
## Reliability
[Timeouts, retries, idempotency, delivery, reconciliation, and recovery]
 
## Security and privacy
[Credentials, permissions, validation, secrets, callbacks, and data lifecycle]
 
## Developer experience
[Documentation, examples, SDKs, sandbox, diagnostics, and support]
 
## Observability
[Identifiers, traces, logs, metrics, dashboards, and partner evidence]
 
## Residual risk
[Known limitations, owner, acceptance, expiry, and communication]
 
## Lifecycle
[Rollout, deprecation, offboarding, deletion, and retirement]

Related skills

• identity-security-architect
• authorization-security-engineer
• sdk-auth-configuration-engineer
• api-gateway-management-engineer

Maintenance rules

Review this skill when consumers, schemas, protocols, providers, SDKs, limits, regulations, or operational dependencies change; incidents reveal missing contract behaviour; the workflow becomes tied to one vendor; the file approaches 500 lines; or reusable schemas, examples, validators, fixtures, or compatibility tests would improve execution.