Sub-Accounts

Sub-accounts let a parent account organize work under separately-tracked child accounts — useful when you serve multiple customers, business units, or brands from a single Autena integration. Each sub-account has its own data isolation and can be billed and reported on independently, while the parent retains full management control.

There are two pieces to working with sub-accounts:

1. Managing sub-accounts — create them, mint their API keys, and report on usage.
2. Acting as a sub-account — scoping an ordinary API request (tracking, rates, TMS, …) to one sub-account with the X-Autena-Acting-Tenant header.

Acting as a sub-account: the header

Add the X-Autena-Acting-Tenant header to any request to scope it to a specific sub-account. It accepts three forms:

Value	Meaning
self	Act as your own account. This is the default when the header is omitted.
<uuid>	Act as the sub-account with this Autena tenant UUID.
ext:<external_id>	Act as the sub-account whose external_id matches <external_id>.

curl -X POST https://api.autena.ai/v1/shipments \
  -H "Authorization: Bearer atn_YOUR_API_KEY" \
  -H "X-Autena-Acting-Tenant: ext:acme-logistics" \
  -H "Content-Type: application/json" \
  -d '{ "transport_mode": "ocean", "carrier": "MAEU", "identifiers": { "mbl": "MEDU1234567" } }'

When the header is required

Required on writes once you have sub-accounts

Once your account has at least one active sub-account, the X-Autena-Acting-Tenant header is required on every write request (POST, PUT, PATCH, DELETE). Omitting it returns 400 Bad Request.

This prevents a write from silently landing on the wrong account. Send X-Autena-Acting-Tenant: self to write against the parent explicitly.

Read requests (GET) never require the header — they default to self.

Who can act as whom

• A parent key may act as itself (self) or as any of its active sub-accounts. Deactivated sub-accounts are rejected.
• A sub-account key may only act as itself. Any other value returns 403 Forbidden.

Managing sub-accounts

All management endpoints live under /v1/sub-accounts and require a parent API key — sub-account keys cannot manage sub-accounts. Write operations require the sub_accounts:write scope; reads require sub_accounts:read.

Create a sub-account

curl -X POST https://api.autena.ai/v1/sub-accounts \
  -H "Authorization: Bearer atn_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Logistics",
    "external_id": "acme-logistics"
  }'

external_id is optional but recommended — it lets you address the sub-account in the X-Autena-Acting-Tenant header (ext:acme-logistics) using your own identifier instead of the Autena UUID.

Mint an API key for a sub-account

curl -X POST https://api.autena.ai/v1/sub-accounts/{sub_id}/api-keys \
  -H "Authorization: Bearer atn_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "acme-prod", "scopes": ["tracking:read", "tracking:write"] }'

The API key and client secret are returned once — store them securely.

Other operations

Operation	Endpoint
List sub-accounts	GET /v1/sub-accounts
Get a sub-account	GET /v1/sub-accounts/{sub_id}
Update a sub-account	PATCH /v1/sub-accounts/{sub_id}
Deactivate / reactivate	POST /v1/sub-accounts/{sub_id}/deactivate · /reactivate
List a sub-account's keys	GET /v1/sub-accounts/{sub_id}/api-keys
Revoke a key	POST /v1/sub-accounts/{sub_id}/api-keys/{key_id}/revoke
Usage report	GET /v1/sub-accounts/usage?from=…&to=…

See the full request and response shapes in the API Reference.