Access Keys

An access key is the credential S3 clients sign requests with. It is a pair: an access key ID (access_key) and a secret (secret). To create one, see the Quickstart.

Access keys are separate from Nirvana API keys. An API key manages buckets and access keys through the Nirvana API. An access key reads and writes objects through the S3 endpoint.

Scope

A key belongs to one project and one region. It works for every bucket of that project in that region, including buckets created after the key. It doesn’t work for buckets of other projects or in other regions.

To limit a workload to certain buckets, put those buckets in a project of their own and give the workload a key from that project.

The Secret Is Shown Once

The secret is returned only in the response that creates the key. Listing or getting a key returns its access_key but never its secret. Store the secret in a secrets manager as soon as you create the key.

If you lose the secret, it can’t be recovered. Create a new key and delete the old one.

With Terraform, the nirvana_storage_key resource keeps the secret in state from the create response, so treat the state as sensitive. An imported key has no secret in state. To get a new secret, replace the key, for example with terraform apply -replace=nirvana_storage_key.key.

Rename a Key

You can rename a key at any time. Its access key ID and secret stay the same.

curl -X PATCH https://api.nirvanalabs.io/v1/storage/keys/{key_id} \
  -H "Authorization: Bearer $NIRVANA_LABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-uploads-2026"}'

nirvana storage:keys update --key-id <key_id> --name ci-uploads-2026

Rotate a Key

A key’s secret can’t be changed, so rotating means replacing the key:

Create a new key in the same project and region.
Switch every client to the new access key ID and secret, and confirm they work.
Delete the old key.

Both keys work at the same time between steps 1 and 3, so clients can move over without downtime.

Delete a Key

curl -X DELETE https://api.nirvanalabs.io/v1/storage/keys/{key_id} \
  -H "Authorization: Bearer $NIRVANA_LABS_API_KEY"

nirvana storage:keys delete --key-id <key_id>

The request returns 204. The key stops working immediately: any client still using it gets an authentication error on its next request. Buckets and objects are not affected.

List Keys

curl "https://api.nirvanalabs.io/v1/storage/keys?project_id={project_id}" \
  -H "Authorization: Bearer $NIRVANA_LABS_API_KEY"

project_id is required. You can filter by region and by name, a case-insensitive substring of the key name.