API Authentication

Authentication

Authentication is the developer surface for one specific problem: control which software can create paid tasks, read evidence and perform high-impact actions. The design has to combine ordinary software concerns with physical latency, evidence and money movement.

API key model

API key model is where the implementation should expose physical-world constraints rather than abstracting them away. If access, timing, identity or evidence changes the result, the schema should say so.

Server-side credential storage

A production treatment of Server-side credential storage needs both the normal path and the exception path. Human execution is reliable only when the client knows what happens when the environment does not match the request.

Authorization: Bearer $HUMANTASK_API_KEY
X-HumanTask-Project: project_123

Scopes and permissions

Scopes and permissions should be documented as an explicit part of this interface. The caller needs to know which fields affect routing, which values are authoritative and which states can change after a human has accepted work.

Authorization: Bearer $HUMANTASK_API_KEY
X-HumanTask-Project: project_123

Rotation

Rotation should be documented as an explicit part of this interface. The caller needs to know which fields affect routing, which values are authoritative and which states can change after a human has accepted work.

Auditability

Auditability should be documented as an explicit part of this interface. The caller needs to know which fields affect routing, which values are authoritative and which states can change after a human has accepted work.

Agent-specific spend limits

For Agent-specific spend limits, prefer a small number of well-defined fields over free-form conventions. The physical worker may read natural-language instructions, but software should get structured values for anything that affects control flow.

Separate Identity from Authorization

Knowing which project made a request is not the same as deciding what it may do. Keys can identify a caller while scopes, project rules or policy enforce allowed capabilities, maximum spend and evidence access.

Rotate Without Downtime

Production users need a way to create a new credential, deploy it and then revoke the old one. Rotation should not require every task to be paused. Audit logs should record which credential created a high-impact request.

Agent-Specific Controls

An AI agent may need narrower rights than the backend that supervises it. Giving the agent a key that can create limited task types with a capped budget reduces the blast radius of prompt errors or unexpected tool use.

Error Model

Physical errors are domain events. A closed venue, denied access, missing item and unsafe condition should not collapse into one generic failure. The client may retry some cases, accept others as evidence and escalate the rest.

Production Readiness

Before production, test duplicate creation, cancellation, a blocked task, incomplete evidence, credential rotation and at least one repeated webhook.

Common Integration Mistake

Never embed a privileged task-creation key in browser JavaScript or a public agent prompt.

Next Step

Implement one authentication flow against the canonical task lifecycle, inspect the real payloads and only then generalize the client for more capabilities or locations.

Implementation Notes for Authentication

API key model

When implementing api key model for Authentication, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Server-side credential storage

When implementing server-side credential storage for Authentication, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Scopes and permissions

When implementing scopes and permissions for Authentication, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Rotation

When implementing rotation for Authentication, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Auditability

When implementing auditability for Authentication, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Agent-specific spend limits

When implementing agent-specific spend limits for Authentication, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Test Matrix

A Authentication integration should be tested against more than the happy path. Include a valid request, invalid input, duplicate retry, no matching supply, worker exception, incomplete evidence and cancellation where the interface supports it. The result of each test should be observable in the canonical task object so developers can reconcile UI, API and agent behavior.