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.

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:

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

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. From a shell:

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.