Secrets
The Secrets screen lets you store a credential of the tenant (provider key, connector password, token) in the secret backend, replace its value and delete it. Values are write only: the screen lists only the metadata. Portal path: /security/secrets, menu Security and governance > Secrets. It is used by tenant administrators, security officers and developers who connect a provider or a connector.
What the screen shows
The screen (Secrets in portal/src/screens/security.tsx) shows a banner Write only: "Values are sent to the secret backend and never returned; only metadata is listed.", then one table, Secrets, read from GET /v1/secrets (no paging), sorted by path.
| Column | Content |
|---|---|
| Path | Path of the secret, for example providers/openai/api_key. |
| Version | Incremented on each write of the same path. |
| Backend | openbao when OpenBao is configured, else local (encrypted in the database). |
| Updated | Last write. |
Empty table: "No secret", "Store a credential: its value is never returned."
Actions
| Button or action | What it does | API call | Roles |
|---|---|---|---|
| New secret (then Create) | Stores a Path (required, placeholder providers/openai/api_key) and a Value (required, masked). An existing path gets a new version. Audited as secret.write. | POST /v1/secrets | tenant_admin, security_officer, developer |
| Overwrite (row menu, then Overwrite) | Writes a new Value for the path of the row; the version goes up by one. | POST /v1/secrets | tenant_admin, security_officer; developer for the secrets it wrote |
| Delete (row menu) | Opens the destructive confirmation; you type the path, then Confirm. The secret is removed from the database and from OpenBao. Audited as secret.delete. | GET /v1/lineage/graph, then DELETE /v1/secrets/{path} | tenant_admin, security_officer; developer for the secrets it wrote |
| Refresh icon | Reads the list again. | GET /v1/secrets | Every user of the tenant |
A deleted secret cannot be read back: any provider, connector or agent that references its path fails until a new value is stored.
Roles
The portal hides no button on this screen. The Control Plane (services/control-plane/src/eai/domains/secrets/__init__.py) lets any user of the tenant list the metadata, and requires tenant_admin, security_officer or developer to write or delete (WRITER_ROLES). A developer may only overwrite or delete the secrets it wrote; the administrators manage every secret. platform_admin passes every role check. No route returns a value: the platform reads a secret on the server side only.
Typical tasks
Store a provider key
- Open the form. The provider configuration references the secret by its path, never by its value. Click New secret. Expected result: a side panel with Path and Value. If it fails: no button means the list did not load; click Retry.
- Fill it. Enter a Path such as
providers/openai/api_keyand paste the key in Value. Expected result: the value is masked. If it fails: nothing to retry at this step. - Create. Click Create. Expected result: the message Created and a row with Version
1and the backend used. If it fails:validation_error(HTTP 422) means a path with forbidden characters (allowed: letters, digits,_,.,/,-, up to 255 characters, not starting with.,/or-);secret_backend_error(HTTP 502) means OpenBao refused the write.
Rotate a credential
- Find the path. The path stays the same, only the value changes. Locate the row. Expected result: the current Version. If it fails: "No secret" means it was never stored for this tenant.
- Overwrite. Row menu > Overwrite, paste the new Value, then Overwrite. Expected result: the message Done and Version increased by one. If it fails:
forbidden(HTTP 403) withrequired_rolesmeans you are adeveloperand another person wrote this secret. - Revoke the old value at the provider. The platform does not call the provider. Revoke the previous key in the console of the provider. Expected result: only the new key works.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
validation_error (HTTP 422) on create | The path does not match ^[A-Za-z0-9_][A-Za-z0-9_./-]{0,254}$, or the value is empty or longer than 65536 characters. | Fix the path or the value. |
invalid_request (HTTP 400) with path | The path holds a .. segment. | Remove the .. segment. |
forbidden (HTTP 403) with required_roles | Your roles cannot write secrets, or you are a developer and the secret was written by someone else. | Ask a tenant_admin or a security_officer. |
secret_backend_error (HTTP 502) | OpenBao is unreachable or refused the operation. | Check OpenBao, then retry. |
not_found on Delete | The secret was already deleted. | Refresh the table. |
tenant_required (HTTP 403) | The account acts without a tenant. | Sign in with an account of the tenant. |