Skip to content

Access and credentials

View as Markdown

In command examples, replace AGENT with your CoAgent's username or CoAgent ID.

Permissions and secrets solve different problems. Permissions authorize the CoAgent's Socra identity on a resource. Secrets provide credentials or configuration to tools running in its computer.

Grant workspace access

Find the CoAgent by its directory identity when granting access in the relevant app. A ChatGPT or Claude connection supplies AI usage; it does not grant access to your resources.

  • Channels: Start a conversation that includes the CoAgent, or add it to the conversation where it will work. Check the participants before sharing private material.
  • Cortex: Ask the Module owner or a Module admin to grant the CoAgent Module viewer for reading and Flash, or Module editor when it should also maintain that knowledge. Issue access is separate: use Issue viewer to read, Issue contributor to create and comment, or Issue editor when it must update or complete Issues. These roles can be combined. See Access and permissions.
  • Cloud: Grant the required Project permissions for the exact Build, Run or other resources it needs. Repository write access does not grant deployment or rollback permission.

Ask the CoAgent to verify access in its own session. Replace MODULE_NAME with the Module it needs to Flash:

sh
socra cortex module access MODULE_NAME
socra cortex flash MODULE_NAME

Check the returned permissions and whether Flash succeeds. An authorized Flash includes its dependency closure; it does not grant direct access or editing rights to those dependency Modules. Check Issue access separately before assigning work there.

Grant GitHub repository access

An Account Owner or Admin can connect GitHub and grant repository access. The guide covers the Admin setup, socra install agent, the socra agent github commands and read or write grants for each CoAgent.

The GitHub App installation defines the available repositories. Each CoAgent needs an explicit grant, and repository access does not grant Cloud deployment permissions. Verify access in the CoAgent’s own session before assigning work.

Add a secret

For another external tool, you can supply a secret. You need an Account owner or admin role. Obtain a credential with the scope required by that tool before adding it.

  1. Open the CoAgent's Secrets section in Admin.
  2. Create a secret with the environment variable name expected by the tool.
  3. Enter the credential value and save the secret.
  4. Confirm that the secret appears in the list.

The CoAgent's processes can read this credential after it is injected into the environment.

For the CLI, replace TOOL_API_TOKEN with the environment variable name the tool expects. Replace SECRET_FILE with the path to a protected file containing the credential:

sh
socra agent secret create AGENT TOOL_API_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 CoAgent is idle, then verify the tool can authenticate.

The API and UI return metadata rather than secret values. The CoAgent'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 section or run socra agent secret update AGENT TOOL_API_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.

See also