Authentication

The public API authenticates with API tokens — opaque strings that look like hly_<key_id>_<secret>. Every request carries one in the standard Authorization header:

Authorization: Bearer hly_ab12cd34ef56_xW3...redacted...9q

A token acts as you: it can do anything your account can, narrowed by the token’s scopes. It can never exceed your real access — Halyard always checks both the token’s scopes and your underlying permissions on each resource.

Creating a token

Create, list, and revoke tokens from your account settings in the app, or via the API itself:

curl -s https://api.halyard-ai.com/api/v1/me/tokens \
  -H "Authorization: Bearer $HALYARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "ci-deploy-bot",
        "scopes": ["projects:read", "issues:write"],
        "expires_in_days": 90
      }'

The response includes the full token once — store it immediately (e.g. in your secret manager). Only a masked record is retrievable afterward:

{
  "id": "…",
  "name": "ci-deploy-bot",
  "key_id": "ab12cd34ef56",
  "scopes": ["projects:read", "issues:write"],
  "expires_at": "2026-09-24T00:00:00Z",
  "plaintext": "hly_ab12cd34ef56_xW3...9q"
}

You can only grant scopes you already hold, so a scoped token can never mint a more powerful one.

Scopes

Scopes are <resource>:<action> where action is read, write, or admin, and a higher action implies the lower ones on the same resource (admin ⊇ write ⊇ read).

Resource	read	write	admin
projects	list / get	create / update	delete
issues	list / get	create / update	delete
enclaves	list / get	create / update	delete
sessions	list / get status	—	—
library	read documents	add documents	—
configs	read project config	—	—

A token created with no scopes can do nothing (least privilege). Request the narrowest set that does the job.

Rotating and revoking

• Rotate (POST /me/tokens/{id}/rotate) mints a replacement with the same scopes and revokes the old one in a single step.
• Revoke (DELETE /me/tokens/{id}) disables a token immediately.

Keep tokens safe

• Treat a token like a password. Don’t commit it; load it from the environment or a secret manager.
• Prefer short-lived, least-privilege tokens for automation.
• Halyard participates in secret scanning: tokens leaked in public repositories are detected by their hly_ prefix and auto-revoked.