Secrets API reference

Secrets are scoped to a database and identified by a unique key. Onyx combines that key with the database ID to form a composite identifier, preventing collisions across your fleet.

Values are encrypted at rest and decrypted only when you explicitly request a secret. Listing secrets returns metadata only, keeping the values hidden unless you call the dedicated retrieval endpoint.

The Secrets API layers symmetric and asymmetric encryption. Each secret value is encrypted with a randomly generated AES-256-GCM key; that key is then encrypted with a database-specific RSA-4096 public key and stored alongside the initialization vector.

Each database owns its own RSA keypair stored in the secret-keystore directory. Public keys remain in plaintext for encryption operations, while private keys are encrypted using a master key using an envelope encryption practice. Keys are generated automatically the first time a database uses secrets.

All endpoints require authenticated database access. Listing or retrieving a secret works with any database role, while creating, updating, or deleting a secret requires both a databaseMAINTAINER role and organization ADMIN access.

Retrieve the metadata for all secrets tied to a database without exposing their values.

GET /database/{databaseId}/secret

{
  "records": [
    {
      "key": "api-key-1",
      "purpose": "External API access",
      "updatedAt": "2023-10-15T14:30:00Z"
    }
  ],
  "meta": { "totalRecords": 1 }
}

Create a new encrypted secret and persist its metadata.

POST /database/{databaseId}/secret

{
  "key": "my-api-key",
  "purpose": "Access to external service",
  "value": "secret-value-to-be-encrypted"
}

This endpoint requires database MAINTAINER and organizationADMIN permissions. The response echoes the key and purpose plus an updated timestamp once the value is encrypted and stored.

Retrieve a specific secret including its decrypted value. Use this endpoint sparingly and avoid logging the returned payload in plaintext.

GET /database/{databaseId}/secret/{key}

{
  "key": "my-api-key",
  "purpose": "Access to external service",
  "value": "actual-secret-value",
  "updatedAt": "2023-10-15T14:30:00Z"
}

Rotate a secret or rename its key without creating a new record. Updates apply to the key, purpose, and encrypted value atomically.

PUT /database/{databaseId}/secret/{key}

{
  "key": "updated-api-key-name",
  "purpose": "Updated purpose for external service access",
  "value": "new-secret-value"
}

Remove a secret from the database once it is no longer needed.

DELETE /database/{databaseId}/secret/{key}

{
  "key": "api-key-1"
}

The Secrets API uses standard HTTP status codes:

• 200: Successful operation
• 201: Resource created successfully
• 400: Bad request (invalid parameters)
• 401: Unauthorized (missing or invalid authentication)
• 403: Forbidden (insufficient permissions)
• 404: Not found (database or secret does not exist)
• 500: Internal server error

• Use descriptive keys that communicate the purpose of each secret.
• Rotate secret values regularly and script rotations through the update endpoint.
• Grant MAINTAINER and organization ADMIN access only to team members who truly need to manage secrets.