APIZDocs

APIZ guide

Connect An API

Connect a service once as an API Instance. APIZ stores the upstream credential, tests the connection through the selected adapter, and lets Clients reference the connection without receiving the secret.

Before You Start

  • Install the CLI and sign in to the intended Team.
  • Obtain a credential from the upstream provider with only the permissions APIZ should be able to exercise.
  • Choose the built-in adapter that matches the service. Use the General adapter for an ordinary HTTP API without a specialized adapter.

Web Console

  1. Open API Instances and select Create API Instance.
  2. Choose the adapter. General API appears first when available; official provider adapters such as GitHub expose provider-specific fields and help.
  3. Enter a name, the non-secret connection settings, and the upstream credential only in fields marked Secret.
  4. Review Access boundary fields. Configuration hints are not Policy enforcement unless the field explicitly describes a non-bypassable boundary.
  5. Select Test Connection before saving. A failure remains visible with a plain-language diagnosis, recovery steps, stable code, and redacted target.
  6. Select Create API Instance. Choose View Details to inspect health, credential fingerprint evidence, configuration, Client usage, and recent Access Logs.

The credential inputs are write-only. Editing ordinary configuration never loads or resubmits the stored secret. Use the separate Rotate Credential action when the upstream credential changes.

From the API Instance list or detail page you can also Test Connection, Bind to Client, View Access Logs, View Audit, Disable, or Delete. Deletion shows current Client usage and requires confirmation.

To restrict every Data Plane request for the instance to known networks, add IP and Geo filtering. The source-IP allowlist is an APIZ-core pre-Policy boundary and works with every adapter.

CLI

List the adapters and inspect one descriptor before entering a secret:

apiz adapter list
apiz adapter describe github

The descriptor reports configuration fields, credential shape, connection-test presets, request behavior, and supported Setup Manifest render formats.

Connect GitHub

Read a token without echoing it, send it to APIZ over standard input, and remove it from the shell variable immediately afterward:

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

This example requires jq. GitHub uses https://api.github.com by default. The get_user_info preset validates the credential with GET /user without printing the credential.

Save the returned api_instance_id; later commands refer to the API Instance by that identifier.

Configuration hints such as allowed_repos help describe and render a GitHub connection, but do not enforce authorization by themselves. Attach a Policy when a repository or action must be enforced.

Connect A General HTTP API

The General adapter supports no authentication, bearer headers, basic authentication, custom headers, and query parameters. For a bearer-token API:

read -rsp "Upstream API token: " UPSTREAM_TOKEN && printf '\n'
printf '%s' "$UPSTREAM_TOKEN" \
  | jq -Rs '{credential: .}' \
  | apiz -o json api create general \
      --name inventory-api \
      --base-url https://inventory.example \
      --auth bearer-header \
      --rewrite append-to-base-path \
      --credential-stdin
unset UPSTREAM_TOKEN

Replace https://inventory.example with the real HTTPS upstream origin. Do not use a production credential in documentation, shell history, committed files, or test fixtures.

For non-secret public APIs, use --auth none and follow the command help for the accepted credential input.

Test And Inspect The Connection

Run the saved connection test:

apiz api test <api-instance-id>
apiz api show <api-instance-id>

A successful test means APIZ could authenticate and complete the adapter's safe test operation. It does not mean every possible upstream action is allowed.

If the test fails:

  1. confirm the adapter and upstream base URL;
  2. confirm the provider credential is active and has the required provider-side permission;
  3. inspect the safe error code and message returned by apiz api test;
  4. rotate the stored secret instead of creating a duplicate API Instance when the connection identity is unchanged.
apiz api rotate-secret <api-instance-id> \
  --credential-stdin \
  --confirm-promote

Use apiz api rotate-secret --help for adapter-specific input flags. Rotation does not require changing Client Bindings or Temporary Credentials.

Disable Access Without Deleting The Connection

apiz api disable <api-instance-id>
apiz api enable <api-instance-id>

Disabling an API Instance stops every Client Binding that references it. Client credentials may remain valid for other bindings.

Next: give an agent access.