APIZ guide

CLI Quickstart

This quickstart connects GitHub to APIZ, gives one agent temporary access, sends one request through the APIZ Data Plane, checks the evidence, and revokes the access. The agent never receives the GitHub token.

What You Will Create

GitHub API Instance
        ▲
        │ binding alias: github
release-agent Client
        │
        └── one-hour Temporary Credential ──> agent runtime

Policy is intentionally omitted from the first request. Credential separation, adapter validation, secret replacement, and redacted evidence still apply. Add a Policy afterward when you need finer request rules.

Prerequisites

an APIZ deployment URL;
the APIZ CLI from the same release as the deployment;
curl and jq;
a GitHub token limited to the provider-side permissions needed for this test.

Use a private temporary directory so the Setup Manifest is not written into a repository:

APIZ_WORKDIR=$(mktemp -d)
chmod 700 "$APIZ_WORKDIR"
umask 077

apiz context set getting-started --server https://current-host
apiz context use getting-started
apiz login
apiz whoami

The documentation site inserts the public Control Plane URL for its own deployment. If your account can access several Teams, inspect apiz team list and select the intended Team with apiz team use <team-id>.

The login flow asks for the short one-time code shown by WorkOS. It does not ask for your GitHub token.

2. Connect GitHub

read -rsp "GitHub token: " GITHUB_TOKEN && printf '\n'
printf '%s' "$GITHUB_TOKEN" \
  | jq -Rs '{credential: .}' \
  | apiz -o json api create \
      --adapter github \
      --name quickstart-github \
      --config-json '{}' \
      --test-config-json '{"preset":"get_user_info"}' \
      --credential-stdin \
  > "$APIZ_WORKDIR/api.json"
unset GITHUB_TOKEN

API_INSTANCE_ID=$(jq -r '.api_instance_id' "$APIZ_WORKDIR/api.json")
apiz api test "$API_INSTANCE_ID"

APIZ stores the upstream GitHub credential in the API Instance boundary. The test calls GitHub's safe GET /user preset and returns only a safe result.

3. Create Access For The Agent

apiz -o json client create --name quickstart-release-agent \
  > "$APIZ_WORKDIR/client.json"
CLIENT_ID=$(jq -r '.client_id' "$APIZ_WORKDIR/client.json")

apiz -o json client bind "$CLIENT_ID" \
  --api-instance "$API_INSTANCE_ID" \
  --alias github \
  > "$APIZ_WORKDIR/binding.json"

apiz -o json client credentials create "$CLIENT_ID" \
  --binding github \
  --ttl 1h \
  > "$APIZ_WORKDIR/setup.json"

The Setup Manifest is sensitive because it contains newly issued APIZ credentials. It does not contain the GitHub token.

Read the endpoint and credential for the github binding:

APIZ_GITHUB_ENDPOINT=$(jq -r \
  '.items[] | select(.meta.binding_alias == "github") | .endpoint' \
  "$APIZ_WORKDIR/setup.json")
APIZ_TEMPORARY_CREDENTIAL=$(jq -r \
  '.items[] | select(.meta.binding_alias == "github") | .auth.credential' \
  "$APIZ_WORKDIR/setup.json")
CREDENTIAL_GROUP_ID=$(jq -r '.credential_group_id' \
  "$APIZ_WORKDIR/setup.json")

4. Send A Request Through APIZ

curl -fsS \
  -H "Authorization: Bearer $APIZ_TEMPORARY_CREDENTIAL" \
  "$APIZ_GITHUB_ENDPOINT/user" \
  | jq '{login, id, type}'

The agent presents only the APIZ Temporary Credential. After APIZ validates the request, the protected Data Plane applies the stored GitHub credential before contacting GitHub.

5. Inspect And Revoke

apiz access-log list --client "$CLIENT_ID" --since 15m --limit 20
apiz client credentials revoke "$CREDENTIAL_GROUP_ID"

Copy a request_id from the Access Log output to inspect its ordered timeline:

apiz access-log request <request-id>

Human output summarizes the request and names each observed phase. Policy and credential events that did not produce an HTTP response show N/A; the final APIZ or upstream response is labeled separately. Use --output json when a script needs the unchanged event objects.

After revocation, the Temporary Credential must no longer authorize the request. The API Instance and GitHub credential remain available for other approved Clients.

Clear the shell variables and delete the private temporary directory when you finish:

unset APIZ_TEMPORARY_CREDENTIAL APIZ_GITHUB_ENDPOINT
rm -r -- "$APIZ_WORKDIR"
unset APIZ_WORKDIR

The removal command targets only the private directory created at the start of this guide.