Skip to content
NebulaCtrlInstall

Reference

View as Markdown

Secret managers API

5 operations. Every call needs a session cookie or an Authorization: Bearer nct_… token unless marked Public. Conventions, errors and scopes

GET/secret-managers

List the team's external secret manager integrations

Variables reference a secret as ${{vault:<name>/<path>#<key>}} or, for Doppler, ${{doppler:<name>/<project>/<config>#<key>}}. The value is fetched when a deploy sends its command and is never stored. Credentials are never returned (secretSet only). scope and grants say which projects and environments may reference the integration.

Response 200 · OK · application/json
ListOutputBody
  • SecretManager[] | nullrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/secret-managers

Add a secret manager integration

HashiCorp Vault / OpenBao: KV v2 with a token or AppRole. Infisical: a machine identity (universal auth). Doppler: a service token (bound to one config) or a personal / service account token. Nothing contacts the manager until the test or the first deploy that references it. Admin scope.

Request body · application/json · required
CreateInputBody
  • addressstring
    Vault or OpenBao address, e.g. https://vault.example.com:8200
  • approleMountstring
    AppRole auth mount (default approle)
  • authMethodenum: token | approle
    token (default) or approle
  • caCertstring
    PEM certificate(s) to trust for a private CA (public material)
  • clientIdstring
    Machine identity client id (universal auth)
  • defaultConfigstring
    Doppler config used by references that name none (with defaultProject)
  • defaultProjectstring
    Doppler project used by references that name none, like doppler:<name>#KEY. Set with defaultConfig, or leave both empty (a service token is bound to one config)
  • ScopeGrant[] | null
    With scope selected: the projects (or single environments) allowed to reference the integration. At least one.
  • kindenum: vault | infisical | dopplerrequired
    vault covers HashiCorp Vault and OpenBao (KV v2); doppler is Doppler (service token, or a personal / service account token with a project and config)
  • mountstring
    KV v2 mount path (default secret)
  • namestringrequired
    Lowercase letters, digits and dashes; it appears in references as vault:<name>/… or doppler:<name>/…
  • namespacestring
    Vault Enterprise / OpenBao namespace (X-Vault-Namespace)
  • organizationSlugstring
    Optional organization slug to scope the login to
  • projectIdstring
    Infisical project id
  • roleIdstring
    AppRole role id
  • scopeenum: team | selected
    team (default on create): every project may reference the integration. selected: only the projects and environments in grants. Omit on update to keep the stored scope.
  • secretstring
    Write-only: the Vault token (token auth), the AppRole secret id, the Infisical client secret or the Doppler token. Omit on update to keep the stored one.
  • siteUrlstring
    Infisical URL (default https://us.infisical.com) or Doppler API URL (default https://api.doppler.com)
Response 201 · Created · application/json
SecretManager
  • SecretManagerConfigrequired
  • createdAtstring (date-time)required
  • examplestringrequired
    A reference in this integration's syntax
  • ScopeGrant[] | nullrequired
    With scope selected: the projects and environments that may reference the integration
  • idstringrequired
  • kindenum: vault | infisical | dopplerrequired
  • SecretManagerLastTestrequired
  • namestringrequired
    Used in references: ${{vault:<name>/<path>#<key>}} or ${{doppler:<name>/<project>/<config>#<key>}}
  • scopeenum: team | selectedrequired
  • secretSetbooleanrequired
  • updatedAtstring (date-time)required
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

PUT/secret-managers/{id}

Update a secret manager integration

The name and kind are fixed. Changing the address, auth method or identity requires the credential again. Omitting scope keeps the stored scope and grants. Admin scope.

ParameterInTypeDescription
idrequiredpathstring
Request body · application/json · required
SecretManagerBody
  • addressstring
    Vault or OpenBao address, e.g. https://vault.example.com:8200
  • approleMountstring
    AppRole auth mount (default approle)
  • authMethodenum: token | approle
    token (default) or approle
  • caCertstring
    PEM certificate(s) to trust for a private CA (public material)
  • clientIdstring
    Machine identity client id (universal auth)
  • defaultConfigstring
    Doppler config used by references that name none (with defaultProject)
  • defaultProjectstring
    Doppler project used by references that name none, like doppler:<name>#KEY. Set with defaultConfig, or leave both empty (a service token is bound to one config)
  • ScopeGrant[] | null
    With scope selected: the projects (or single environments) allowed to reference the integration. At least one.
  • mountstring
    KV v2 mount path (default secret)
  • namespacestring
    Vault Enterprise / OpenBao namespace (X-Vault-Namespace)
  • organizationSlugstring
    Optional organization slug to scope the login to
  • projectIdstring
    Infisical project id
  • roleIdstring
    AppRole role id
  • scopeenum: team | selected
    team (default on create): every project may reference the integration. selected: only the projects and environments in grants. Omit on update to keep the stored scope.
  • secretstring
    Write-only: the Vault token (token auth), the AppRole secret id, the Infisical client secret or the Doppler token. Omit on update to keep the stored one.
  • siteUrlstring
    Infisical URL (default https://us.infisical.com) or Doppler API URL (default https://api.doppler.com)
Response 200 · OK · application/json
SecretManager
  • SecretManagerConfigrequired
  • createdAtstring (date-time)required
  • examplestringrequired
    A reference in this integration's syntax
  • ScopeGrant[] | nullrequired
    With scope selected: the projects and environments that may reference the integration
  • idstringrequired
  • kindenum: vault | infisical | dopplerrequired
  • SecretManagerLastTestrequired
  • namestringrequired
    Used in references: ${{vault:<name>/<path>#<key>}} or ${{doppler:<name>/<project>/<config>#<key>}}
  • scopeenum: team | selectedrequired
  • secretSetbooleanrequired
  • updatedAtstring (date-time)required
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

DELETE/secret-managers/{id}

Remove a secret manager integration

Refused with 409 integration_in_use while a variable references it.

ParameterInTypeDescription
idrequiredpathstring
Response 204 · No Content

No body.

Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflictintegration_in_use
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/secret-managers/{id}/test

Test a secret manager integration

Signs in and, when path and key are given, reads that secret. The value is discarded and never returned.

ParameterInTypeDescription
idrequiredpathstring
Request body · application/json · required
TestInputBody
  • keystring
    Optional field or secret name to read
  • pathstring
    Optional secret path to read (without the integration name); for Doppler the project and config, like backend/prd, or empty for the integration's defaults
Response 200 · OK · application/json
SecretManagerTestResult
  • messagestringrequired
  • okbooleanrequired
  • readbooleanrequired
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.