APIZDocs

APIZ guide

Give An Agent Temporary API Access

A Client represents the agent, sandbox, application, or developer tool that will use APIZ. Bind only the API Instances it needs, then issue short-lived Temporary Credentials for its runtime.

Web Console

Create A Client And Binding

  1. Open Clients and select Create Client.
  2. Enter a clear runtime name and optional non-secret metadata.
  3. On Client detail, select Add Binding.
  4. Choose one ready API Instance and a lowercase Route Alias.
  5. Leave Allow access without a Client Access Credential off unless the route is intentionally public and its upstream-cost risk has been reviewed.
  6. Optionally attach a ready Policy, then select Add Binding.

The generated Binding Route Key is immutable and separate from the friendly Route Alias. A URL or endpoint address is not itself a credential unless the selected setup method explicitly creates a secret URL.

Issue Temporary Credentials

  1. On Client detail, select Create credentials.
  2. Choose the APIs to prepare, expiry, and optional purpose.
  3. Keep the recommended authentication types, or open Advanced authentication types when a tool requires a different credential shape.
  4. Review the credential count and select Create Credentials once.
  5. Use Copy APIZ token to save the default token independently, or select an API, compatible connection and configuration format before copying its output. Changing Path/Domain renders the existing credential without issuing another.

The result is intentional one-time plaintext. Copy feedback never repeats the credential. Closing the result must not place it in browser storage, URLs, analytics, or later ordinary page state.

Manage Existing Access

Select Manage credentials on the Client page. Each Credential Group row is one issuance operation. Active groups can be extended or revoked; revoking a group stops every still-active credential issued together. A recovered setup uses the default APIZ token and cannot recover expired or revoked access.

CLI

Create A Client And Binding

apiz -o json client create --name release-agent
apiz -o json client bind <client-id> \
  --api-instance <api-instance-id> \
  --alias github

The binding alias is the stable user-facing name for this route. Use a short, meaningful alias such as github, notion, or inventory.

A Client may have several bindings. A binding references exactly one API Instance. Changing or rotating the API Instance secret does not put that secret in the Client and does not require a new Client.

Issue Temporary Credentials

List the server-resolved choices first. The output reflects both Adapter support and the endpoints enabled in the current deployment. Its item column is accepted verbatim by client credentials create --item:

apiz client setup options <client-id>

Use --output json when an agent needs to select by recommended, credential_shape, endpoint.shape, or render_formats. Then create credentials for only the binding needed by the task and choose a bounded lifetime:

umask 077
apiz -o json client credentials create <client-id> \
  --binding github \
  --ttl 1h \
  > setup.json

For another compatible endpoint, inspect the issued items[].id and items[].connections, then render the saved manifest without issuing again:

apiz client setup render --client <client-id> \
  --manifest-file setup.json \
  --connection '<item-id>=<connection-id>' \
  --format shell

--usage custom --item remains available during creation when a different authentication type is required. Path/Domain variants of the same requirement share one issued credential. API selection prepares configuration and must not be treated as narrowing the default APIZ token's Client-wide authority.

The returned Setup Manifest contains plaintext APIZ credentials intentionally. Store it only in a private temporary location, pass the necessary item to the agent runtime, and remove the file when setup is complete.

Each item identifies its binding in meta.binding_alias and includes the APIZ endpoint and authentication material needed by the downstream tool. For example:

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

These values are APIZ endpoint and credential values. They are not the GitHub base URL and not the upstream GitHub token.

The command defaults to a two-hour lifetime when --ttl is omitted. Prefer an explicit TTL that matches the task.

Use A Tool-Friendly Format

APIZ can render the Setup Manifest for the selected adapter and tool. Supported formats can include json, shell, dotenv, aws-credentials, curl, prompt, sdk-args, and cli-flags; each adapter advertises the formats it actually supports.

apiz client credentials create <client-id> \
  --binding github \
  --ttl 1h \
  --format curl

Treat rendered output as sensitive even when it resembles an ordinary command or environment file.

List And Revoke Access

apiz client credentials list <client-id>
apiz client credentials revoke <credential-or-group-id>

One issuance operation creates a Credential Group. Revoking its group id revokes every still-active credential issued together. Revoke access when the task ends early, a runtime is discarded, or a credential may have leaked.

Scope Rules For Both Interfaces

  • Create a separate Client when two runtimes should have independent lifecycle, evidence, or revocation.
  • Select only the required bindings during issuance.
  • Use the shortest practical TTL.
  • Add a Policy when binding-level access is still broader than the task.
  • Do not enable unauthenticated binding access unless the public-access product behavior is intentional and separately reviewed.

Next: add request rules or inspect request evidence.

If Credential Creation Times Out

A timeout does not prove that creation failed. The Console keeps the original request and offers Check creation status. In the CLI, human output prints a creation operation ID before submitting:

apiz client credentials create cli_... --format shell
apiz client credentials status cli_... --operation-id 4d958d36-273f-4e5e-97b3-0668320ddae4

Replace the example UUID with the ID printed for your request, and keep the same Team and Client selected. Scripts using --output json should generate and supply their own UUID v4 with --operation-id before the first submission.

  • Committed: credentials were created. Do not issue again to retrieve their values. Inspect the returned group using client credentials show. An active default APIZ token can recover its group through client handoff setup; the operation ID and your operator login cannot. If no usable token was retained, follow the exact group link or CLI guidance, revoke that inaccessible group, then review current Client access before explicitly creating a replacement.
  • Not observed: the original request may still complete. If you retry, keep every creation option unchanged and pass the same --operation-id. In the Console, use Retry same request. A status error is not proof of absence.
  • Output rendering failed after creation: if you retained a manifest, use client setup render to format it without issuing again. The CLI does not automatically save a recovery file or replace shell output with secret JSON.

Expired and revoked history rows offer Review replacement. The review uses the Client's current active API Bindings and your current access; it does not reactivate or copy the old credentials. Opening or cancelling it creates nothing. After creating replacement credentials, update the consuming agent or tool and confirm a real request in Access Logs.

When recovering on another machine, --binding and --format select the configuration returned to that machine. They do not reduce what the active default APIZ token can recover: possession of that token authorizes the whole Credential Group until it expires or is revoked.

A new operation ID means a separate creation. Copy the non-secret ID before leaving an unresolved Console review; the browser does not persist it.

Choose A Connection After Issuance

Create credentials from the Client page after reviewing APIs and expiry. The result provides Copy APIZ token independently of the service configuration. Choose the API, a compatible Connection (Path or Domain Routing), and format before copying configuration. This reuses the same credentials and expiry.

For remote use, inject the token as APIZ_TOKEN and the public endpoint as APIZ_PROXY_URL. apiz client handoff setup --format json returns prepared items and their connection ids. Use --connection item_id=connection_id with handoff setup or client setup render to select one. Values come from that manifest, not guessed adapter names. Old groups without connection snapshots retain their original endpoint. Changing an S3 endpoint requires signing a new request; never edit the hostname of an already signed URL.