# Machine keys and CI

Scripts, CI pipelines and bots use a service account instead of a person's
login. A service account is a member of the organization that holds keys and
gets tools through its groups.

## Create a key

An owner or admin, in the Zenitya app:

1. Opens **Service accounts** and creates one, for example "CI deploy".
2. Adds it to the groups whose tools it should call.
3. Creates a key and picks its scopes and expiry. The key is shown once.

| Scope       | Allows                                                          |
| ----------- | --------------------------------------------------------------- |
| `deploy`    | `zya deploy` and reading builds                                 |
| `invoke`    | Calling tools (those granted to its groups) over the CLI or MCP |
| `configure` | Managing project secrets. Never implied by the other scopes     |

Give each key only the scopes it needs. A service account's page shows who
created, rotated and revoked each key; rotate a key there when someone who had
it leaves.

## Use it with the CLI

Set `ZENITYA_API_KEY`. It takes precedence over any saved login, and needs no
`zya login`:

```sh
export ZENITYA_API_KEY=...   # from your CI's secret store
zya whoami
zya deploy --json
```

`--token <key>` works too, but a value on the command line can end up in logs;
prefer the variable.

## GitHub Actions

```yaml
name: Deploy tools
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install --frozen-lockfile
      - run: curl -fsSL https://zenitya.dev/install.sh | sh
      - run: ~/.zenitya/bin/zya deploy --json
        env:
          ZENITYA_API_KEY: ${{ secrets.ZENITYA_API_KEY }}
```

In CI the CLI prints one plain line per step and no color, so logs stay
readable. `deploy --json` puts the result on stdout for later steps.

## Calling tools from code

Use the key with any MCP client against the organization endpoint; see
[Connecting agents over MCP](mcp.md#connect-with-a-service-account-key).
From a shell:

```sh
zya exec findLateOrders --data '{"since":"2026-11-01","limit":5}'
```

`exec` runs in a project directory, since it names tools by their key within
the project.