Accessing Arda APIs

All Arda API calls require a Bearer token (ARDA_API_KEY) and a standard set of request headers. Secrets are stored in 1Password vaults and injected at runtime using op run. This guide covers how to discover endpoints, construct authenticated requests, and call any Arda API across all environments.

Environments

Environment	Host	1Password env file
Production	`https://prod.alpha001.io.arda.cards`	`/api-test/1Password/prod.env`
Staging	`https://stage.alpha002.io.arda.cards`	`/api-test/1Password/stage.env`
Dev	`https://dev.alpha002.io.arda.cards`	`/api-test/1Password/dev.env`
Local	`http://localhost:8889`	`/api-test/1Password/local.env`

Each env file maps ARDA_API_KEY, BFF_CLIENT_ID, BFF_CLIENT_SECRET, and GATEWAY_BASE_URL to 1Password vault references using op:// URIs.

1Password Vaults

Environment	Vault
Production	`Arda-SystemsOAM`
Staging	`Arda-StageOAM`
Dev	`Arda-DevOAM`

Available APIs

All APIs share the same gateway host per environment. Replace {host} with the environment host from the table above.

Domain	API	Base path	OpenAPI spec
System	User Account	`/v1/user-account`	`{host}/v1/user-account/docs/openApi.json`
System	Tenant	`/v1/userTenant`	`{host}/v1/userTenant/docs/openApi.json`
System	AgentFor	`/v1/agent-for`	`{host}/v1/agent-for/docs/openApi.json`
Reference	Business Affiliate	`/v1/business-affiliate`	`{host}/v1/business-affiliate/docs/openApi.json`
Reference	Item	`/v1/item`	`{host}/v1/item/docs/openApi.json`
Resources	Kanban Cards	`/v1/kanban`	`{host}/v1/kanban/docs/openApi.json`
Transactions	Orders	`/v1/order`	`{host}/v1/order/docs/openApi.json`

Full API catalog: workspace-jmpicnic/knowledge-base/by-project/general/api-list.md

Required Headers

Every API request must include the following headers:

Header	Value	Required
`Authorization`	`Bearer ${ARDA_API_KEY}`	Always
`X-Request-ID`	A unique UUID per request	Always
`X-Tenant-Id`	The tenant UUID for the operation	Always
`X-Author`	Identifier of the caller (email or service name)	Always
`X-oidc-subject`	OIDC subject (user ID or service identifier)	Always
`Content-Type`	`application/json`	POST/PUT requests only

Prerequisites

Ensure 1Password CLI is authenticated before making any calls:

op signin

The op run wrapper injects ARDA_API_KEY and GATEWAY_BASE_URL from the vault into the subprocess environment. Never extract or hardcode these values in shell variables or scripts.

Request Patterns

GET request

TIMESTAMP_MS=$(date +%s000)

op run --env-file=/api-test/1Password/<env>.env -- \
  curl -s \
    "${GATEWAY_BASE_URL}/v1/item/item/<entity-id>?effectiveasof=${TIMESTAMP_MS}&recordedasof=${TIMESTAMP_MS}" \
    -H "Authorization: Bearer ${ARDA_API_KEY}" \
    -H "X-Request-ID: $(uuidgen)" \
    -H "X-Author: <author>" \
    -H "X-Tenant-Id: <tenant-id>" \
    -H "X-oidc-subject: <subject>" | jq .

Replace <env> with prod, stage, dev, or local.

POST request (example: history query)

TIMESTAMP_MS=$(date +%s000)

op run --env-file=/api-test/1Password/<env>.env -- \
  curl -s -X POST \
    "${GATEWAY_BASE_URL}/v1/item/item/<entity-id>/history" \
    -H "Authorization: Bearer ${ARDA_API_KEY}" \
    -H "X-Request-ID: $(uuidgen)" \
    -H "X-Author: <author>" \
    -H "X-Tenant-Id: <tenant-id>" \
    -H "X-oidc-subject: <subject>" \
    -H "Content-Type: application/json" \
    -d '{
      "since": { "effective": 0, "recorded": 0 },
      "until": { "effective": '"${TIMESTAMP_MS}"', "recorded": '"${TIMESTAMP_MS}"' }
    }' | jq .

PUT request

op run --env-file=/api-test/1Password/<env>.env -- \
  curl -s -X PUT \
    "${GATEWAY_BASE_URL}/v1/item/item/<entity-id>" \
    -H "Authorization: Bearer ${ARDA_API_KEY}" \
    -H "X-Request-ID: $(uuidgen)" \
    -H "X-Author: <author>" \
    -H "X-Tenant-Id: <tenant-id>" \
    -H "X-oidc-subject: <subject>" \
    -H "Content-Type: application/json" \
    -d '<json-body>' | jq .

DELETE request

op run --env-file=/api-test/1Password/<env>.env -- \
  curl -s -X DELETE \
    "${GATEWAY_BASE_URL}/v1/item/item/<entity-id>" \
    -H "Authorization: Bearer ${ARDA_API_KEY}" \
    -H "X-Request-ID: $(uuidgen)" \
    -H "X-Author: <author>" \
    -H "X-Tenant-Id: <tenant-id>" \
    -H "X-oidc-subject: <subject>" | jq .

Bitemporal Query Parameters

Most GET endpoints support optional time-travel parameters:

Parameter	Type	Description
`effectiveasof`	Epoch milliseconds	Effective time boundary for the query
`recordedasof`	Epoch milliseconds	Recorded time boundary for the query

When omitted, the server defaults to “now”. To read current state explicitly, generate a timestamp and append it to the query string:

TIMESTAMP_MS=$(date +%s000)
# append: ?effectiveasof=${TIMESTAMP_MS}&recordedasof=${TIMESTAMP_MS}

Operational Notes

Use $(uuidgen) for X-Request-ID to guarantee uniqueness across requests.
Pipe output through jq . for readable JSON formatting.
Redirect large response payloads to a scratch/ subdirectory rather than printing them to the terminal.
The GATEWAY_BASE_URL and ARDA_API_KEY variables are populated by op run from the env file — reference them directly in the curl command without first extracting them.
The 1Password CLI may prompt for biometric authentication, which blocks until confirmed. Be prepared to authenticate when running op run commands.

Inspecting Cluster Logs — Inspect pod and CloudWatch logs.
API Testing with Bruno — Run the full Bruno API test suite.