Cosmoner Docs
API Reference

Secrets

Encrypted configuration. A secret's value is returned exactly once — by the call that sets it — and never again; reads describe the secret without handing the plaintext back. For values that do not need protecting, use variables instead.

List secrets

GET
/v1/projects/{projectId}/secrets

Metadata for every secret on the project — never the values. A secret's plaintext is returned only by the call that sets it.

Pass environment to narrow the list. Secrets in default apply to every environment unless an entry with the same name exists for that environment.

Auth: a project API key carrying secrets:read.

Authorization

apiKey
AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string
Length1 <= length

Query Parameters

environment?string

Value in

  • "default"
  • "development"
  • "staging"
  • "production"

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/projects/string/secrets"
{  "success": true,  "data": [    {      "id": "string",      "name": "string",      "description": "string",      "environment": "default",      "version": -9007199254740991,      "createdBy": "string",      "updatedBy": "string",      "createdByUser": {        "id": "string",        "name": "string",        "email": "[email protected]"      },      "updatedByUser": {        "id": "string",        "name": "string",        "email": "[email protected]"      },      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z"    }  ]}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}

Create a secret

POST
/v1/projects/{projectId}/secrets

Stores an encrypted value and returns the plaintext once, in this response.

Names are unique per environment. A project that has reached its secret limit returns 402 PAYMENT_REQUIRED; add capacity with the upgrade endpoint.

Auth: a project API key carrying all of secrets:read and secrets:write.

Role: the caller must be an owner or admin of the project.

Rate limit: this endpoint is rate limited; a 429 means back off and retry.

Authorization

apiKey
AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string
Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/projects/string/secrets" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "value": "string"  }'
{  "success": true,  "data": {    "id": "string",    "name": "string",    "description": "string",    "environment": "default",    "version": -9007199254740991,    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "value": "string",    "maskedValue": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}

Fetch a secret

GET
/v1/projects/{projectId}/secrets/{secretId}

The secret's metadata. The value is not included and cannot be read back.

Auth: a project API key carrying secrets:read.

Authorization

apiKey
AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string
Length1 <= length
secretId*string
Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/projects/string/secrets/string"
{  "success": true,  "data": {    "id": "string",    "name": "string",    "description": "string",    "environment": "default",    "version": -9007199254740991,    "createdBy": "string",    "updatedBy": "string",    "createdByUser": {      "id": "string",      "name": "string",      "email": "[email protected]"    },    "updatedByUser": {      "id": "string",      "name": "string",      "email": "[email protected]"    },    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}

Replace a secret's value

PATCH
/v1/projects/{projectId}/secrets/{secretId}

Re-encrypts the secret with a new value and increments its version. The new plaintext is returned once, in this response.

Auth: a project API key carrying all of secrets:read and secrets:write.

Role: the caller must be an owner or admin of the project.

Authorization

apiKey
AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string
Length1 <= length
secretId*string
Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/v1/projects/string/secrets/string" \  -H "Content-Type: application/json" \  -d '{    "value": "string"  }'
{  "success": true,  "data": {    "id": "string",    "name": "string",    "description": "string",    "environment": "default",    "version": -9007199254740991,    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "value": "string",    "maskedValue": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}

Delete a secret

DELETE
/v1/projects/{projectId}/secrets/{secretId}

Auth: a project API key carrying all of secrets:read and secrets:write.

Role: the caller must be an owner or admin of the project.

Authorization

apiKey
AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string
Length1 <= length
secretId*string
Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/v1/projects/string/secrets/string"
Empty
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}

Fetch a secret's audit trail

GET
/v1/projects/{projectId}/secrets/{secretId}/audit

Who created, changed or deleted the secret, and when. Values never appear here.

Auth: a project API key carrying secrets:read.

Role: the caller must be an owner or admin of the project.

Authorization

apiKey
AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string
Length1 <= length
secretId*string
Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/projects/string/secrets/string/audit"
{  "success": true,  "data": [    {      "id": "string",      "secretId": "string",      "action": "CREATED",      "actorId": "string",      "actor": {        "id": "string",        "name": "string",        "email": "[email protected]"      },      "metadata": "string",      "createdAt": "2019-08-24T14:15:22Z"    }  ]}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}

Buy secret capacity

POST
/v1/projects/{projectId}/secrets/upgrade

Adds secrets packs to the project's subscription, raising the limit. Defaults to one pack.

The change is billed from the moment it takes effect; the response is the capacity now in force.

Auth: a project API key carrying all of secrets:read and secrets:write.

Role: the caller must be an owner or admin of the project.

Authorization

apiKey
AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string
Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Default{}

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/projects/string/secrets/upgrade" \  -H "Content-Type: application/json" \  -d '{}'
{  "success": true,  "data": {    "used": -9007199254740991,    "limit": -9007199254740991,    "freeLimit": -9007199254740991,    "packSize": -9007199254740991,    "paidPacks": -9007199254740991,    "packPrice": {      "monthly": 0,      "currency": "string"    }  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}

Fetch secret capacity

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

How many secrets the project stores, how many it may store, and the price of more.

Auth: a project API key carrying secrets:read.

Authorization

apiKey
AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string
Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/projects/string/secrets/usage"
{  "success": true,  "data": {    "used": -9007199254740991,    "limit": -9007199254740991,    "freeLimit": -9007199254740991,    "packSize": -9007199254740991,    "paidPacks": -9007199254740991,    "packPrice": {      "monthly": 0,      "currency": "string"    }  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}
{  "success": false,  "error": {    "code": "string",    "message": "string"  }}

Redis

Managed Redis databases. A database's password is returned only by the single-database read, never by the list, so enumerating databases does not hand out credentials for all of them.

Variables

Non-sensitive configuration, stored and returned in plaintext and scoped to a deployment environment. For values that must not be readable, use secrets instead.

On this page

List secretsCreate a secretFetch a secretReplace a secret's valueDelete a secretFetch a secret's audit trailBuy secret capacityFetch secret capacity