Skip to content

Follow the final API document; clearer refusals, key expiry and deprecation warnings - #280

Merged
Gorka Gonzalo (d0ubl3g) merged 7 commits into
devfrom
feat/api-contract-m24
Nov 16, 2026
Merged

Gorka Gonzalo (d0ubl3g) merged 7 commits into
devfrom
feat/api-contract-m24

Conversation

@d0ubl3g

Copy link
Copy Markdown
Contributor

Changes you will see as a user:

  • The generated /v1 client follows the final API document for version 2026-11-15.
    Alerts now carry their MITRE ATT&CK mapping: alerts list --json shows
    mitre_techniques and mitre_mapping, and --csv has two more columns at the end.
  • hodeishield whoami shows when a tenant API key expires, as a "Key expires" line and a
    credential_expires_at field in --json. It warns on standard error when the key
    expires within 14 days or has already expired.
  • Some refusals now say why and what to do about it, and exit with code 4: a request from
    an IP address that is not allowed, an account that must enrol multi-factor
    authentication, and a tenant plan that does not include API or CLI access. A device
    sign-in refused because of the plan shows the same message. Any other refusal reason
    shows the API's own message, also with exit code 4.
  • When the API refuses a query parameter it does not know, the message names the unknown
    parameter and the accepted ones.
  • A warning on standard error, at most once per run, when the API marks a request as
    deprecated.
  • A new test checks that every query parameter the client can send is declared in the
    vendored API document.
  • README and CHANGELOG are updated.

Refresh the vendored OpenAPI document and the generated client. The
document now also describes an operation that writes; the CLI reads only,
so the generator skips operations that are not GET.

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
…asons

A 403 whose reason is IP_NOT_ALLOWED or MFA_ENROLLMENT_REQUIRED now says
what is wrong and what to do about it. Any other reason code the API sends
shows the API's own message. All of them keep exit code 4.

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
When the API refuses a request because of a query parameter it does not
know, the error now lists the unknown name or names and the ones the API
accepts. A new test checks that every query parameter the client can send
is declared in the vendored API document.

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
whoami shows the key's expiry (a `Key expires` line, and the additive
credential_expires_at field in --json, null for no expiry) and warns on
standard error when the key expires within 14 days or has expired.

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
The client reports the Deprecation and Sunset headers of an answer, and
the CLI prints one warning on standard error per run when it sees one.

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
…ation warning

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
… document

A refusal with the PLAN_WITHOUT_API reason, and a device sign-in refused for the same
reason, now say the tenant's plan does not include API or CLI access and where the
plan can be changed. The vendored API document is the final one for 2026-11-15; alerts
now carry their MITRE ATT&CK mapping.

Signed-off-by: d0ubl3g <48954024+d0ubl3g@users.noreply.github.com>
@d0ubl3g
Gorka Gonzalo (d0ubl3g) merged commit 7e09131 into dev Nov 16, 2026
23 checks passed
@d0ubl3g
Gorka Gonzalo (d0ubl3g) deleted the feat/api-contract-m24 branch November 16, 2026 08:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant