Skip to content
cloudhostDocs
API reference

Account and keys

The calling credential, API keys and the audit log.

GET/v1/healthz

Is the API up#

Credential
None

Response

200Ok

  • okbooleanrequired

Errors

StatusDescription
500internal: an unexpected failure

Example

curl "https://api.ibel.ai/v1/healthz"
GET/v1/whoami

The calling credential#

Credential
An API key or a dashboard session
Roles
Any role

Response

200WhoAmI

  • accountstring (uuid)required
  • teamstringrequired
  • emailstringrequired
  • keystringrequired

    key id, or s:<session id>

  • rolestringrequired

    one of owner, admin, developer, billing, viewer

Errors

StatusDescription
401unauthorized: missing, invalid, expired or revoked credential
500internal: an unexpected failure

Example

curl "https://api.ibel.ai/v1/whoami" \
  -H "Authorization: Bearer $KEY"
GET/v1/keys

List API keys#

Never the secrets; revoked keys included.

Credential
An API key or a dashboard session
Roles
Any role

Response

200object

  • keysKey[]required
    • idstringrequired

      pattern ^[0-9a-f]{12}$

    • namestringrequired
    • rolestringrequired

      one of owner, admin, developer, billing, viewer

    • created_atstring (date-time)required
    • created_bystring | null

      person:<uuid>, key:<id>, build:<uuid> or device

    • last_used_atstring (date-time) | null
    • expires_atstring (date-time) | null
    • revoked_atstring (date-time) | null
    • replaced_bystring | null

Errors

StatusDescription
401unauthorized: missing, invalid, expired or revoked credential
500internal: an unexpected failure

Example

curl "https://api.ibel.ai/v1/keys" \
  -H "Authorization: Bearer $KEY"
POST/v1/keys

Make an API key#

The key is returned once.

Credential
An API key or a dashboard session
Roles
owner, admin, developer (no wider than the caller; not a build's key)
Step-up
With a dashboard session, a second factor confirmed in the last 10 minutes; API keys pass.

Request bodyapplication/json

  • namestring

    up to 100 characters

  • rolestring

    one of owner, admin, developer, billing, viewer

  • expires_in_daysinteger

    1–3650

Response

201KeyCreated

  • idstringrequired
  • namestringrequired
  • rolestringrequired

    one of owner, admin, developer, billing, viewer

  • expires_atstring (date-time) | null
  • keystringrequired

    the full chk_ key, shown once

Errors

StatusDescription
400Bad request: bad_role, bad_expiry, bad_json
401unauthorized: missing, invalid, expired or revoked credential
403Not allowed: forbidden, role_too_wide, step_up_required
500internal: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/keys" \
  -H "Authorization: Bearer $KEY" \
  -d '{"name":"ci","role":"owner","expires_in_days":1}'
DELETE/v1/keys/{id}

Revoke a key#

Credential
An API key or a dashboard session
Roles
any for its own key; owner or admin for others (never a wider key)
Step-up
With a dashboard session, a second factor confirmed in the last 10 minutes; API keys pass.

Parameters

  • idstringpathrequired

    key id

    pattern ^[0-9a-f]{12}$

Response

200object

  • idstring
  • revokedboolean

Errors

StatusDescription
401unauthorized: missing, invalid, expired or revoked credential
403Not allowed: forbidden, step_up_required
404Not found: not_found
500internal: an unexpected failure

Example

curl -X DELETE "https://api.ibel.ai/v1/keys/7e5926b6f29c" \
  -H "Authorization: Bearer $KEY"
POST/v1/keys/{id}/rotate

Rotate a key#

A new key with the same name, role and expiry; the old one works for 24 hours more.

Credential
An API key or a dashboard session
Roles
owner, admin, developer (not a wider key; not a build's key)
Step-up
With a dashboard session, a second factor confirmed in the last 10 minutes; API keys pass.

Parameters

  • idstringpathrequired

    key id

    pattern ^[0-9a-f]{12}$

Response

201KeyRotated

  • idstringrequired
  • namestring
  • rolestring

    one of owner, admin, developer, billing, viewer

  • keystringrequired

    shown once

  • old_key_valid_untilstring (date-time)required

Errors

StatusDescription
401unauthorized: missing, invalid, expired or revoked credential
403Not allowed: forbidden, role_too_wide, step_up_required
404Not found: not_found
500internal: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/keys/7e5926b6f29c/rotate" \
  -H "Authorization: Bearer $KEY"
GET/v1/audit

Audit log#

Credential
An API key or a dashboard session
Roles
Any role

Parameters

  • limitintegerquery

    1-500, default 100

    1–500 · default 100

  • beforeintegerquery

    an event id; only older events (paging with next_before)

  • personstringquery

    person:<uuid> or key:<id>

  • projectstringquery

    a project name

  • typestringquery

    one of deploy, project, env, domain, store, team, key, alert, billing, auth, support

  • fromstringquery

    a day (2026-11-04, in the caller's time zone) or an ISO 8601 time

  • tostringquery

    a day (included) or an ISO 8601 time

Response

200object

  • eventsAuditEvent[]required
  • actorsmap of Actor
  • next_beforeinteger | null

Errors

StatusDescription
400Bad request: bad_param
401unauthorized: missing, invalid, expired or revoked credential
500internal: an unexpected failure

Example

curl "https://api.ibel.ai/v1/audit" \
  -H "Authorization: Bearer $KEY"
GET/v1/audit/actors

People and keys in the activity#

The people and API keys that appear in the last 180 days of activity.

Credential
An API key or a dashboard session
Roles
Any role

Response

200object

  • actorsobject[]required
    • valuestring
    • kindstring
    • idstring
    • namestring | null
    • emailstring | null

Errors

StatusDescription
401unauthorized: missing, invalid, expired or revoked credential
500internal: an unexpected failure

Example

curl "https://api.ibel.ai/v1/audit/actors" \
  -H "Authorization: Bearer $KEY"
GET/v1/audit/last

Who created and who last changed named things#

One request for a page of names (up to 200, comma-separated).

Credential
An API key or a dashboard session
Roles
Any role

Parameters

  • targetsstringqueryrequired

    names or ids separated by commas

Response

200object

  • targetsmap of objectrequired
  • actorsmap of Actor

Errors

StatusDescription
401unauthorized: missing, invalid, expired or revoked credential
500internal: an unexpected failure

Example

curl "https://api.ibel.ai/v1/audit/last?targets=targets" \
  -H "Authorization: Bearer $KEY"