General API Adapter

Use General API when the upstream service speaks HTTP but does not need provider-specific parsing or signing. APIZ forwards the request, replaces its authentication, evaluates Policy against the HTTP method and path, and records redacted evidence.

What This Adapter Supports

• Upstream authentication: none, bearer, custom header, Basic, or query token.
• Agent credentials: APIZ bearer, X-APIZ-Key, query apiz_key, or Basic-shaped access.
• HTTP methods: GET, HEAD, POST, PUT, PATCH, and DELETE.
• Base-path append, base-path replacement, and fixed-base URL rewrite modes.
• Path and domain routing through generated Setup Manifest items.

Use a specialized adapter instead when APIZ must verify a protocol signature, understand provider resources, or expose provider-specific Policy actions.

Credential Boundary

The API Instance stores the upstream credential. The agent receives a separate APIZ Temporary Credential and generated endpoint. After the request is authenticated and allowed, APIZ removes caller authentication and injects the configured upstream bearer token, header, Basic password, or query token.

Allowed host, path-prefix, and method fields are review and Policy-template hints. They are not an enforced allowlist without Policy.

Prepare The Upstream Credential

Choose the narrowest credential the service supports. Record:

• the HTTPS base URL, including any stable base path;
• authentication mode and header/query name when applicable;
• one non-destructive connection-test path; and
• which methods and paths the agent genuinely needs.

Do not place the credential in config; credential values belong only in the write-only credential object.

Web Console

1. Open API Instances → Create API Instance → General API.
2. Enter a name and upstream Base URL.
3. Choose Authentication mode and enter the value only under Credential.
4. Review Allowed requests as intent hints. Attach a Policy when those paths or methods must be enforced.
5. Under Connection test, choose a safe method and path such as GET /health.
6. Review advanced rewrite and timeout settings. Test Connection is optional; failed testing does not prevent saving. Editing the form makes earlier test evidence outdated.
7. Select Create API Instance. The Configuration saved result retains the pre-save test outcome separately and clears credential inputs.
8. Select Connect a Client, then choose an existing Client or create one. The saved API is carried into the binding review.

If saving is rejected, correct the error in the same form. For an expired session, sign in through another tab and explicitly retry. If creation status is unknown, inspect API Instances before starting another creation; a lost response does not prove failure.

To edit an existing API, open Edit Configuration. APIZ checks the revision reviewed by the form before saving. On a conflict or unknown response, your non-secret edits remain available for copying; Check saved version compares the stored configuration with your submitted values. Review before choosing Reload and discard edits. This does not cancel a request already in flight. Test Saved Connection tests stored values, not unsaved edits. A test never enables a disabled API. Changing the API makes previous test evidence outdated; retesting is optional and old unversioned evidence is labeled unconfirmed.

CLI

Inspect the live descriptor before automation:

apiz adapter explain general
apiz api explain --adapter general

Create a bearer-authenticated connection without putting the token in shell history:

read -rsp "Upstream token: " UPSTREAM_TOKEN && printf '\n'
printf '%s' "$UPSTREAM_TOKEN" | jq -Rs '{credential: .}' |
apiz -o json api create \
  --adapter general \
  --name inventory-api \
  --config-json '{"http":{"base_url":"https://inventory.example.invalid"},"auth_mode":"bearer"}' \
  --test-config-json '{"method":"GET","url":"/health"}' \
  --credential-stdin
unset UPSTREAM_TOKEN

For Basic authentication, send {"username":"...","password":"..."} and set auth_mode to basic. For a custom header or query token, set auth_mode to custom_header or query and set auth_location to the required name.

Give An Agent Access

Bind the saved API Instance to a Client and issue access only for that binding:

apiz -o json client create --name inventory-agent
apiz client bind <client-id> --api-instance <api-instance-id> --alias inventory
apiz client credentials create <client-id> --binding inventory --ttl 1h --format curl

The result is one-time plaintext. Pass only the generated endpoint and APIZ credential to the agent. See Give an agent access for Web Console steps, recovery, and revocation.

Use It From The Agent

For the recommended bearer-shaped setup item:

curl -fsS \
  -H "Authorization: Bearer $APIZ_TEMPORARY_CREDENTIAL" \
  "$APIZ_ENDPOINT/v1/items"

The agent must use the generated APIZ endpoint, not the upstream base URL. SDKs that accept a base URL and bearer/API-key setting can use the equivalent values from the Setup Manifest.

When the issued manifest includes compatible Path and Domain connections, select one while rendering configuration with --connection item-id=connection-id. Both use the same issued authentication material. Shell, dotenv, prompt, cURL, SDK arguments and CLI flags retain the selected service endpoint. The default APIZ token's authority is not narrowed by choosing which API to configure.

Policy Actions And Resources

The normalized resource is general_path with the request path. Actions are:

The Allow read methods template allows only GET and HEAD. Use Structured Policy for method/path rules or Scripted Policy when bounded inspection or rewriting is required.

Connection Tests

The test accepts method, url or path, optional redacted headers, and an optional body. A full URL is allowed for one-off troubleshooting and must use a valid HTTP(S) origin. Tests contact the configured upstream, so begin with a read-only operation.

Evidence And Troubleshooting

• general_connection_status_failed: inspect the redacted status and confirm the test path and provider permission.
• Authentication failure: rotate the API Instance credential; do not replace an agent Temporary Credential unless APIZ authentication itself failed.
• Wrong upstream path: inspect the configured rewrite mode and the normalized path in Access Logs.
• Unexpected method allowed: attach an enforcing Policy; the allowed-method configuration is only a hint.

Use request evidence to distinguish APIZ denial from an upstream response.

Current Limitations

• Resources remain HTTP paths; the adapter does not infer provider objects.
• Provider-specific signing, pagination, OAuth refresh, webhook verification, and SDK semantics require a specialized adapter.
• Redirects and regex rewrites are advanced security-sensitive settings; keep them disabled unless the complete destination boundary has been reviewed.

For concurrent automation, first inspect apiz api get API_ID --output json, then pass its revision as apiz api update API_ID --expected-revision REVISION alongside the desired changes. A 409 requires reading and reviewing the new version. api list displays test_evidence_state; raw JSON retains the server's safe test metadata, including tested and recorded revisions.