Secrets API Reference

Crate provides a RESTful API (in addition to a gRPC/Connect interface) for managing your organization’s secrets programmatically.

Authentication

All Secrets API endpoints require a valid API Key and the caller must have the Admin role in the target organization. Please see the Global API & Auth reference for details on how to generate and use your keys.

Endpoints

Store a Secret

PUT /organization/{id}/secrets

Creates or updates a secret.

[!IMPORTANT] The Crate API strictly enforces Sealed Transport (sealed=true). You cannot send plaintext secrets to this endpoint. You must first fetch your organization’s public key, encrypt the secret value using RSA-OAEP SHA-256, base64-encode the result, and send it as the encrypted_value.

Request Body:

{
  "name": "DATABASE_URL",
  "environment": "dev",
  "encrypted_value": "base64-encoded-rsa-ciphertext...",
  "sealed": true,
  "tags": ["backend", "db"]
}

List Secrets

GET /organization/{id}/secrets?env={environment}&tags={comma-separated-tags}

Lists all secrets in the specified environment. You can optionally filter the results by providing a tags query parameter. This endpoint does not return the secret values.

Response:

{
  "secrets": [
    {
      "name": "DATABASE_URL",
      "environment": "dev",
      "version": 1,
      "tags": ["backend", "db"],
      "updated_at": "2026-05-27T10:00:00Z"
    }
  ]
}

Get Public Key

GET /organization/{id}/secrets/public-key

Retrieves the organization’s RSA public key in PEM format, used for sealing secrets before storing them.

Response:

{
  "public_key_pem": "-----BEGIN PUBLIC KEY-----\nMIIB...-----END PUBLIC KEY-----\n"
}

Secure Retrieval

POST /organization/{id}/secrets/retrieve

Retrieves multiple secret values securely. To prevent interception, the client must provide a temporary RSA public key. The server encrypts the payload with a transient AES key, and then encrypts the AES key with the client’s public key.

Request Body:

{
  "environment": "dev",
  "names": ["DATABASE_URL", "STRIPE_API_KEY"],
  "tags": ["backend"],
  "public_key_pem": "-----BEGIN PUBLIC KEY-----\n..."
}

Response:

{
  "encrypted_secrets": "base64-encoded-aes-gcm-ciphertext...",
  "encrypted_key": "base64-encoded-rsa-ciphertext..."
}

Delete a Secret

DELETE /organization/{id}/secrets/{name}?env={environment}

Permanently deletes a secret from the specified environment.