API request workflow

API request workflow

Create an asset using protected credentials, repeat an ambiguous request, and poll accepted response work.

Create an inventory asset with a repeatable request, then poll asynchronous work by its returned operation ID. The resource references define individual operations and their permissions.

Prepare a client

Run these commands on an administrative workstation with curl. Use a working directory accessible only to the operator. Obtain the API origin and organization ID from Organization → API access. Store the bearer header in a permission-restricted file using the approved secret manager; its contents are Authorization: Bearer followed by the key, separated by a space. Do not commit that file.

The creation credential needs assets:write, Administrator authority, and access to the intended asset scope. The team team_security must already exist in the organization.

Restrict the bearer-header file before making requests:

Shell
chmod 600 AUTHORIZATION_HEADER_FILE

Replace AUTHORIZATION_HEADER_FILE with the path to the file supplied by your secret manager. Use the same path in subsequent commands.

Create an inventory asset

Save the asset request as asset.json in the restricted working directory:

JSON
{
  "name": "Store",
  "kind": "service",
  "locator": "store.example.com",
  "owner_id": "team_security",
  "tags": ["pilot"]
}

Replace the example name, locator, owner, and tags with the pilot service's values. Keep a copy of the exact request body until its result is known.

Send the request with an idempotency key dedicated to this intended creation:

Shell
curl --fail-with-body --silent --show-error \
  --header '@AUTHORIZATION_HEADER_FILE' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: REQUEST_KEY' \
  --data-binary @asset.json \
  'https://GUARD_HOST/api/v1/guard/organizations/ORGANIZATION_ID/assets'

Replace the following:

  • AUTHORIZATION_HEADER_FILE: The protected bearer-header file path.
  • REQUEST_KEY: A unique value for this creation, retained unchanged for retries.
  • GUARD_HOST: The hostname from Organization → API access.
  • ORGANIZATION_ID: The selected organization's stable ID.

The Asset API returns 201 with the new stable ID. Record that ID and confirm the returned locator identifies the intended service. This creates inventory; follow service onboarding to protect actual traffic.

Resolve an ambiguous response

If the connection fails before the result arrives, repeat the identical request with the same idempotency key and JSON file. Do not edit the body while reusing the key. The original result can be replayed during the 24-hour retention window. After that window, inspect the inventory before creating replacement work.

Poll accepted work

An approved response action can return 202 with an operation ID. Use the returned ID rather than creating a new action to check status. The credential for polling requires operations:read and visibility of the affected targets.

Read the accepted operation:

Shell
curl --fail-with-body --silent --show-error \
  --header '@AUTHORIZATION_HEADER_FILE' \
  --header 'Accept: application/json' \
  'https://GUARD_HOST/api/v1/guard/organizations/ORGANIZATION_ID/operations/OPERATION_ID'

Replace OPERATION_ID with the returned operation ID; use the same credential-file path, hostname, and organization ID as in the creation request.

Repeat reads with bounded backoff and respect Retry-After when supplied. Terminal states are succeeded, failed, canceled, or expired. Inspect every target result and the initiating feature's completion condition. For failed targets, correct the recorded cause and reconcile any completed effect before submitting replacement work. A local timeout stops polling; it does not cancel work. An isolation release requires a new authorized action.