Secret Manager
Secret Manager is a safe place for the passwords, API keys, tokens and other sensitive values your applications need, so you don’t have to write them into code or config files. You save a value once; your app or script reads the current value when it needs it. Every change is kept as a new version, so you can see what changed and roll back.
Secret Manager is turned on per organization. If Secret Manager isn’t under Tools in your sidebar, contact support to request access.
When to use it
Terms
How it works
- You create a store in a workspace.
- You add a secret with one or more key/value pairs.
- Your program reads the secret, either with a platform API token that has Secret Manager → Read, or with its own Access sign-in.
- When a value changes, you save a new version; the program gets the new value on its next read.
Before you begin
- Role: to create or change anything you need write access to the workspace: the Owner, an Admin, or a Technical member. Collaborators can open Secret Manager read-only, which includes viewing secret values. Billing members have no access. See Team members & access roles.
- Identity verification of your own account, to make changes. See Verify your identity.
- Billing: creating a store or a secret goes through the billing check, so your wallet must allow new resources.
- For the API: a platform API token with Secret Manager permission, and the workspace ID.
Create a store and a secret
Create a store
Click Create Store. In Create store, enter a Store name such as Payments (1–128 characters) and an optional Description, then click Create store. The store appears in the list with its Store Key and the status Active.
Verify it worked
The secret appears on the Secrets tab. Click View to see the current version’s values as JSON, with Copy JSON.
Read a secret from code
Any program with a platform API token can read a secret’s current value. The token needs Secret Manager → Read (secret-store.read), and every request must use the workspace that owns the store.
First find the store’s and the secret’s IDs, then read the value:
The last call returns the values under data:
Lists and metadata calls never include values; only the value and version calls do. To create a secret through the API, send POST /secret-store/stores/{store_id}/secrets with {"secret_name": "stripe-api", "value": {"API_KEY": "sk_live_..."}}. All operations are in the Secret Store API reference.
Change, roll back and delete secrets
Each secret’s row has these actions:
Delete is a soft delete. The secret stays in the list with the status Soft Deleted, and its name stays taken. Through the API you can restore it (POST /secret-store/secrets/{secret_id}/undelete), or remove it for good (DELETE /secret-store/secrets/{secret_id}/permanent). Permanent delete and destroying versions can’t be undone.
Give an application its own access
An Access entry lets a program sign in to Secret Manager with its own credentials instead of your API token.
Create the access
On the store’s Access tab, click Create Access. Choose the Access method (AppRole or Kubernetes), enter an Access name such as payments-api (unique in the workspace), and choose the Permission: Read only or Read & write. For Kubernetes, also enter the Kubernetes namespace and Service account. Click Create access.
Every time you open Login Details for an AppRole access, IBEE creates a new Secret ID, and earlier Secret IDs keep working. Rotate secret ID also adds a new one without cancelling the old ones. To cut off a leaked Secret ID, Delete the access and create a new one.
Other actions on an access:
- Permissions: shows Current permissions. Under Add permission, pick a Store and a Permission, and tick Can read older versions (on by default), Can roll back or Can permanently destroy versions (the last needs Read & write). A Read only access can’t be given write, roll back or destroy later.
- Revoke sessions: ends the access’s current sessions; it can sign in again.
- Disable / Enable: blocks the access without deleting it, and ends its sessions.
- Delete: confirm Delete access. It removes the access everywhere, including its permissions on other stores.
Archive or delete a store
From the store’s Actions menu:
- Archive (confirm Archive): applications can no longer read from the store and nothing in it can be changed. The store stays in the list with the status Archived. Its secrets still count for billing. Restore brings it back.
- Delete (type the store’s name, then Delete permanently): removes the store and all its secrets. This can’t be undone. Accesses that also use other stores are kept; only this store’s permission is removed.
Deleting a store deletes every secret in it, permanently. Copy any value you still need first, or Archive the store instead.
Limits and billing
Your usage appears under Billing → Usage. See Billing and usage.
Security tips
- Give each application its own Access with Read only permission on only the stores it needs.
- Use separate stores for production and test values, ideally in separate workspaces.
- Collaborators can view values. Invite people who shouldn’t see secrets with a role that has no access to the workspace.
- Never log secret values or Secret IDs.
- If a value leaks, change it at its source (for example, rotate the database password), then Update the secret.
Troubleshooting
API errors come back as JSON with an error code and message.
Related pages
- API Tokens: create a token with Secret Manager permission
- Secret Store API reference
- Team members & access roles
- Billing and usage
