check

Make an app-facing authorization decision against the derived relationship state. This command verifies the feed, derives state, and evaluates whether a subject meets the specified requirements. ak allow is an alias for ak check.

Usage

ak check [FLAGS]
ak allow [FLAGS]

Flags

Flag	Required	Default	Description
--sig <PATH_OR_URL>	Yes	—	SIG metadata path or URL.
--subject <DID>	Yes	—	Subject DID to check.
--require <KEY=VALUE>	Yes	—	Predicate to evaluate. Repeatable.
--format <FORMAT>	No	json	Output format: json or text.
--explain	No	—	Include an explanation trace in the output.

Requirements

The --require flag accepts key-value predicates. It can be specified multiple times, and all predicates must match for the decision to be allow.

Predicate	Example	Description
relationship=<TYPE>	relationship=employee	Subject must have an active relationship of this type.
role=<NAME>	role=deploy	Subject must hold this role in an active relationship.

Exit Codes

Code	Meaning
0	Allow — the subject meets all requirements.
1	Deny — the subject does not meet one or more requirements.
2	Error — a verification or processing error occurred.

JSON Output

When using --format json (the default), the output includes:

{
  "decision": "allow",
  "subject": "did:web:alice.example.com",
  "requirements": [
    { "key": "relationship", "value": "employee" },
    { "key": "role", "value": "deploy" }
  ],
  "matched_relationship_id": "rel-alice-eng",
  "last_sequence": 3
}

Examples

Allow decision

ak check \
  --sig ./issuer-root/.well-known/sig.json \
  --subject did:web:alice.example.com \
  --require relationship=employee \
  --require role=deploy

Exit code: 0

{
  "decision": "allow",
  "subject": "did:web:alice.example.com",
  "requirements": [
    { "key": "relationship", "value": "employee" },
    { "key": "role", "value": "deploy" }
  ],
  "matched_relationship_id": "rel-alice-eng",
  "last_sequence": 3
}

Deny decision

ak check \
  --sig ./issuer-root/.well-known/sig.json \
  --subject did:web:bob.example.com \
  --require relationship=employee

Exit code: 1

{
  "decision": "deny",
  "subject": "did:web:bob.example.com",
  "requirements": [
    { "key": "relationship", "value": "employee" }
  ],
  "matched_relationship_id": null,
  "last_sequence": 3
}

Explain mode

The --explain flag adds a trace showing how the decision was reached:

ak check \
  --sig ./issuer-root/.well-known/sig.json \
  --subject did:web:alice.example.com \
  --require relationship=employee \
  --require role=admin \
  --explain

Exit code: 1

{
  "decision": "deny",
  "subject": "did:web:alice.example.com",
  "requirements": [
    { "key": "relationship", "value": "employee" },
    { "key": "role", "value": "admin" }
  ],
  "matched_relationship_id": null,
  "last_sequence": 3,
  "explanation": [
    "Found active relationship rel-alice-eng (type=employee)",
    "Requirement relationship=employee: satisfied by rel-alice-eng",
    "Requirement role=admin: not satisfied, available roles are [engineer, deploy]",
    "Decision: deny (1 of 2 requirements met)"
  ]
}

Text format

ak check \
  --sig ./issuer-root/.well-known/sig.json \
  --subject did:web:alice.example.com \
  --require relationship=employee \
  --format text

ALLOW did:web:alice.example.com (relationship=employee) via rel-alice-eng

Notes

• All requirements must be satisfied for an allow decision. If any single predicate fails, the result is deny.
• The check runs a full feed verification before evaluating requirements. If verification fails, the exit code is 2.
• Use --explain during development and debugging to understand why a decision was reached.
• The allow alias is provided as a convenience for scripts where the intent reads more naturally (e.g., ak allow --subject ... --require ...).