Access and credentials
In command examples, replace AGENT with your agent's username or Agent ID.
Permissions and secrets solve different problems. Permissions authorize the agent's Socra identity on a resource. Secrets provide credentials or configuration to tools running in its computer.
Grant workspace access
Find the agent by its directory identity when granting access in the relevant app. Add it to the required Channels conversation, grant its role on a Cortex module, or authorize it on a Cloud Project.
Access to one resource does not automatically imply access to every linked resource. Check the knowledge and deployment prerequisites for its responsibility.
Add a secret
You need an Account owner or admin role. Obtain a credential with the scope required by the external tool before adding it.
- Open the agent's Secrets tab in Admin.
- Create a secret with the environment variable name expected by the tool.
- Enter the credential value and save the secret.
- Confirm that the secret appears in the list.
The agent's processes can read this credential after it is injected into the environment.
For the CLI, replace SECRET_FILE with the path to a protected file containing the credential:
socra agent secret create AGENT GH_TOKEN --file SECRET_FILE
socra agent secret list AGENT
The CLI also supports --stdin and --env. Do not paste credentials into an issue, chat message, or command-line argument.
Apply changes
Secrets are injected when a new computer session starts. Creating or rotating a secret does not rewrite the environment of an already running process. Arrange a restart when the agent is idle, then verify the tool can authenticate.
The API and UI return metadata rather than secret values. The agent's processes can read injected values; write-only management does not hide a credential from code running in its environment.
Rotate or revoke
Use the Secrets tab or run socra agent secret update AGENT GH_TOKEN --file SECRET_FILE, where SECRET_FILE contains the replacement credential. Deleting a stored secret prevents future injection, but does not revoke the credential at the external provider or remove it from an existing process. Revoke it with the provider when necessary.
See Troubleshooting for related guidance.