Secrets Management
Store credentials, configure your secrets backend, and bind secrets to plugins, all from the dashboard.
Gibson stores credentials (API keys, tokens, passwords) for you. Your plugins get them at runtime. The values never appear in agent logs, tool outputs, or audit streams.
This guide shows the everyday tasks of a tenant admin. The tasks are: add secrets, connect a custom backend, register a plugin, rotate credentials, review audit logs, and understand active grants.
Adding your first secret
Go to Settings > Secrets. If you just created your account, the page shows a confirmation that your secrets backend is ready.
- Click Add secret.
- Fill in the fields:
- Name, a short identifier that your plugin resolves. Use
the convention
cred:<purpose>, for examplecred:openai_api_keyorcred:db_password. - Value, paste your credential here. The field is masked. Gibson sends the value directly to secure storage and never shows it again.
- Category, choose
credfor API keys and passwords. Chooseprovider_configfor LLM provider configuration. Useprovider_configwhen you wire an LLM key through the secrets system.
- Name, a short identifier that your plugin resolves. Use
the convention
- Click Save. The dashboard returns you to the secrets list. The list shows the secret name, category, version number, and the last access time. The list never shows the value.
Can I see the value later? No. Gibson stores credentials in encrypted form. If you need to replace a value, use the Rotate action. By design, the dashboard has no "reveal value" button.
Connecting your own secrets backend (BYO broker)
By default, new accounts use Gibson-managed secrets storage. Gibson provisions this secure storage backend for your account at signup. It needs no configuration.
If your organization's security policy requires credentials in your own infrastructure, switch to a bring-your-own (BYO) backend. Do this on the Settings > Secrets backend page. You need the Admin role to make this change.
Before you switch: a backend change does not move existing secrets. Secrets that you added before the switch stay in the old backend. New secrets go to the new backend. If you need all secrets in one place, recreate them after the switch.
When you save a new backend configuration, Gibson first tests connectivity with a "probe". The probe writes and reads a temporary value in your backend. This confirms that the permissions are correct. If the probe passes, Gibson commits the save. If the probe fails, Gibson does not commit the save.
HashiCorp Vault (self-hosted)
You need a KV v2 secrets engine and a Vault auth method that your Gibson instance can use. We recommend the JWT auth method for production. Gibson presents its service identity as a JWT. Gibson also supports AppRole and static Token.
Required configuration fields:
| Field | Example | Notes |
|---|---|---|
| Vault address | https://vault.example.com | Must be reachable from Gibson's network |
| Namespace | gibson/tenant-acme | Vault Enterprise only; leave blank for Community Edition |
| Path prefix | secret/data/tenant/acme/ | Community Edition: use this instead of namespace |
| KV mount | secret | The KV v2 mount name |
| Auth method | jwt | One of: token, approle, jwt, kubernetes, aws_iam |
| Auth credentials | (depends on method) | For token: the token value; for approle: role ID + secret ID; for jwt: the JWT role name |
Common issues:
- If the probe returns
permission denied, check your Vault ACL policy. The policy must grantcreate,read,update,delete, andliston the KV path. - If the probe returns
KV v1 mount detected, enable a KV v2 mount in your Vault. Then update the KV mount field. - For Community Edition, use Path prefix mode, not Namespace.
AWS Secrets Manager
Gibson assumes an IAM role to access your Secrets Manager. Your IAM role must trust Gibson's identity.
Required configuration fields:
| Field | Example | Notes |
|---|---|---|
| IAM role ARN | arn:aws:iam::123456789012:role/gibson-secrets | The role Gibson will assume |
| External ID | acme-gibson-prod | Optional; required if your trust policy enforces one |
| Region | us-east-1 | The AWS region where your secrets live |
IAM policy required on the assumed role:
{
"Effect": "Allow",
"Action": [
"secretsmanager:CreateSecret",
"secretsmanager:GetSecretValue",
"secretsmanager:UpdateSecret",
"secretsmanager:DeleteSecret",
"secretsmanager:ListSecrets"
],
"Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:gibson/tenant/*"
}
If your Secrets Manager uses a customer-managed KMS key, also add
kms:GenerateDataKey and kms:Decrypt on that key.
Common issues:
AccessDeniedException, check that the trust policy of the IAM role allows Gibson's principal. Also check that the permission policy of the role coversgibson/tenant/*secrets.failed to assume role, make sure that the role ARN is correct. If you use an external ID, make sure that it matches exactly.
GCP Secret Manager
Gibson authenticates to GCP with a service account JSON key or with Workload Identity Federation. We recommend Workload Identity Federation for GKE-hosted Gibson deployments.
Required configuration fields:
| Field | Example | Notes |
|---|---|---|
| GCP project | my-gcp-project | The project where Secret Manager is enabled |
| Auth method | wif or sa_json | Workload Identity (recommended) or service account JSON key |
| Service account JSON | (file upload) | Only for sa_json auth; the key must have Secret Manager Admin rights |
Required IAM role on the service account: roles/secretmanager.admin
(or the narrower roles/secretmanager.secretAdmin).
Before you configure: make sure that the Secret Manager API is enabled in your GCP project:
gcloud services enable secretmanager.googleapis.com --project my-gcp-project
Common issues:
403 PERMISSION_DENIEDwithAPI not enabled, run the command above.invalid_grant, your service account JSON key was rotated or revoked. Generate a new key in the GCP console and upload it again.
Azure Key Vault
Gibson authenticates to Azure Key Vault with a service principal (SP) or with Workload Identity.
Required configuration fields:
| Field | Example | Notes |
|---|---|---|
| Vault URL | https://my-vault.vault.azure.net | The full DNS name of your Key Vault |
| Azure AD tenant ID | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx | Your Azure AD directory (tenant) ID, found in Azure Portal under Azure Active Directory > Overview |
| Client ID | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx | The service principal's application (client) ID |
| Client secret | (masked field) | The SP's client secret; use Workload Identity to avoid managing this |
| Auth method | service_principal or workload_identity |
The service principal needs Get, Set, and Delete permissions on secrets in the access policies of your Key Vault. If the vault uses Azure RBAC mode, the service principal needs the Key Vault Secrets Officer role instead.
Common issues:
Forbidden 403, check that the SP has the correct access policy or RBAC role on the specific Key Vault. A role at subscription level only is not enough.authentication failed: client secret expired, rotate the SP secret in Azure AD. Then update the configuration here.AADSTS700016, the client ID or tenant ID is incorrect.
Granting a plugin its secrets
Plugins are the only components in Gibson that can retrieve credential values at runtime. A plugin declares no secret. A tenant admin grants the plugin access to named secrets, and Gibson records a permission between the identity of the plugin and each granted secret.
The secret access step
When you deploy a plugin from the dashboard, the deploy wizard has a Secret access step. Select the secrets of this workspace that the plugin can read. The plugin can read no other secret. You can select none.
When you finish the wizard, Gibson records the permission for each selected secret before it shows the bootstrap token.
Start your plugin host
On the machine where your plugin runs, put the bootstrap token and the address of your platform in the environment. Then start the plugin:
export GIBSON_URL=https://<your-platform>
export GIBSON_BOOTSTRAP_TOKEN=eyJ...
gibson component run --kind plugin
The first start exchanges the token for a persistent host key. Your plugin process uses this host key on every later connection. The token is single-use and expires shortly after issuance.
A plugin that resolves a secret at start fails the boot with the secret named when it has no grant for it. Grant the secret, then start the plugin again.
Removing a grant
The detail page of the plugin lists each granted secret. Revoke a grant there. The running plugin learns of the revocation within seconds and reports itself degraded.
Rotating secrets
Rotation replaces the value of a secret. The name, the bindings, and the plugins that use the secret stay the same.
When to rotate
- A credential was exposed (breach response).
- Your security policy requires periodic rotation (for example, every 90 days for API keys).
- A service provider forces rotation (for example, an OAuth token expired).
How to rotate
- Go to Settings > Secrets.
- Click the name of the secret to open the detail page. Then click Rotate. Or click the kebab menu on the list row and choose Rotate.
- Paste the new value and confirm.
The version counter increments immediately. Gibson notifies each plugin that holds a grant on the secret. The plugin drops its cached value, and the next time the plugin requests the credential, it receives the new value. No restart is needed.
What plugins are affected
The detail page of the secret lists every bound plugin under Plugin associations. The Rotate confirmation modal shows the same list. Use it to see which plugins the rotation reaches before you confirm.
What if a plugin is unavailable during rotation?
The plugin gets the new value on its next credential request. You need no action.
Reviewing audit logs
Gibson records every secret operation in the audit log. Go to Settings > Audit log, or use the audit log link in the navigation menu.
What is logged
| Event | When it appears |
|---|---|
secret.create | A secret was added |
secret.read | A plugin retrieved a credential value (the value itself is never logged, only the secret's name) |
secret.update | A secret was rotated |
secret.delete | A secret was deleted |
secret.bind | A plugin was granted access to a secret |
secret.revoke_access | A plugin's access to a secret was removed |
secret.config_set | The secrets backend configuration was changed |
plugin.register | A plugin was registered |
plugin.invoke | A plugin method was called by a tool |
authz.deny | A request was denied (for example, a plugin tried to access a secret it wasn't bound to) |
Filtering the log
Use the Event type dropdown to filter by category. Combine it with the Date range and Actor filters to narrow results.
Example: to see all credential reads in the last 7 days:
- Event type:
secret.read - Date range: last 7 days
Example: to find who added the cred:openai_api_key secret:
- Event type:
secret.create - Actor: (leave blank to see all actors)
Then look for the row with resource name cred:openai_api_key.
Exporting for compliance
Click Export (CSV or JSON) to download the filtered log. Each row includes the event type, timestamp, actor, resource name, and outcome. Export files never include credential values.
Understanding grants
A grant is a time-limited authorization. Gibson issues it to a component (agent, tool, or plugin) at the start of a mission. The grant specifies exactly which actions the component can take. The grant expires when the mission ends, or after a fixed window, whichever comes first.
Where to find them
Go to Settings > Grants to see all active grants in your account.
What the columns mean
| Column | Meaning |
|---|---|
| Recipient | The specific component instance that holds the grant |
| Type | agent, tool, or plugin. Only plugins hold grants that cover credential retrieval. |
| Allowed actions | The list of operations this grant authorizes |
| Expires | When the grant stops being valid |
Why grants expire
Grants are short-lived by design. Nobody can use an expired grant, even if it is replayed. This limits the blast radius of a compromised or misbehaving component. At most, the component can act within its granted scope until the grant expires.
If a grant seems unexpectedly long-lived, check the mission that issued it. Some missions are designed for long-running tasks and receive longer grants.
Near-expiry highlighting
Amber rows are within 5 minutes of expiry. This is informational. The component can still act on the grant until expiry. Gibson issues a new grant at the next mission dispatch.
Can I revoke a grant?
The Grants page is read-only in the current release. Active missions manage their own grant lifecycles. If you need to stop a mission immediately, use the mission control actions on the Missions page. This causes the associated grants to expire.
What gets logged about secrets accessed during a mission
The detail page of a mission has a Secrets accessed panel. The panel lists the names of the secrets that plugins retrieved during that mission. It shows the names only, never the values. This helps you correlate mission outcomes with specific credentials:
- Which plugin retrieved which credentials
- How many times each was retrieved
- The first and last access time within the mission
Each entry links to the full secret detail page. There you can see metadata, plugin associations, and the broader audit history.
Deleting a secret
Before you delete a secret, check which plugins are bound to it. The Delete confirmation dialog lists the affected plugins. When you delete a secret, Gibson:
- Removes the credential value from storage immediately.
- Removes all plugin bindings.
- Leaves plugins that used the secret in a Degraded state. These plugins continue to serve methods that do not need the deleted credential. Methods that need it fail until you register the plugin again with a replacement binding.
To disable a credential for a time and keep the plugin bindings, rotate it to a known-invalid value. Do not delete it.