# Keys and permissions

Choose the credential for the task. Keep secrets in a private environment or secret store. Do not paste them into commands or committed files.

## Management tasks

`BARUA_MANAGEMENT_KEY` authorizes the scopes an owner granted to a connection. It has no test/live mode. Use it with `manage.mjs` and `inspect.mjs`.

After [installing the skill](/docs/guides/quickstart.md), set `BARUA_SKILL` to its directory and run:

```sh
node "$BARUA_SKILL/scripts/manage.mjs" capabilities
```

Read the returned actions and `reads` entries. Each read lists its required permissions and whether it is allowed. `terms_current` is separate; some changes require current owner terms even when a scope is present.

The owner creates the grant through [owner access](/docs/guides/owner-access.md). Follow [access and discovery](/skills/barua-setup/references/management.md#access-and-discovery) before any action. Connection creation must save the returned key directly to the configured private destination.

## Server events

`BARUA_API_KEY` is an integration key with a recorded test/live mode. A test key validates payloads but creates no people and sends no email. Use live mode only for the authorized integration. Historical events use explicit backfill mode.

The [event contract](/docs/events.md#keys) defines key capabilities. Management access and event access are separate. Revoking a management connection does not revoke integration keys already installed in a product.

## Owner decisions

The owner helper uses either `BARUA_OWNER_TOKEN` with `BARUA_WORKSPACE_ID`, or `BARUA_OWNER_SESSION_FILE`. Do not configure both sources. The session file is private and contains the selected workspace; confirm that selection before changes.

See [owner sign-in](/skills/barua-setup/references/owner.md#sign-in-privately) for file permissions and refresh behavior. Owner authentication does not delegate legal acceptance or destructive decisions to an agent.

## Connection problems

The helpers default to `https://barua.ai`. `BARUA_URL` overrides the host; HTTPS is required except for localhost development. Run `--help` on the relevant helper for flags.

On denied access, read the capabilities and [recovery rules](/docs/guides/troubleshooting.md). Do not switch credentials or use dashboard access to bypass a missing permission.