Skip to main content

API authentication

The current commercial pilot implements its identity model with role-bound bearer credentials. Each credential creates one accountable actor and one separated workflow role.

Implemented behavior​

  • Send credentials as Authorization: Bearer <token>.
  • A token contains 32 to 256 printable ASCII bytes without spaces.
  • The private credential file stores only the SHA3-256 token digest.
  • Every credential maps to one actor ID and exactly one role.
  • The server derives actor identity from the credential and transition time from its own clock. Requests cannot supply either value.
  • Missing or invalid credentials return 401 Unauthorized; a valid actor attempting an action outside its role receives 403 Forbidden.
  • The operator console keeps the token in browser sessionStorage, which is cleared when the tab is closed.

The supported roles are initiator, approver, security_admin, executor, and auditor. A single credential cannot combine these roles.

Credential record​

{
  "schema_version": 1,
  "credentials": [
    {
      "actor_id": "partner-approver-01",
      "roles": ["approver"],
      "token_sha3_256": "<64 lowercase hexadecimal characters>"
    }
  ]
}

Generate the secret and its stored digest outside the repository:

TOKEN=$(openssl rand -hex 32)
printf '%s' "$TOKEN" | openssl dgst -sha3-256

The clear token is delivered to its named actor through an approved secret channel. It must not be committed, included in evidence exports, sent in query parameters, or copied into support logs.

Onboarding check​

After the private credential file is installed and the pilot service is started, the actor verifies its identity and role:

curl https://<pilot-host>/v1/session \
  -H "Authorization: Bearer $TOKEN"

The returned actor ID and role must match the jointly approved role map before workflow testing begins.

Pilot rotation procedure​

  1. Generate a new random token and digest.
  2. Add the replacement digest to the private credential file for the same actor and role.
  3. Restart the controlled pilot service and verify /v1/session with the new token.
  4. Remove the old digest, restart again, and confirm the old token returns 401.
  5. Record the change time, operator, actor, and validation result outside the credential file.

The current service loads credentials at startup, so pilot rotation uses a controlled file update and service restart.

Production requirements​

The enterprise deployment profile adds agreed TLS or private-mesh termination, secret-manager ownership, automated expiry and revocation, rate limiting, credential-rotation evidence, and a selected identity mechanism such as OAuth, partner mTLS, workload identity, or hardware-backed credentials.