IAM

Identity and access management for the entire platform. IAM is the central authority every other service trusts to authenticate tokens and evaluate permissions.

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, a team, an agent, an API key, or a service-owned principal such as a workflow or automation.
  • 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, teams, agents, or API keys.

For the conceptual model behind principals, zones, and connections, read Identities & boundaries. For the runtime enforcement model, see the Permissions guide.

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: a principal can only be connected to, and granted on, resources inside its own company.

# 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}" }'

Console Access

Each membership has a console access setting, on by default. With it off, the person uses only the apps shared with them: they land on the company's apps start page at /apps/{company_slug}, console pages send them back there, and the platform refuses their direct API requests for that company with HTTP 403 console_access_denied. Apps they may use keep working fully, and they remain an ordinary member: visible in IAM → Users, and able to receive roles, teams, service access, and grants. The Sign-in and access concept explains the model.

Changing it requires iam:company:members:manage on that member (Owner and Admin by default). Nobody can change their own console access (400 cannot_change_own_console_access), only a member who holds the system Owner role can change another system owner's console access (403), and switching it off is refused when the company would be left without a system owner who has console access (409 last_console_owner). A custom role named Owner does not count. The same 409 protects that last system owner elsewhere: removing them from the company, removing their owner role, or assigning them the Admin or Member role. Give another system owner console access first. Setting the value it already has succeeds and records nothing; a real change records iam.member.console_access_changed in IAM activity. The agent ToolDef is iam.company.members.access.update.

Give someone app-only access

  1. Invite the person and wait until they accept; console access can't be set on a pending invitation, and until you switch it off they have console access. Or find them under IAM → Users if they are already a member.
  2. Open the member and, in the Access section of the Overview tab, switch off Console access. The switch is disabled on your own page.
  3. On each app they should use, open the app's security page and grant them (or a team they belong to) the User preset.
  4. Give them, directly or through a team or role, the permissions those apps need on the underlying resources, such as creating items in a workflow. Apps act as the person, so they can never do more than the person may do.
  5. Ask them to sign in. If this is their only company, they land on the apps start page (“Your apps”) and see exactly the apps you granted; if they belong to several, they pick your company on the organizations page and it opens there. If it shows “No apps have been shared with you yet”, step 3 is missing.

To have the company's logo on their start page, upload a logo in IAM → Profile (see Brand your organization). Without one, the platform logo shows.

# Switch off console access for one member
curl -X PATCH https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{user_id}/access \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "console_access": false }'

To check who is app-only, look for the Apps only label in IAM → Users, or read console_access on each item of the member list. A signed-in person sees their own value per company in GET /v1/auth/me. To restore the console, send { "console_access": true }; reloading the page, or signing out and in again, makes every console page available.

Force Sign-in Through Your Start URL

Every company has a start URL, https://platform.ergondata.ai/apps/{company_slug}: signed out it is the company's own sign-in page, signed in it is the apps start page. You can require your members to sign in there for your company, for example people who should only ever reach your company through your intranet or your own single sign-on portal. Set it once for the whole organization, and override it for the people who should keep signing in at the platform login; the Sign-in and access concept explains the model.

  1. Open IAM → Sign-in and find the Access portal card. You need iam:company:settings (the Owner role by default).
  2. Set Access portal to Apps start page. From now on every member who inherits it lands on your apps start page after signing in, even with console access.
  3. Switch on Require sign-in through access portal. The switch is disabled while the access portal is Default.
  4. Give your members the start URL; copy it from Start URL, right below the switch. Their next sign-in for your company, or the next time they open it, must happen there.
  5. For anyone who should keep signing in at the platform login, open IAM → Users, select them, and in the Access section of the Overview tab set Access portal to Default (they land in the console) or Require sign-in through access portal to Off (they keep the apps start page). Inherit goes back to the organization's value, which the option shows in brackets.

To require it for only a few people instead, leave the organization on Default and set those members' Access portal to Apps start page and Require sign-in through access portal to On.

What the member sees at the platform login: their sign-in succeeds, but your company does not open. When they open it (or it is their only company), the browser goes to your start URL, which shows “{Company} asks you to sign in here” above your sign-in form. Signing in there works with the methods your company allows (see Set Sign-in Rules for Your Organization), with MFA when your company requires it. They do not sign out first: signing in at your start URL as the same account adds your company to the session they already have, and switching between companies does not ask again. Their other companies are unaffected and keep working from the platform login. Each sign-in at your start URL appears in the member's access history marked Access portal. See Signing in to several organizations.

Add the start URL to your SSO portal or intranet. The start URL is a plain, stable link, so it works as the app link in your identity provider's user portal (for example a bookmark app in Okta, or a linked application in Microsoft Entra ID's My Apps) or as a tile on your intranet. Use the full address, with your company slug, as the link's URL. People who open it while already signed in go straight to the apps start page (unless their session has not signed in at your start URL and needs to); people who are signed out get your sign-in page and can continue with the Google or Microsoft button.

Your portals are company sign-in pages too. The address of an app marked as a portal shows your company's own sign-in screen, designed in the app. A sign-in there counts as a sign-in at your start URL: it satisfies Require sign-in through access portal, follows the same sign-in rules and protection, and opens your company for the whole session, not only that app. The start URL itself keeps the built-in sign-in. See Portals.

# Everyone: land on the apps start page and sign in there
curl -X PATCH https://platform.ergondata.ai/v1/auth/companies/{company_id}/access-portal \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "access_portal": "platform_default", "require_portal_sign_in": true }'

# One member keeps the console and the platform login
curl -X PATCH https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{user_id}/access \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "access_portal": "default" }'

Every field of either request is optional: send only the ones you change, and an empty body is refused with 400 no_changes. Turning the requirement on while the resulting access portal is Default is refused with 400 access_portal_required; to undo both on the organization, send { "require_portal_sign_in": false, "access_portal": null } in one request. On a member, null goes back to inheriting. The organization's settings need iam:company:settings; a member's need iam:company:members:manage on the member, and you may set these two fields on your own membership too (only console access is never self-service), and only a system owner may change another system owner's. A change records iam.company.access_portal_changed or iam.member.access_portal_changed in IAM activity. A client that selects the company for such a member through the API gets 403 portal_sign_in_required with a portal_url to send the person to.

The requirement decides where people sign in and records it; it is not an extra authentication factor. The same account and credentials work at the start URL and at the platform login. To strengthen sign-in, set your organization's sign-in rules as well.

Land People in a Portal App

The access portal can also be one of your portal Apps: after signing in at the platform login, and when they open or switch to your company, the people it applies to land in that App instead of the console or the apps start page.

  1. Make sure the App is a portal: it has an auth module, a version with it is published, and it is marked as your portal. Only such Apps are offered.
  2. Open IAM → Sign-in and, in the Access portal card, pick the App under Portal apps. Members who inherit the access portal land there from their next sign-in.
  3. To send some members to another portal App, or keep some in the console, open IAM → Users, select them, and set Access portal in the Access section. Two members of the same company can land in different Apps.
  4. Optionally switch on Require sign-in through access portal. People who sign in anywhere else are sent to the App's address to sign in there; a sign-in at your start URL or at another of your portal Apps counts too.
# Everyone lands in the portal App
curl -X PATCH https://platform.ergondata.ai/v1/auth/companies/{company_id}/access-portal \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "access_portal": "app:{app_id}" }'

The App id goes in lower case after app:. An App that is not a portal people can sign in at now is refused with 400 access_portal_app_unavailable, and 503 means the App could not be checked at that moment; try again. The list of Apps you can pick is GET /api/v1/apps/portal-apps, which needs iam:company:settings or iam:company:members:manage on the whole organization. Someone who may manage only some members can still set an App through the API, but the screen does not offer the Apps to them.

If the App later stops being a portal, is unpublished or deleted, the setting stays as it is (shown as Unavailable app). People land on the apps start page while the App is not available, or when they may not use it, until it is back or you pick another value. Sign-ins at the App appear in the access history as Through {App}.

Set Sign-in Rules for Your Organization

Your organization decides how its members sign in: which methods it accepts, which Google Workspace domains and Microsoft tenants single sign-on must come from, and whether the two-factor code is asked on every sign-in. The rules apply to every session that opens your organization, including one that signed in at the platform login; the Sign-in and access concept explains each one. All of them need iam:company:settings (the Owner role by default) and live in IAM → Sign-in.

  1. In the Sign-in methods card, tick the Allowed methods: Email and password, Google, Microsoft.
  2. Optionally list your Google Workspace domains (for example acme.com) and Microsoft tenant ids, one per line. Leave both empty to accept any Google or Microsoft account. With entries in only one list, the other provider accepts nobody, so untick it.
  3. Choose Save.
  4. In the Two-factor authentication policy card, switch on Require two-factor authentication for all members and set Applies to: Password sign-ins (Google and Microsoft rely on their own two-factor settings) or Every sign-in (Google and Microsoft sign-ins also enter the platform's code).

What members see: your start URL offers only the methods you allow. A member whose session signed in some other way (with a password you no longer accept, a Google account outside your domains, or without the code you now ask for) is sent to your start URL when they open your organization, signs in there, and continues. Their other organizations are not affected. A refused Google or Microsoft sign-in at your start URL returns to the sign-in page with a message saying the organization does not allow that provider or that account. Your portals follow the same rules: build their sign-in screens to show only the methods your organization allows.

The Sign-in protection card on the same page sets how many failed attempts lock an account, for how long, and how long a session may stay idle. These values apply to sign-ins at your start URL and your portals, for your members. At the platform login a member of several organizations gets the strictest values among the organizations it opens for them, so your values may be stricter there because of another organization. A lock at your start URL blocks only your sign-in page, and an idle timeout ends only your organization's sign-in; the person keeps working in their other organizations. See Sign-in protection per organization.

Allow Only SSO

  1. Make sure single sign-on works for you: sign in at your start URL with Google or Microsoft. Saving rules that would refuse the way you are signed in right now is refused, so you cannot lock yourself out by mistake.
  2. Untick Email and password, add your Workspace domains or tenant ids, and save. The card shows Without password, this organization is SSO only.
  3. Keep at least one owner with a password and two-factor authentication. Owners can always sign in at the start URL with password and code (the sign-in page offers Owner? Sign in with password), so a broken SSO setup does not lock your organization out. Anyone else, including an owner without two-factor authentication, gets 403 sign_in_method_not_allowed when they try a password there.
# SSO only, from your Google Workspace
curl -X PATCH https://platform.ergondata.ai/v1/auth/companies/{company_id}/sign-in-methods \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "methods": ["google"], "google_workspace_domains": ["acme.com"] }'

# The two-factor code on every sign-in, Google included
curl -X PATCH https://platform.ergondata.ai/v1/auth/companies/{company_id}/mfa-policy \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "require_mfa": true, "require_mfa_for": "every_sign_in" }'

Send only the fields you change. A change that would refuse your own current sign-in returns 409 with reason sign_in_rules_lock_out_caller; sign in with a method the new rules accept, with your code when they ask for it, and save again. Each change records iam.company.sign_in_methods_changed or iam.company.mfa_policy_changed in IAM activity, with the previous values.

Brand Your Organization

A company shows two images: an icon and a logo. Both are set in IAM → Profile by someone with iam:company:settings (the Owner role by default).

  1. Under Icon, upload a square image, such as your brand mark on a solid background, at least 256 × 256 pixels. It appears next to your company in the company switcher and pickers, on the organizations page, and as the browser tab icon on your start URL. Without one, those places show your company's initials.
  2. Under Logo, upload Logo for light mode: a wide image, such as your full logo with a transparent background, around 4:1 (for example 800 × 200 pixels), dark enough to read on a light background.
  3. Optionally upload Logo for dark mode, a version that reads on a dark background. When only one logo is uploaded, it is used in both themes.

The logo appears in the console sidebar header, in the header of the apps start page, and on the sign-in page at your start URL. Without a logo, the sidebar and the start page show the platform logo (never the icon), and the sign-in page shows your icon with your company name, or the platform logo when there is no icon either. Each image accepts JPEG, PNG, WebP, or GIF up to 5 MB; uploading replaces the previous one, and removing one falls back at once.

Through the API, all three images go through the company image endpoint. Without kind it sets the icon; with kind=logo it sets the logo for variant=light (the default) or variant=dark. Sending a variant without kind=logo returns 400 variant_requires_logo.

# Icon
curl -X PUT https://platform.ergondata.ai/v1/auth/companies/{company_id}/avatar \
  -H "Authorization: Bearer {token}" \
  -F "file=@icon.png"

# Logo for light mode, then logo for dark mode
curl -X PUT "https://platform.ergondata.ai/v1/auth/companies/{company_id}/avatar?kind=logo&variant=light" \
  -H "Authorization: Bearer {token}" \
  -F "file=@logo-light.png"
curl -X PUT "https://platform.ergondata.ai/v1/auth/companies/{company_id}/avatar?kind=logo&variant=dark" \
  -H "Authorization: Bearer {token}" \
  -F "file=@logo-dark.png"

# Remove the dark-mode logo
curl -X DELETE "https://platform.ergondata.ai/v1/auth/companies/{company_id}/avatar?kind=logo&variant=dark" \
  -H "Authorization: Bearer {token}"

Icon changes record iam.company.avatar_updated and iam.company.avatar_removed; logo uploads record iam.company.logo_updated and removals iam.company.logo_removed, each with the variant, in IAM activity. Signed-in members read the images in GET /v1/auth/me; the signed-out sign-in page reads them, with the company name, from GET /v1/auth/portals/{company_slug}.

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

Resolve permission UUIDs from the appropriate access catalog and prefer one batch request over sequential single-grant calls. Service-local grants still belong on the owning resource's access endpoint, not IAM's organization-border route. See the IAM API reference for the shared request and response fields.

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}"
  }'

See Getting Started → Authentication for the full token flow.

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}"
  }'

Resources Inventory

Owners can list every federated zone in the organization (folders, workflows, worksheets, buckets, agents, apps and other zone roots) with its creator, its current managers and whether it is orphaned (no live manager to answer access requests). The list is an inventory, not access: seeing a zone grants nothing on its contents. To open a zone, request access and a manager approves it.

The routes require iam:company:resources:view, held by the owner role. Admins and members get it only when an owner grants it. Agents use iam.company.resources.list, iam.company.resources.get and iam.company.resources.summary.

# Orphaned workflow and bucket zones, newest first
curl "https://platform.ergondata.ai/api/v1/iam/companies/{company_id}/resources?services=workflows&services=buckets&status=orphaned" \
  -H "Authorization: Bearer {token}"

Ready for field-level detail? See the IAM API Reference.