Secrets

A secret is a value a site's code reads as env.NAME: the signing secret of a webhook from another service, or a key for an outside API. The live site and its draft each have their own value.

The value goes to the hosting provider and nowhere else. Clave keeps only the name, and nothing can read the value back, Clave included. It never enters git.

Write one

PUT /v1/sites/{id}/secrets/{name} with { "value": "..." }.

• A name is upper-case letters, digits and _, and starts with a letter.
• DB, ASSETS and names that start with CLAVE_ are the platform's.
• A value is at most 4 KB. A site holds at most 20 secrets.

The live code reads it after the next publish.

The draft's value

?slot=1 writes the draft's own value, and the draft's code reads it after the next draft. A draft never gets the live value. Anyone with the draft's link can make its code use what it holds, so give a draft a test credential: a sandbox key, a test webhook secret.

The value lives on the draft, so the draft must exist first: before that the answer is 409 draft_needed. When the draft is discarded or the site archived, its values go with it.

List and remove

GET /v1/sites/{id}/secrets answers with names and the slot of each (0 for the live site), never values.

DELETE /v1/sites/{id}/secrets/{name} removes the name from the live site and the draft; ?slot= removes one of them.

The Secrets tab of a site in the app shows the same list: each name, and whether the live site and the draft have a value. It shows no values and changes nothing.

What a secret is not

The site's code can read the value and send it to any host on its egress list. That is the owner's key in the owner's code, the same as an environment variable on any host. Never put a Clave token in a secret: a token opens the whole account. The site's code has the runtime API for what it needs from Clave.