API keys

Gave gives you your first key. After that, you manage your keys yourself: hold several at once, so you can rotate one without downtime.

A key looks like gave_sk_sandbox_ followed by 64 hex digits. Gave keeps only a hash of it, so a key is shown once, when it's created. Store it in your secrets manager straight away.

Create a key

Name it: a name is unique among your keys and never reused, which makes the request safe to retry.

curl https://api.sandbox.gave.sh/v1/api-keys \
  -H "x-api-key: $GAVE_API_KEY" \
  -H "content-type: application/json" \
  -d @create-key.json

{ "name": "ci" }

It answers 201 Created, with the key's secret:

{
  "key": { "name": "ci", "last4": "cdef", "createdAt": "2026-10-11T09:00:00.000Z" },
  "secret": "gave_sk_sandbox_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "duplicate": false
}

The same request again answers duplicate: true, without the secret: it can't be shown twice. Lost it? Create another key and revoke this one. You can hold up to 20 active keys at once, and 1,000 in all, revoked ones included.

List your keys

curl https://api.sandbox.gave.sh/v1/api-keys -H "x-api-key: $GAVE_API_KEY"

{
  "keys": [
    { "name": "primary", "last4": "9f3a", "createdAt": "2026-10-01T08:00:00.000Z", "revokedAt": "2026-10-11T09:05:00.000Z" },
    { "name": "ci", "last4": "cdef", "createdAt": "2026-10-11T09:00:00.000Z" }
  ]
}

last4 tells keys apart; the secret itself is never shown again.

Revoke a key

curl -X DELETE https://api.sandbox.gave.sh/v1/api-keys/primary -H "x-api-key: $GAVE_API_KEY"

{
  "key": { "name": "primary", "last4": "9f3a", "createdAt": "2026-10-01T08:00:00.000Z", "revokedAt": "2026-10-11T09:05:00.000Z" }
}

A revoked key stops working within a minute; if Gave's database is out of reach then, a key checked in the last hour keeps working until it's back. Revoking it again changes nothing. Your last active key can't be revoked (422 LastActiveKey): create another one first.

Rotate a key

1. Create a key, and deploy it to your servers.
2. Once nothing uses the old key, revoke it.