Agents and the Agent API

How agents work

Create an agent in the Admin console for each script, CI pipeline or AI agent. It reads only the vaults you share with it. The Agent API returns ciphertext; the passkey-x agent command decrypts it on the agent’s own machine with the private key part of its token, which is never sent. Every read appears in the audit log.

The agent token is pxa1.<agent id>.<secret>.<private key>; only pxa1.<agent id>.<secret> is sent to the API. Stop the agent to end its access at once.

Set up an agent

1. In the Admin console, open Agents and create an agent for the script or pipeline.
2. Copy the one-time agent token and store it as a secret in your CI system.
3. Share the vaults the agent needs with it, as you would with a person.
4. Run the passkey-x agent command with the token. It downloads ciphertext and decrypts it on that machine only.
5. Stop the agent to end its access at once. Every read appears in the audit log.

passkey-x agent

Prefer run: values go to the child process only, never to the terminal or shell history. References are described in Command line; on a developer’s own computer, pkx does the same with the desktop app.

In CI

# GitHub Actions: PASSKEY_X_AGENT_TOKEN is a repository secret; the passkey-x CLI (apps/cli) is on the runner
- name: Deploy with secrets from Passkey-X
  env:
    PASSKEY_X_AGENT_TOKEN: ${{ secrets.PASSKEY_X_AGENT_TOKEN }}
  run: |
    passkey-x agent run \
      --env DATABASE_URL=px://Production/Database/password \
      --env STRIPE_KEY=px://Production/Stripe/password \
      -- ./deploy.sh

Agent API

Errors: 401 the token is invalid or was replaced; 403 agent_inactive the agent was stopped, or the organization’s plan or kill switch doesn’t allow agents.

curl -sS -X GET 'https://passkey-x.com/api/agent/v1/vaults' \
  -H "Authorization: Bearer $PASSKEY_X_AGENT_TOKEN"