Skip to content

Authentication and API keys

An API key is the credential a system — not a person — uses to read one tenant's data. A tenant can have several, each with its own name, scopes, and expiry.

Authenticating on behalf of a user?

If your integration needs to act as a specific HodeiShield user — a CLI, an assistant — rather than as a standalone system, use OAuth instead.

Create a key

From the console: Settings › Integrations and development › Integrations › API Key. Only administrators (organization or tenant) can create and manage keys; every other role gets 403.

When creating one, you set:

Field Rule
name 1–80 characters
scopes list of scopes (see below); an unknown scope is rejected
expiresInDays 1 to 730 days, or never-expiring (not recommended)

The response shows the plaintext token once, shaped like hsk_…. Store it in your secrets manager: if it's lost, the only recovery is rotating the key.

Using it

Authorization: Bearer hsk_...
sequenceDiagram
    participant C as Your system
    participant A as HodeiShield API

    C->>A: GET /v1/... (Authorization: Bearer hsk_...)
    Note over A: Checks run in this order; the first one that fails answers.
    alt key missing, revoked, expired, or unknown
        A-->>C: 401
    else key, tenant or service quota exhausted
        A-->>C: 429 (Retry-After)
    else invalid path or query parameter
        A-->>C: 400
    else the operation's required scope is missing
        A-->>C: 403 (required scope named in the detail)
    else all checks pass
        A-->>C: 200 (or 404 if the resource does not exist) + RateLimit-Limit / -Remaining / -Reset
    end

Scopes

A scope has the shape <module>:read or <module>:write — e.g. supply_risk:read, evidence:read, or compliance.nis2:read. Two important rules:

  • No scope implies another. Reading and writing require two separate scopes.
  • Compliance is per framework. compliance.nis2:read does not grant access to ENS data.

  • Resource scopes. changes:read (read-only, no changes:write exists) reads the change-management register at GET /v1/changes. incidents:read reads the incident register at GET /v1/incidents, and ai_systems:read the register of AI systems at GET /v1/ai-systems; both are read-only, and neither supply_risk:read nor ai_governance:read stands in for them.

  • alerts:write acknowledges and resolves alerts (see below). It is never implied by a read scope, and it implies none.
  • risks:write moves a risk-register entry along its lifecycle (POST /v1/risks/{id}/transition). Like alerts:write it is explicit: no read scope (supply_risk:read included) implies it, it implies none, and existing keys do not gain it. It needs the supply_risk module active. Only a tenant administrator can grant it, and the key acts with the role of the user who created it, read on every request. An MSSP portfolio key holds it only if an administrator of the MSSP organisation granted it.
  • act:decide is an OAuth-only scope, never a key scope. It lists and decides the action proposals you could approve (GET /v1/act/inbox, POST /v1/act/proposals/{id}/approve and .../reject) and is issued only to the HodeiShield CLI, and only while the server enables it. It is opt-in: the CLI does not ask for it by default, only on a sign-in you make in order to decide, and the approval screen shows it. A decision needs a sign-in confirmed within the last 15 minutes (step-up: your second factor or password); after that the CLI has to sign in again (403 STEP_UP_REQUIRED). Approving never executes the action: it only consents to executing it in the console within 15 minutes. The inbox lists only the proposals you can approve with your own role. Keys, portfolio keys, the MCP server and other applications are refused (403 CREDENTIAL_NOT_ALLOWED).
  • email is an OAuth scope, not a module scope: it only changes whether GET /v1/me returns user.email to a user token (see OAuth).

A missing scope returns 403, with the detail naming the scope that was required.

The module must be active

Holding the scope is not enough: the module it names must also be active for the tenant at the time of the request, and a compliance.<framework> scope also needs that framework activated (changes:read needs at least one activated compliance framework; incidents:read needs the supply_risk module and ai_systems:read the ai_governance module). This applies to tenant API keys and portfolio keys as to OAuth tokens. When it is not, the answer is 403 with error.details.code MODULE_NOT_ENTITLED, error.details.scopes and error.details.modules, plus error.details.frameworks when the framework is in the plan but not activated. A new key does not help: the module has to be active again. The refused use is recorded in the tenant's audit log. See Errors.

Acknowledge and resolve alerts (alerts:write)

alerts:write lets a system — typically a SOAR — acknowledge and resolve supply-chain alerts through /v1. It is an explicit write scope: no read scope (supply_risk:read included) implies it, it implies no read scope (a key holding only alerts:write cannot read alert content), and existing keys do not gain it. You tick it yourself when you create the key; the creation form marks it as a write scope. It needs the supply_risk module active, like the alert reads.

Who can grant it. The user creating (or rotating) the key must hold a role that can resolve alerts in the console. No interactive confirmation is asked at call time, because the caller is an automation, so the role is checked when the scope is granted. On an MSSP portfolio key (hsp_…) only an organization administrator of the provider can grant it, because the key then acts in every client of its set; an MSSP analyst cannot. A portfolio key that carries it must have an expiry, like every portfolio key.

The acting role. A key acts as the user who created it, with that user's role read on every request. Rotating a key makes the rotating user the successor's creator. If that user is demoted, suspended, deleted or removed from the tenant (for a portfolio key: removed from the provider, or no longer reaching that client), the key loses the power at once and answers 403 (WRITE_ACTOR_UNRESOLVED or ROLE_NOT_PERMITTED). The console's role-by-severity rule applies: an MSSP analyst's key closes medium and low alerts only; critical and high need a creator who could close them in the console.

Acknowledge

curl -X POST "https://api.hodeishield.com/v1/alerts/$ALERT_ID/acknowledge" \
  -H "Authorization: Bearer $HODEISHIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Triaged by playbook PB-114"}'

The body is optional; reason (at most 500 characters) is kept in the audit trail.

Resolve

curl -X POST "https://api.hodeishield.com/v1/alerts/$ALERT_ID/resolve" \
  -H "Authorization: Bearer $HODEISHIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Patched and verified"}'

reason is required (at least two non-blank characters, at most 500) and becomes the alert's resolution_reason. With a portfolio key, add -H "X-HS-Tenant: <client tenant id>" exactly as on the reads: a tenant outside the key's client set answers 404 (TENANT_NOT_FOUND).

Both answer 200 with the alert's state after the request, never its content:

{
  "data": {
    "id": "33333333-3333-4333-8333-333333333333",
    "status": "resolved",
    "acknowledged_at": "2026-11-12T10:15:00Z",
    "resolved_at": "2026-11-12T10:42:00Z",
    "resolution_reason": "Patched and verified",
    "updated_at": "2026-11-12T10:42:00Z"
  },
  "changed": true
}

Errors

Status error.details.code When
400 Body is not a JSON object, has an unknown key, or reason is missing, too short or over 500 characters
403 INSUFFICIENT_SCOPE The key does not carry alerts:write
403 ROLE_NOT_PERMITTED The creator's role may not triage alerts, or is an MSSP analyst and the alert is critical or high
403 WRITE_ACTOR_UNRESOLVED The creator no longer exists, is not active or no longer reaches the tenant; nothing was written
403 LICENCE_INACTIVE The licence is in its grace period (writes are refused; reads are not)
404 The alert does not exist in that tenant (an id of another tenant looks the same), or TENANT_NOT_FOUND for a tenant outside a portfolio key's set
409 ALERT_RESOLVED Acknowledge of an alert that is already resolved
409 ALERT_STATE_CHANGED The alert changed between the read and the write of your request; read it again and decide
429 error.details.scope is write_key (the key's write budget) or service

Repeating a request

Both operations are idempotent. Repeating a change already made answers 200 with the current state and "changed": false, and writes nothing: acknowledging an acknowledged alert, or resolving a resolved one (the first reason stays). changed: true means this request made the change. A 409 ALERT_STATE_CHANGED means someone else changed the alert at the same moment: read it with GET /v1/alerts/{id} and decide; do not blindly retry.

Audit and rate limit

Every change writes one entry in the tenant's audit trail (see Audit log) with the key id (never the secret), the acting user, the alert, the old and new status and the reason. A repeat that changes nothing writes none. Writes have their own request budget per key, separate from the read limits, so a burst of reads never spends it and the reverse; see Rate limits.

Rotating a key

Rotating creates a successor key with the same name and scopes, and keeps the previous key alive for a configurable overlap window (0 to 30 days) so you can migrate your systems without downtime. Once the window closes, the previous key stops authenticating.

Revoking a key

Revocation is immediate and idempotent: a revoked, expired, or unknown key always returns the same 401, without distinguishing the reason in the response.

Per-license quotas

API quotas depend on your tenant's license tier. Every authenticated response includes the RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers; exceeding the quota returns 429 with Retry-After. Use those headers to adapt your client at runtime, rather than hardcoding the limit.