IAM

Key Concepts

IAM issues the tokens that authorize every request and owns the model that decides what each caller may do. Services never make their own access decisions from scratch — they validate a token and ask IAM (directly or via cached policy) whether an action is allowed on a resource.

• Principal — any actor that can hold permissions: a member, an agent, an API key, or a service.
• Permission — a service:resource:action string (e.g. conversations:conversations:view).
• Grant — an allow/deny of a permission to a principal, optionally scoped to a specific resource.
• Role — a named bundle of permissions assigned to members.

Principals & Identities

Every actor on the platform is a principal with a principal_type and a stable id. Humans authenticate as members of a company; machines authenticate as API keys or agents. Because agents and services are principals in the same model as humans, a grant to an agent works exactly like a grant to a person — no confused-deputy shortcuts.

Companies & Members

A company is the top-level tenant boundary. Members belong to a company and hold roles that resolve to permissions. All resources across the platform are owned by a company, and cross-tenant access is impossible except through explicit connections.

# List members of a company
curl "https://platform.ergondata.ai/api/v1/iam/companies/{company_id}/members" \
  -H "Authorization: Bearer {token}"

# Assign a role to a member
curl -X POST https://platform.ergondata.ai/api/v1/iam/companies/{company_id}/members/{member_id}/roles \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "role_id": "{role_id}" }'

Grants & Role Assignments

IAM separates authority over role definitions from authority over members. Creating, editing, deleting, or configuring a role requires iam:company:roles:manage. Assigning or removing a role through a member's /members/{user_id}/roles routes requires iam:company:members:manage on that member.

The corresponding agent ToolDefs are iam.company.members.roles.list (requires iam:company:members:view), iam.company.members.roles.assign, and iam.company.members.roles.remove (both require iam:company:members:manage).

For IAM-native and organization-border permissions, use POST /v1/auth/companies/{company_id}/grants/batch to create multiple grants. Each operation crosses one subject with resources[] and permission_ids[], with at most 200 expanded grants in the request. Results are ordered, independent, and safe to retry: existing tuples return already_exists while invalid items return failed without rolling back valid grants.

The company-root route publishes iam.company.grants.batch_create. IAM also exposes the same batch contract for each governance zone:

• POST /v1/auth/companies/{company_id}/roles/access/grants/batch — iam.company.roles.access.grants.batch_create
• POST /v1/auth/companies/{company_id}/teams/access/grants/batch — iam.company.teams.access.grants.batch_create
• POST /v1/auth/companies/{company_id}/api-keys/access/grants/batch — iam.company.api_keys.access.grants.batch_create
• POST /v1/auth/companies/{company_id}/agents/access/grants/batch — iam.company.agents.access.grants.batch_create
• POST /v1/auth/companies/{company_id}/members/access/grants/batch — iam.company.members.access.grants.batch_create

API Keys & Tokens

Programmatic access uses API keys with the OAuth2 client-credentials flow. Exchange a key's client id and secret for a short-lived bearer token, then send it as Authorization: Bearer <token> on every request. An API key is itself a principal, so it only ever sees what it has been granted.

curl -X POST https://platform.ergondata.ai/api/v1/iam/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "{client_id}",
    "client_secret": "{client_secret}"
  }'

Agent Identities

Agents are first-class principals with their own identity and their own grants. When an agent acts, it authenticates as itself — the platform records the agent, not the human who triggered it, as the actor. This keeps every autonomous action auditable and bounded by exactly the permissions the agent was given.

Permission Checks

Services enforce access by checking whether a principal holds a permission on a resource. The check applies deny-over-allow and honors resource-scoped grants, so a broad allow can be narrowed by a specific deny. Most enforcement happens transparently inside each service, but IAM also exposes a validation endpoint for explicit checks.

curl -X POST https://platform.ergondata.ai/api/v1/iam/validate \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "permission": "conversations:conversations:view",
    "resource": "org/{company_id}/conversation/{conversation_id}"
  }'