API reference

Secrets

Secrets per environment with versions and rollback, project tokens (Bearer chsm_…), restricted projects, an audit trail, rotation reminders, usage, and links that give a function or app env.SECRETS with no network call. Values are encrypted at rest with a key per team.

GET/v1/secrets/projects

List secrets projects#

The team's secrets projects (a restricted one only to those who may see it) and the plan's limits.

Credential: An API key or a dashboard session
Roles: Any role

Response

200object

projectsSecretProject[]required
- namestringrequired
- descriptionstring
- environmentsstring[]required
- rotate_daysinteger | null
- restrictedboolean
- secretsinteger
- tokensinteger
- linksinteger
- reads_30dinteger
- created_atstring (date-time)
- updated_atstring (date-time)
- accessstring
  what the caller may do with values
  one of none, read, write
limitsSecretLimits
- projectsinteger
- secretsinteger
- perProjectinteger
- secrets_usedinteger

Errors

Status	Description
400	Bad request: `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

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

POST/v1/secrets/projects

Create a secrets project#

Environments default to production, preview and development. restricted: true needs owner or admin.

Credential: An API key or a dashboard session
Roles: owner, admin, developer

Request body`application/json`

namestringrequired
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$
descriptionstring
up to 300 characters
environmentsstring[]
1–10 items
rotate_daysinteger | null
1–3650
restrictedboolean

Response

201SecretProjectCreated

namestringrequired
descriptionstring
environmentsstring[]required
rotate_daysinteger | null
restrictedboolean
secretsinteger
tokensinteger
linksinteger
reads_30dinteger
created_atstring (date-time)
updated_atstring (date-time)
accessstring
what the caller may do with values
one of none, read, write

Errors

Status	Description
400	Bad request: `bad_name`, `bad_environments`, `bad_days`, `bad_restricted`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`, `limit`
404	Not found: `not_found`
409	Conflict: `name_taken`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/secrets/projects" \
  -H "Authorization: Bearer $KEY" \
  -d '{"name":"STRIPE_KEY"}'

GET/v1/secrets/projects/{project}

Get a secrets project#

Settings and counts.

Credential: An API key or a dashboard session
Roles: Any role

Parameters

projectstringpathrequired
the secrets project's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Response

200SecretProject

namestringrequired
descriptionstring
environmentsstring[]required
rotate_daysinteger | null
restrictedboolean
secretsinteger
tokensinteger
linksinteger
reads_30dinteger
created_atstring (date-time)
updated_atstring (date-time)
accessstring
what the caller may do with values
one of none, read, write

Errors

Status	Description
400	Bad request: `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/secrets/projects/shop" \
  -H "Authorization: Bearer $KEY"

DELETE/v1/secrets/projects/{project}

Delete a secrets project#

With its secrets, versions and tokens. Refused while a function or app links it (409 linked).

Credential: An API key or a dashboard session
Roles: owner, admin
Step-up: With a dashboard session, a second factor confirmed in the last 10 minutes; API keys pass.

Parameters

projectstringpathrequired
the secrets project's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Response

200object

deletedstring

Errors

Status	Description
400	Bad request: `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`, `step_up_required`
404	Not found: `not_found`
409	Conflict: `linked`
500	`internal`: an unexpected failure

Example

curl -X DELETE "https://api.ibel.ai/v1/secrets/projects/shop" \
  -H "Authorization: Bearer $KEY"

PATCH/v1/secrets/projects/{project}

Change a secrets project#

Any of description, rotate_days, restricted (owner or admin) and name (owner or admin). Environments change with the environments routes.

Credential: An API key or a dashboard session
Roles: owner, admin, developer

Parameters

projectstringpathrequired
the secrets project's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Request body`application/json`

descriptionstring
up to 300 characters
rotate_daysinteger | null
1–3650
restrictedboolean
namestring
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$

Response

200SecretProject

namestringrequired
descriptionstring
environmentsstring[]required
rotate_daysinteger | null
restrictedboolean
secretsinteger
tokensinteger
linksinteger
reads_30dinteger
created_atstring (date-time)
updated_atstring (date-time)
accessstring
what the caller may do with values
one of none, read, write

Errors

Status	Description
400	Bad request: `nothing`, `use_environments`, `bad_name`, `bad_days`, `bad_restricted`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
409	Conflict: `name_taken`
500	`internal`: an unexpected failure

Example

curl -X PATCH "https://api.ibel.ai/v1/secrets/projects/shop" \
  -H "Authorization: Bearer $KEY" \
  -d '{"description":"…","rotate_days":1,"restricted":true,"name":"STRIPE_KEY"}'

POST/v1/secrets/projects/{project}/environments

Add an environment#

copy_from starts it with another environment's current values.

Credential: An API key or a dashboard session
Roles: owner, admin

Parameters

projectstringpathrequired
the secrets project's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Request body`application/json`

namestringrequired
pattern ^[a-z0-9]([a-z0-9-]{0,30}[a-z0-9])?$
copy_fromstring | null
pattern ^[a-z0-9]([a-z0-9-]{0,30}[a-z0-9])?$

Response

201objectCreated

environmentsstring[]
copiedinteger

Errors

Status	Description
400	Bad request: `bad_environment`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`, `limit`
404	Not found: `not_found`
409	Conflict: `exists`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/secrets/projects/shop/environments" \
  -H "Authorization: Bearer $KEY" \
  -d '{"name":"STRIPE_KEY"}'

DELETE/v1/secrets/projects/{project}/environments/{env}

Remove an environment#

And its values. Refused for the last one, or while a live token reads it.

Credential: An API key or a dashboard session
Roles: owner, admin
Step-up: With a dashboard session, a second factor confirmed in the last 10 minutes; API keys pass.

Parameters

projectstringpathrequired
the secrets project's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
envstringpathrequired
the environment
pattern ^[a-z0-9]([a-z0-9-]{0,30}[a-z0-9])?$

Response

200object

environmentsstring[]

Errors

Status	Description
400	Bad request: `bad_environment`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`, `step_up_required`
404	Not found: `not_found`
409	Conflict: `last_environment`, `in_use`
500	`internal`: an unexpected failure

Example

curl -X DELETE "https://api.ibel.ai/v1/secrets/projects/shop/environments/production" \
  -H "Authorization: Bearer $KEY"

GET/v1/secrets/projects/{project}/secrets

List secrets#

Also takes a project token (Bearer chsm_…). Names, types, versions per environment and rotation dates; never values. With values=1 and env, every value of that environment (SecretValues; needs step-up with a session).

Credential: An API key or a dashboard session
Roles: any role for names; values need developer or above (and access on a restricted project), or a project token

Parameters

projectstringpathrequired
the secrets project's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
valuesstringquery
1: the values of one environment
one of 1, true
envstringquery
the environment (default: the token's one environment, else development, else the project's first)
pattern ^[a-z0-9]([a-z0-9-]{0,30}[a-z0-9])?$

Response

200SecretList | SecretValues

projectstring
environmentsstring[]
secretsobject[]
- namestring
- descriptionstring
- typestring
  one of sensitive, plain
- rotate_daysinteger | null
- environmentsmap of object | null
- updated_atstring (date-time)
- updated_byobject
- rotation_duestring (date-time) | null
- rotation_overdueboolean
- created_atstring (date-time)

Errors

Status	Description
400	Bad request: `bad_environment`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`, `step_up_required`
404	Not found: `not_found`, `no_environment`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/secrets/projects/shop/secrets" \
  -H "Authorization: Bearer $KEY"

POST/v1/secrets/projects/{project}/secrets

Set many secrets#

Also takes a project token (Bearer chsm_…). secrets (an object) or dotenv (the text of a .env file), up to 500, all or nothing.

Credential: An API key or a dashboard session
Roles: owner, admin, developer (write access on a restricted project), or a write project token

Parameters

projectstringpathrequired
the secrets project's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Request body`application/json`

secretsmap of string
dotenvstring
environmentsstring[]
1–10 items
typestring
one of sensitive, plain
notestring
up to 200 characters

Response

201objectCreated

importedinteger
secretsSecretWritten[]
- namestring
- typestring
- versionsmap of integer

Errors

Status	Description
400	Bad request: `bad_secrets`, `bad_name`, `bad_value`, `bad_environment`, `bad_type`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`, `limit`
404	Not found: `not_found`
409	Conflict: `stays_sensitive`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/secrets/projects/shop/secrets" \
  -H "Authorization: Bearer $KEY" \
  -d '{"secrets":{"KEY":"s3cr3t"},"dotenv":"…","environments":["…"],"type":"sensitive","note":"…"}'

GET/v1/secrets/projects/{project}/secrets/{name}

Read a secret#

Also takes a project token (Bearer chsm_…). One value; version for an older one; masked=1 answers with the mask only (no read counted, no step-up). A session needs step-up for the value.

Credential: An API key or a dashboard session
Roles: any role for names; values need developer or above (and access on a restricted project), or a project token

Parameters

projectstringpathrequired
the secrets project's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
namestringpathrequired
the secret's name
pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}$ · up to 64 characters
envstringquery
the environment (default: the token's one environment, else development, else the project's first)
pattern ^[a-z0-9]([a-z0-9-]{0,30}[a-z0-9])?$
versionintegerquery
an older version's number
at least 1
maskedstringquery
1: the mask only
one of 1, true

Response

200SecretValue

namestring
environmentstring
versioninteger
typestring
updated_atstring (date-time)
valuestring | null
maskedstring
with masked=1: dots and the length, never a character of the value

Errors

Status	Description
400	Bad request: `bad_environment`, `bad_param`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`, `step_up_required`
404	Not found: `not_found`, `no_environment`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/secrets/projects/shop/secrets/STRIPE_KEY" \
  -H "Authorization: Bearer $KEY"

PUT/v1/secrets/projects/{project}/secrets/{name}

Set a secret#

Also takes a project token (Bearer chsm_…). A new version in each environment named (default: all of the project's, or all the token reaches).

Credential: An API key or a dashboard session
Roles: owner, admin, developer (write access on a restricted project), or a write project token

Parameters

projectstringpathrequired
the secrets project's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
namestringpathrequired
the secret's name
pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}$ · up to 64 characters

Request body`application/json`

valuestringrequired
1–5120 characters
environmentsstring[]
1–10 items
typestring
one of sensitive, plain · default "sensitive"
descriptionstring
up to 300 characters
rotate_daysinteger | null
1–3650
notestring
up to 200 characters

Response

200SecretWritten

namestring
typestring
versionsmap of integer

Errors

Status	Description
400	Bad request: `bad_value`, `bad_environment`, `bad_environments`, `bad_type`, `bad_days`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`, `limit`
404	Not found: `not_found`
409	Conflict: `stays_sensitive`
500	`internal`: an unexpected failure

Example

curl -X PUT "https://api.ibel.ai/v1/secrets/projects/shop/secrets/STRIPE_KEY" \
  -H "Authorization: Bearer $KEY" \
  -d '{"value":"s3cr3t"}'

DELETE/v1/secrets/projects/{project}/secrets/{name}

Delete a secret#

Also takes a project token (Bearer chsm_…). With its history; env removes it from one environment only (as a version that says so).

Credential: An API key or a dashboard session
Roles: owner, admin, developer (write access on a restricted project), or a write project token

Parameters

projectstringpathrequired
the secrets project's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
namestringpathrequired
the secret's name
pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}$ · up to 64 characters
envstringquery
remove it from this environment only
pattern ^[a-z0-9]([a-z0-9-]{0,30}[a-z0-9])?$

Response

200object

deletedstring
environmentstring

Errors

Status	Description
400	Bad request: `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl -X DELETE "https://api.ibel.ai/v1/secrets/projects/shop/secrets/STRIPE_KEY" \
  -H "Authorization: Bearer $KEY"

PATCH/v1/secrets/projects/{project}/secrets/{name}

Change a secret's settings#

Also takes a project token (Bearer chsm_…). Type (plain to sensitive only), description and rotate_days.

Credential: An API key or a dashboard session
Roles: owner, admin, developer (write access on a restricted project), or a write project token

Parameters

projectstringpathrequired
the secrets project's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
namestringpathrequired
the secret's name
pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}$ · up to 64 characters

Request body`application/json`

typestring
one of sensitive, plain
descriptionstring
up to 300 characters
rotate_daysinteger | null
1–3650

Response

200object

namestring
typestring
descriptionstring
rotate_daysinteger | null

Errors

Status	Description
400	Bad request: `bad_type`, `bad_days`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
409	Conflict: `stays_sensitive`
500	`internal`: an unexpected failure

Example

curl -X PATCH "https://api.ibel.ai/v1/secrets/projects/shop/secrets/STRIPE_KEY" \
  -H "Authorization: Bearer $KEY" \
  -d '{"type":"sensitive","description":"…","rotate_days":1}'

POST/v1/secrets/projects/{project}/secrets/{name}/rotate

Rotate a secret#

Also takes a project token (Bearer chsm_…). A new version with the value given, or a random one (length, default 40) returned once as value. Clears the rotation reminder.

Credential: An API key or a dashboard session
Roles: owner, admin, developer (write access on a restricted project), or a write project token
Step-up: With a dashboard session, a second factor confirmed in the last 10 minutes; API keys pass.

Parameters

projectstringpathrequired
the secrets project's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
namestringpathrequired
the secret's name
pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}$ · up to 64 characters

Request body`application/json`

valuestring
up to 5120 characters
lengthinteger
16–512
environmentsstring[]
1–10 items
notestring
up to 200 characters

Response

200SecretWritten

namestring
typestring
versionsmap of integer
valuestring
the generated value, shown once

Errors

Status	Description
400	Bad request: `bad_value`, `bad_length`, `bad_environment`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`, `step_up_required`, `limit`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/secrets/projects/shop/secrets/STRIPE_KEY/rotate" \
  -H "Authorization: Bearer $KEY" \
  -d '{"value":"s3cr3t","length":16,"environments":["…"],"note":"…"}'

GET/v1/secrets/projects/{project}/secrets/{name}/versions

A secret's versions#

Also takes a project token (Bearer chsm_…). Every kept version, newest first; env for one environment. Never values.

Credential: An API key or a dashboard session
Roles: any role for names; values need developer or above (and access on a restricted project), or a project token

Parameters

projectstringpathrequired
the secrets project's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
namestringpathrequired
the secret's name
pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}$ · up to 64 characters
envstringquery
one environment
pattern ^[a-z0-9]([a-z0-9-]{0,30}[a-z0-9])?$

Response

200object

namestring
versionsSecretVersion[]
- environmentstring
- versioninteger
- kindstring
  one of set, import, rotate, rollback, delete
- notestring
- currentboolean
- created_atstring (date-time)
- created_byobject | null

Errors

Status	Description
400	Bad request: `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/secrets/projects/shop/secrets/STRIPE_KEY/versions" \
  -H "Authorization: Bearer $KEY"

POST/v1/secrets/projects/{project}/secrets/{name}/rollback

Roll a secret back#

Also takes a project token (Bearer chsm_…). Version to's value becomes a new current version in env.

Credential: An API key or a dashboard session
Roles: owner, admin, developer (write access on a restricted project), or a write project token
Step-up: With a dashboard session, a second factor confirmed in the last 10 minutes; API keys pass.

Parameters

projectstringpathrequired
the secrets project's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
namestringpathrequired
the secret's name
pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}$ · up to 64 characters

Request body`application/json`

envstring
pattern ^[a-z0-9]([a-z0-9-]{0,30}[a-z0-9])?$
tointegerrequired
at least 1

Response

200SecretWritten

namestring
typestring
versionsmap of integer
rolled_back_tointeger

Errors

Status	Description
400	Bad request: `bad_version`, `bad_environment`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`, `step_up_required`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/secrets/projects/shop/secrets/STRIPE_KEY/rollback" \
  -H "Authorization: Bearer $KEY" \
  -d '{"to":1}'

GET/v1/secrets/projects/{project}/export

Every value of one environment#

Also takes a project token (Bearer chsm_…). For run -- and programs (a session needs step-up). plain=1 leaves sensitive values out and names them in withheld (what secrets pull uses). format=dotenv answers text/plain NAME="value" lines.

Credential: An API key or a dashboard session
Roles: any role for names; values need developer or above (and access on a restricted project), or a project token

Parameters

projectstringpathrequired
the secrets project's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
envstringquery
the environment (default: the token's one environment, else development, else the project's first)
pattern ^[a-z0-9]([a-z0-9-]{0,30}[a-z0-9])?$
plainstringquery
1: sensitive values left out
one of 1, true
formatstringquery
dotenv: text instead of JSON
one of dotenv

Response

200SecretExport

projectstring
environmentstring
valuesmap of string
withheldstring[]

Errors

Status	Description
400	Bad request: `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`, `step_up_required`
404	Not found: `not_found`, `no_environment`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/secrets/projects/shop/export" \
  -H "Authorization: Bearer $KEY"

GET/v1/secrets/projects/{project}/tokens

List a project's tokens#

Live, expired and revoked; never the secret.

Credential: An API key or a dashboard session
Roles: Any role

Parameters

projectstringpathrequired
the secrets project's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Response

200object

tokensSecretToken[]
- idstring
- namestring
- accessstring
  one of read, write
- environmentsstring[] | null
- expires_atstring (date-time) | null
- last_used_atstring (date-time) | null
- created_atstring (date-time)
- created_byobject | null
- revoked_atstring (date-time) | null
- statestring
  one of active, expired, revoked
limitinteger

Errors

Status	Description
400	Bad request: `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/secrets/projects/shop/tokens" \
  -H "Authorization: Bearer $KEY"

POST/v1/secrets/projects/{project}/tokens

Make a project token#

Read or write, all or some environments, optional expiry; never more than its maker reaches. The token is shown once.

Credential: An API key or a dashboard session
Roles: owner, admin, developer (with that access to each environment)
Step-up: With a dashboard session, a second factor confirmed in the last 10 minutes; API keys pass.

Parameters

projectstringpathrequired
the secrets project's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Request body`application/json`

namestring
up to 80 characters
accessstring
one of read, write · default "read"
environmentsstring[]
1–10 items
expires_in_daysinteger | null
1–3650

Response

201SecretTokenCreated

idstring
namestring
accessstring
one of read, write
environmentsstring[] | null
expires_atstring (date-time) | null
last_used_atstring (date-time) | null
created_atstring (date-time)
created_byobject | null
- typestring
  one of person, key, token
- idstring
- namestring | null
revoked_atstring (date-time) | null
statestring
one of active, expired, revoked
tokenstring
chsm_<id>_<secret>, shown once

Errors

Status	Description
400	Bad request: `bad_access`, `bad_environment`, `bad_environments`, `bad_days`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`, `step_up_required`, `limit`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/secrets/projects/shop/tokens" \
  -H "Authorization: Bearer $KEY" \
  -d '{"name":"STRIPE_KEY","access":"read","environments":["…"],"expires_in_days":1}'

DELETE/v1/secrets/projects/{project}/tokens/{id}

Revoke a project token#

At once on this API process, within 15 seconds on the others.

Credential: An API key or a dashboard session
Roles: owner, admin, developer

Parameters

projectstringpathrequired
the secrets project's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
idstringpathrequired
the token's id
pattern ^[0-9a-f]{12}$

Response

200object

revokedstring

Errors

Status	Description
400	Bad request: `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl -X DELETE "https://api.ibel.ai/v1/secrets/projects/shop/tokens/3f9a1c2b7d4e" \
  -H "Authorization: Bearer $KEY"

GET/v1/secrets/projects/{project}/access

Who reaches a project#

Every member with their role, their listing on a restricted project and what they may do; and the live tokens.

Credential: An API key or a dashboard session
Roles: Any role

Parameters

projectstringpathrequired
the secrets project's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Response

200object

restrictedboolean
peopleSecretAccessPerson[]
- idstring
- emailstring
- namestring
- rolestring
- listedstring | null
  one of read, write, null
- accessstring
  one of none, read, write
tokensSecretToken[]
- idstring
- namestring
- accessstring
  one of read, write
- environmentsstring[] | null
- expires_atstring (date-time) | null
- last_used_atstring (date-time) | null
- created_atstring (date-time)
- created_byobject | null
- revoked_atstring (date-time) | null
- statestring
  one of active, expired, revoked

Errors

Status	Description
400	Bad request: `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/secrets/projects/shop/access" \
  -H "Authorization: Bearer $KEY"

PUT/v1/secrets/projects/{project}/access/{person}

List a member on a project#

Read or write access on a restricted project.

Credential: An API key or a dashboard session
Roles: owner, admin

Parameters

projectstringpathrequired
the secrets project's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
personstring (uuid)pathrequired
the member's id

Request body`application/json`

accessstringrequired
one of read, write

Response

200object

personstring
emailstring
accessstring

Errors

Status	Description
400	Bad request: `bad_access`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl -X PUT "https://api.ibel.ai/v1/secrets/projects/shop/access/5b0f4c2e-8f1d-4a7e-9c3b-2d6e1f0a9b8c" \
  -H "Authorization: Bearer $KEY" \
  -d '{"access":"read"}'

DELETE/v1/secrets/projects/{project}/access/{person}

Unlist a member#

Takes the person off a project's list.

Credential: An API key or a dashboard session
Roles: owner, admin

Parameters

projectstringpathrequired
the secrets project's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
personstring (uuid)pathrequired
the member's id

Response

200object

removedstring

Errors

Status	Description
400	Bad request: `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl -X DELETE "https://api.ibel.ai/v1/secrets/projects/shop/access/5b0f4c2e-8f1d-4a7e-9c3b-2d6e1f0a9b8c" \
  -H "Authorization: Bearer $KEY"

GET/v1/secrets/projects/{project}/audit

A project's audit trail#

Every read, change, rotation, rollback, pull, export, token, access change and link; never a value. Identical reads in one minute are one event with a count.

Credential: An API key or a dashboard session
Roles: Any role

Parameters

projectstringpathrequired
the secrets project's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
limitintegerquery
events per page
1–500 · default 100
beforestringquery
the next of the last page
pattern ^\d{1,18}$
actionstringquery
one action (or its family, e.g. token)
secretstringquery
one secret
pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}$
envstringquery
one environment
pattern ^[a-z0-9]([a-z0-9-]{0,30}[a-z0-9])?$

Response

200SecretAudit

eventsobject[]
- idstring
- atstring (date-time)
- projectstring
- actionstring
- secretstring | null
- environmentstring | null
- versioninteger | null
- actorobject | null
- ipstring | null
- countinteger
nextstring | null

Errors

Status	Description
400	Bad request: `bad_param`, `bad_name`, `bad_environment`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/secrets/projects/shop/audit" \
  -H "Authorization: Bearer $KEY"

GET/v1/secrets/audit

The team's secrets audit trail#

As a project's, across every project.

Credential: An API key or a dashboard session
Roles: owner, admin

Parameters

limitintegerquery
events per page
1–500 · default 100
beforestringquery
the next of the last page
pattern ^\d{1,18}$
actionstringquery
one action (or its family)
secretstringquery
one secret
pattern ^[A-Za-z_][A-Za-z0-9_]{0,63}$
envstringquery
one environment
pattern ^[a-z0-9]([a-z0-9-]{0,30}[a-z0-9])?$

Response

200SecretAudit

eventsobject[]
- idstring
- atstring (date-time)
- projectstring
- actionstring
- secretstring | null
- environmentstring | null
- versioninteger | null
- actorobject | null
- ipstring | null
- countinteger
nextstring | null

Errors

Status	Description
400	Bad request: `bad_param`, `bad_name`, `bad_environment`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

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

GET/v1/secrets/projects/{project}/usage

A project's usage#

Reads and writes per day and this month, and secrets stored.

Credential: An API key or a dashboard session
Roles: Any role

Parameters

projectstringpathrequired
the secrets project's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
daysintegerquery
days back
1–90 · default 30

Response

200SecretUsage

projectstring
daysobject[]
- daystring
- readsinteger
- writesinteger
monthobject
- readsinteger
- writesinteger
secrets_storedinteger

Errors

Status	Description
400	Bad request: `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/secrets/projects/shop/usage" \
  -H "Authorization: Bearer $KEY"

GET/v1/secrets/usage

The team's secrets usage#

As a project's, for the whole team, with the plan and its included amounts. Meters: secrets_stored and secret_reads (prices in GET /v1/pricing); writes are counted, not priced.

Credential: An API key or a dashboard session
Roles: Any role

Parameters

daysintegerquery
days back
1–90 · default 30

Response

200SecretUsage

daysobject[]
- daystring
- readsinteger
- writesinteger
monthobject
- readsinteger
- writesinteger
secrets_storedinteger
planstring
includedobject
- secretsinteger
- readsinteger
- writesinteger

Errors

Status	Description
400	Bad request: `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

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

GET/v1/secrets/projects/{project}/links

Functions and apps reading a project#

Each with its mode and binding.

Credential: An API key or a dashboard session
Roles: Any role

Parameters

projectstringpathrequired
the secrets project's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Response

200object

linksSecretLink[]
- projectstring
- kindstring
- secrets_projectstring
- modestring
  one of binding, variables
- bindingstring | null
- created_atstring (date-time)

Errors

Status	Description
400	Bad request: `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/secrets/projects/shop/links" \
  -H "Authorization: Bearer $KEY"

POST/v1/secrets/projects/{project}/links

Link a function or app#

It reads the project with no network call: binding mode gives env.SECRETS.get("NAME") and env.SECRETS.list(); variables gives each secret as env.NAME (a project or team variable of the same name wins). Production deployments get the production values, previews the preview values. One project per function or app.

Credential: An API key or a dashboard session
Roles: owner, admin, developer (with read access to production and preview)

Parameters

projectstringpathrequired
the secrets project's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Request body`application/json`

projectstringrequired
the function's or app's name
modestring
one of binding, variables · default "binding"
bindingstring
pattern ^[A-Z_][A-Z0-9_]{0,63}$ · default "SECRETS"

Response

201SecretLinkCreated

projectstring
kindstring
secrets_projectstring
modestring
one of binding, variables
bindingstring | null
created_atstring (date-time)

Errors

Status	Description
400	Bad request: `bad_project`, `bad_mode`, `bad_binding`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
409	Conflict: `linked`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/secrets/projects/shop/links" \
  -H "Authorization: Bearer $KEY" \
  -d '{"project":"shop"}'

DELETE/v1/secrets/projects/{project}/links/{function}

Unlink a function or app#

It stops reading the project at once.

Credential: An API key or a dashboard session
Roles: owner, admin, developer

Parameters

projectstringpathrequired
the secrets project's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
functionstringpathrequired
the function's or app's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$

Response

200object

unlinkedstring

Errors

Status	Description
400	Bad request: `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl -X DELETE "https://api.ibel.ai/v1/secrets/projects/shop/links/function" \
  -H "Authorization: Bearer $KEY"

GET/v1/secrets/links

The links of a function or app#

Which secrets project it reads (the environment variables page).

Credential: An API key or a dashboard session
Roles: Any role

Parameters

projectstringquery
the function's or app's name

Response

200object

linksSecretLink[]
- projectstring
- kindstring
- secrets_projectstring
- modestring
  one of binding, variables
- bindingstring | null
- created_atstring (date-time)

Errors

Status	Description
400	Bad request: `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

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

List secrets projects#

Response

Errors

Example

Create a secrets project#

Request bodyapplication/json

Response

Errors

Example

Get a secrets project#

Parameters

Response

Errors

Example

Delete a secrets project#

Parameters

Response

Errors

Example

Change a secrets project#

Parameters

Request bodyapplication/json

Response

Errors

Example

Add an environment#

Parameters

Request bodyapplication/json

Response

Errors

Example

Remove an environment#

Parameters

Response

Errors

Example

List secrets#

Parameters

Response

Errors

Example

Set many secrets#

Parameters

Request bodyapplication/json

Response

Errors

Example

Read a secret#

Parameters

Response

Errors

Example

Set a secret#

Parameters

Request bodyapplication/json

Response

Errors

Example

Delete a secret#

Parameters

Response

Errors

Example

Change a secret's settings#

Parameters

Request bodyapplication/json

Response

Errors

Example

Rotate a secret#

Parameters

Request bodyapplication/json

Response

Errors

Example

A secret's versions#

Parameters

Response

Errors

Example

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`