IAM API
Authenticate principals and manage organizations, members, teams, roles, API keys, agent identities, service entitlements, grants, zone connections, connection requests, per-instance access, invitations, activity, IP allowlists, working hours, and principal statuses. Base path /v1/auth (account, identity, and access) plus gateway-rooted /v1 routes for IP allowlists, status types, working hours, and principal statuses.
/v1/authAutomation triggers: view every IAM event, payload field, and predicate.
Authentication
Exchange API key credentials for short-lived access tokens.
/v1/auth/tokenCreate Access Token
Exchange API key credentials (client_id + client_secret) for a short-lived bearer token. Create API keys in the console under IAM → API Keys. Issuance is gated by Working Hours Strict Mode and IP allowlists when configured for the key's principal.
No authentication required.
Request Body
| Name | Type | Description |
|---|---|---|
client_id* | string | API key client ID |
client_secret* | string | API key client secret |
Response Fields
| Name | Type | Description |
|---|---|---|
access_token* | string | Bearer token for API calls |
token_type* | string | Always "bearer" |
expires_in* | integer | Token lifetime in seconds |
curl -X POST https://platform.ergondata.ai/v1/auth/token \
-H "Content-Type: application/json" \
-d '{
"client_id": "ek_your-client-id",
"client_secret": "eks_your-client-secret"
}'Response
200 OK{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer",
"expires_in": 3600
}User Authentication
Register users, sign in (with optional MFA challenge), refresh sessions, select a company context, and inspect the current principal.
/v1/auth/registerRegister User
Create a new user account. A verification email is sent to the address. Returns 403 (Sign-up is not open to this address) when the environment limits account creation and the address is not allowed; nothing is created or sent.
No authentication required.
Request Body
| Name | Type | Description |
|---|---|---|
email* | string (email) | User email address |
password* | string | Password (minimum 12 characters, with at least 3 of: lowercase, uppercase, digits, symbols) |
name* | string | Display name (minimum 1 character) |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | User ID |
email* | string | User email |
name* | string | Display name |
is_active* | boolean | Whether the account is active |
avatar_url | string | null | Avatar URL |
created_at* | string (date-time) | Creation timestamp |
curl -X POST https://platform.ergondata.ai/v1/auth/register \
-H "Content-Type: application/json" \
-d '{
"email": "jane@example.com",
"password": "s3cret-passphrase",
"name": "Jane Doe"
}'Response
201 Created{
"id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"email": "jane@example.com",
"name": "Jane Doe",
"is_active": true,
"avatar_url": null,
"created_at": "2026-01-05T14:20:00Z"
}/v1/auth/loginLogin
Authenticate with email and password. Returns an access token, or an MFA challenge (mfa_required: true) when the user must complete multi-factor authentication before a token is issued. Send entry_company_slug when the sign-in happens on a company's start URL (/apps/{company_slug}) or one of its app addresses (/apps/{company_slug}/{app_slug}): the session then opens that company, including after MFA and token refresh, and lists only the companies it signed in at, plus any company you create or join from it. Without entry_company_slug the sign-in is at the platform login: the session lists every company you belong to and opens each one except those where your membership has require_portal_sign_in. Signing in again as the same account with the session's refresh-token cookie adds to what the session opens (another company's start URL, or the platform login); signing in as a different account replaces the session. An unknown or deleted slug is ignored and the response is the same. With entry_company_slug, entry_app_id names the portal App of that company the sign-in is made in: the company's access history records it, through MFA too; an App that is not that company's is ignored. When the company leaves password out of its sign-in methods, a correct password at its start URL returns 403 sign_in_method_not_allowed, except for an owner with a two-factor factor, who gets the MFA challenge. A session that signed in at the platform login with a method a company does not accept is asked to sign in at that company's start URL before it opens the company.
No authentication required.
Request Body
| Name | Type | Description |
|---|---|---|
email* | string (email) | User email address |
password* | string | User password |
entry_company_slug | string | null | Slug of the company whose start URL the person is signing in at (max 255 characters). Omit for the platform login. |
entry_app_id | UUID | null | With entry_company_slug: the id of the company's portal App the person is signing in at. Recorded in the company's access history. |
Response Fields
| Name | Type | Description |
|---|---|---|
access_token | string | Bearer token (present on success, absent on MFA challenge) |
token_type | string | Always "bearer" on success |
company_id | string (UUID) | null | Active company bound to the token, if any |
mfa_required | boolean | Present and true when MFA must be completed |
mfa_token | string | Challenge token to pass to MFA verify (challenge only) |
attempts_left | integer | Remaining MFA attempts (challenge only) |
enrollment_required | boolean | Whether the user must enroll a factor first (challenge only) |
curl -X POST https://platform.ergondata.ai/v1/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "jane@example.com",
"password": "s3cret-passphrase"
}'Response
200 OK{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer",
"company_id": null
}/v1/auth/refreshRefresh Session
Mint a fresh access token from the refresh-token cookie set at login. Returns a new bearer token. The session keeps every place it signed in at (the platform login and each company's start URL) after refresh, except a place idle longer than its idle timeout: that sign-in ends, and companies opened only through it need a new sign-in there. When no place is left the response is 401 and the cookie is cleared. Send company_id, the company in use, so the place that opens it counts as used; without it the platform login counts as used, when the session signed in there. Send touch: false for a refresh the person did not ask for, such as on page load, so nothing counts as used.
Requires the refresh_token cookie.
Request Body
| Name | Type | Description |
|---|---|---|
company_id | string (UUID) | null | The company in use. The place this session opens it through counts as used now. The body is optional. |
touch | boolean | Default true. false when the person did not make this call themselves: nothing counts as used. |
Response Fields
| Name | Type | Description |
|---|---|---|
access_token* | string | New bearer token |
token_type | string | Always "bearer" |
company_id | string (UUID) | null | Active company bound to the token, if any |
curl -X POST https://platform.ergondata.ai/v1/auth/refresh \
--cookie "refresh_token={refresh_token}" \
-H "Content-Type: application/json" \
-d '{"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe"}'Response
200 OK{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe"
}/v1/auth/logoutLogout
Invalidate the current session and clear the refresh-token cookie.
Bearer token required.
curl -X POST https://platform.ergondata.ai/v1/auth/logout \
-H "Authorization: Bearer {token}"Response
204 No Content/v1/auth/idle-sign-outIdle Sign-Out
End this session's sign-in at one place after the person was idle there: the platform login ("platform") or a company's start URL (the company id), as sign_in_page on each company of Get Current Principal. Companies opened only through that place need a new sign-in there; the session keeps its other places and its cookie. Returns an access token for what is left, or 401 (cookie cleared) when that was the last place. A missing or invalid session is also 401, with the cookie left as it is; a sign_in_page that is neither is 422.
Requires the refresh_token cookie.
Request Body
| Name | Type | Description |
|---|---|---|
sign_in_page* | string | "platform" or a company id (UUID) |
Response Fields
| Name | Type | Description |
|---|---|---|
access_token* | string | Bearer token for the places the session keeps |
token_type | string | Always "bearer" |
curl -X POST https://platform.ergondata.ai/v1/auth/idle-sign-out \
--cookie "refresh_token={refresh_token}" \
-H "Content-Type: application/json" \
-d '{"sign_in_page": "platform"}'Response
200 OK{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer"
}/v1/auth/select-active-companySelect Active Company
Mint a fresh access token bound to a company you belong to, so downstream services derive the active tenant from the token. Membership is enforced server-side (403 if you do not belong, or if outside working hours under Strict Mode). The session opens a company it signed in at through that company's start URL. Without that sign-in, a company opens while your membership there does not have require_portal_sign_in, in two cases: the session signed in at the platform login (any company you belong to), or you created or joined the company from this session. In every case the sign-in must also meet the company's sign-in rules: an allowed method, an account from a listed Google Workspace domain or Microsoft tenant when the company lists any, and the platform's two-factor code when the company requires it on every sign-in. Otherwise the response is 403 with detail {"reason": "portal_sign_in_required", "portal_url": "https://platform.ergondata.ai/apps/{company_slug}"}, or the address of the portal App that is the person's access portal (/apps/{company_slug}/{app_id}): send the person to portal_url to sign in there, which adds that company to the same session. Requests for that company's data are refused until then. Your other companies are unaffected.
Bearer token required.
Request Body
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company to activate (must be a company you belong to) |
touch | boolean | Default true: the place this session opens the company through counts as used. false when the person did not choose the company themselves, such as on a redirect. |
Response Fields
| Name | Type | Description |
|---|---|---|
access_token* | string | Company-scoped bearer token |
token_type | string | Always "bearer" |
company_id | string (UUID) | null | Company bound to the token |
console_access | boolean | null | Whether you have console access in this company. When false, you can open and use only the apps shared with you, from the company's apps start page (/apps/{company_slug}); other requests for this company's data return 403 console_access_denied or are answered as if you had no access (for example, an empty list). Only this endpoint sets the field; sign-in and token refresh return null. |
curl -X POST https://platform.ergondata.ai/v1/auth/select-active-company \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe"}'Response
200 OK{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"console_access": true
}/v1/auth/meGet Current Principal
Return the authenticated user plus the company memberships this session lists (roles, permissions, enabled services, console access, access portal, sign-in requirement, and the company's icon and logos per company), ordered by company name, and platform-level permissions. A session that signed in at the platform login lists every membership; a session that signed in only at company start URLs lists those companies, plus any company created or joined from it.
Bearer token required.
Response Fields
| Name | Type | Description |
|---|---|---|
user* | object | The authenticated user (UserResponse) |
companies* | array | Company memberships with roles, permissions, and services |
platform_permissions | array<string> | Platform-level permissions |
platform_sign_in | boolean | Whether this session signed in at the platform login. When false, the session signed in only at company start URLs, and companies lists those plus any company created or joined from the session. |
session_idle_timeout_minutes | integer | Idle timeout in minutes of the platform login when this session signed in there, else the strictest across its start URLs (0 = none). Each company carries its own place's as idle_timeout_minutes. |
curl https://platform.ergondata.ai/v1/auth/me \
-H "Authorization: Bearer {token}"Response
200 OK{
"user": {
"id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"email": "jane@example.com",
"name": "Jane Doe",
"is_active": true,
"avatar_url": null,
"locale": "pt-BR",
"created_at": "2026-01-05T14:20:00Z"
},
"companies": [
{
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"company_name": "Acme Corp",
"company_slug": "acme-corp",
"company_avatar_url": null,
"company_logo_url": null,
"company_logo_dark_url": null,
"roles": ["owner"],
"permissions": ["iam:company:members:view"],
"services": ["agents", "workflows"],
"console_access": true,
"access_portal": null,
"require_portal_sign_in": false
}
],
"platform_permissions": [],
"platform_sign_in": true
}/v1/auth/meUpdate Current Principal
Partial update of the authenticated user. Omitted fields are left unchanged. Today the only field is locale. This session route is intentionally not an agent tool.
Bearer token required.
Request Body
| Name | Type | Description |
|---|---|---|
locale | string | null | Set to en-US or pt-BR. JSON null clears the stored preference so the UI falls back to cookie / Accept-Language / product default. |
curl -X PATCH https://platform.ergondata.ai/v1/auth/me \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"locale": "en-US"}'Response
200 OK{
"user": {
"id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"email": "jane@example.com",
"name": "Jane Doe",
"is_active": true,
"avatar_url": null,
"locale": "en-US",
"created_at": "2026-01-05T14:20:00Z"
},
"companies": [],
"platform_permissions": []
}/v1/auth/portals/{company_slug}Get Start URL Brand
Return the public brand of a company's start URL (/apps/{company_slug}) so a signed-out sign-in page can show it: the company name, slug, icon, logos, and the sign-in methods it allows, and nothing else. Responses are not cached (Cache-Control: no-store) and the route is rate limited like the other public sign-in routes. Returns 404 Not found for an unknown or deleted company; show a generic sign-in page then. This sign-in support route is intentionally not an agent tool.
No authentication required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_slug* | string | Company slug from the start URL |
Response Fields
| Name | Type | Description |
|---|---|---|
company_name* | string | Company name |
company_slug* | string | Company slug |
company_avatar_url | string | null | Company icon as a temporary signed URL, or null |
company_logo_url | string | null | Logo for light mode as a temporary signed URL, or null |
company_logo_dark_url | string | null | Logo for dark mode as a temporary signed URL, or null (use company_logo_url in both themes then) |
sign_in_methods* | array<"password" | "google" | "microsoft"> | The sign-in methods the company allows; show only these. Owners can still use password with their two-factor code when it is left out. |
curl https://platform.ergondata.ai/v1/auth/portals/acme-corpResponse
200 OK{
"company_name": "Acme Corp",
"company_slug": "acme-corp",
"company_avatar_url": null,
"company_logo_url": "https://ergon-files.s3.us-east-1.amazonaws.com/avatars/companies/c0ffee00-cafe-babe-dead-beefcafebabe/logo-light.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&X-Amz-Signature=...",
"company_logo_dark_url": null,
"sign_in_methods": ["password", "google", "microsoft"]
}Account & Verification
Email verification, password resets, and credential changes for the current user.
/v1/auth/verify-emailVerify Email
Confirm a user's email address using the token from the verification email.
No authentication required.
Request Body
| Name | Type | Description |
|---|---|---|
token* | string | Verification token from the email |
curl -X POST https://platform.ergondata.ai/v1/auth/verify-email \
-H "Content-Type: application/json" \
-d '{"token": "verify-token-abc123"}'Response
200 OK{}/v1/auth/resend-verificationResend Verification Email
Send a fresh email-verification link to the given address.
No authentication required.
Request Body
| Name | Type | Description |
|---|---|---|
email* | string (email) | Email to resend verification to |
curl -X POST https://platform.ergondata.ai/v1/auth/resend-verification \
-H "Content-Type: application/json" \
-d '{"email": "jane@example.com"}'Response
200 OK{}/v1/auth/forgot-passwordForgot Password
Trigger a password-reset email. Always returns 200 with the same answer, so it never reveals which emails exist or who belongs to a company. The emailed link opens the platform's reset page with the token. With return_to, and only when the account is a member of the company in that App address, the link opens the App address with reset_token instead, so the App's sign-in screen can set the new password; for anyone else return_to is ignored and the email carries the platform's link. Either way the token goes to Reset Password. A return_to that is not an App address is 422.
No authentication required.
Request Body
| Name | Type | Description |
|---|---|---|
email* | string (email) | Account email address |
return_to | string | An App address, /apps/{company_slug}/{app_slug}. When the account is a member of that company, the emailed link opens that address so the App's sign-in screen can set the new password; otherwise it is ignored. |
curl -X POST https://platform.ergondata.ai/v1/auth/forgot-password \
-H "Content-Type: application/json" \
-d '{"email": "jane@example.com", "return_to": "/apps/acme/customer-portal"}'Response
200 OK{
"detail": "If that email exists, a password reset link has been sent"
}/v1/auth/reset-passwordReset Password
Set a new password using the token from a password-reset email.
No authentication required.
Request Body
| Name | Type | Description |
|---|---|---|
token* | string | Reset token from the email |
password* | string | New password (minimum 12 characters, with at least 3 of: lowercase, uppercase, digits, symbols) |
curl -X POST https://platform.ergondata.ai/v1/auth/reset-password \
-H "Content-Type: application/json" \
-d '{
"token": "reset-token-abc123",
"password": "new-s3cret-passphrase"
}'Response
200 OK{}/v1/auth/change-passwordChange Password
Change the authenticated user's password by supplying the current one.
Bearer token required.
Request Body
| Name | Type | Description |
|---|---|---|
current_password* | string | Current password |
new_password* | string | New password (minimum 12 characters, with at least 3 of: lowercase, uppercase, digits, symbols) |
curl -X POST https://platform.ergondata.ai/v1/auth/change-password \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"current_password": "s3cret-passphrase",
"new_password": "new-s3cret-passphrase"
}'Response
200 OK{}/v1/auth/change-emailChange Email
Request an email-address change. A confirmation link is sent to the new address; the change takes effect after it is verified.
Bearer token required.
Request Body
| Name | Type | Description |
|---|---|---|
new_email* | string (email) | New email address |
password* | string | Current password for confirmation |
curl -X POST https://platform.ergondata.ai/v1/auth/change-email \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"new_email": "jane.doe@example.com",
"password": "s3cret-passphrase"
}'Response
200 OK{}/v1/auth/verify-email-changeVerify Email Change
Confirm a pending email-address change using the token from the confirmation email.
No authentication required.
Request Body
| Name | Type | Description |
|---|---|---|
token* | string | Email-change confirmation token |
curl -X POST https://platform.ergondata.ai/v1/auth/verify-email-change \
-H "Content-Type: application/json" \
-d '{"token": "email-change-token-abc123"}'Response
200 OK{}Profile, Avatar & Identities
Read the caller's own identity inside a company, and manage the current user's avatar and federated (SSO) identity links.
/v1/auth/companies/{company_id}/meGet Caller Identity
Return the authenticated caller's own identity in a company: principal, display name, member/user ids and email (members only), the teams the caller belongs to (directly or inherited through parent/nested teams) and the roles it holds (directly or through a team). Works for members, agents, and API keys; Apps call it through the iam.company.me.get tool to learn who the viewer is. Self-service: only company membership is required, and the response never includes other principals or permission lists. A role held through several edges is listed once per source.
Bearer token. Caller must belong to the company (403 otherwise; 404 if unknown).
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID (Apps and agents inject the current company) |
Response Fields
| Name | Type | Description |
|---|---|---|
principal_id* | string (UUID) | The caller's company-scoped principal ID |
principal_type* | string | Principal kind, e.g. "member", "agent", "api_key" |
company_id* | string (UUID) | Company the identity belongs to |
company_member_id* | string (UUID) | null | Membership ID (members only) |
user_id* | string (UUID) | null | User ID (members only) |
display_name* | string | User name for members; agent or API key name otherwise |
email* | string | null | User email (members only) |
teams* | array | Teams the caller belongs to |
roles* | array | Roles the caller holds, one entry per source |
curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/me \
-H "Authorization: Bearer {token}"Response
200 OK{
"principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"principal_type": "member",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"company_member_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d",
"user_id": "0d1e2f3a-4b5c-4d6e-8f7a-8b9c0d1e2f3a",
"display_name": "Ana Souza",
"email": "ana@example.com",
"teams": [
{
"id": "7ea11000-0000-4000-8000-000000000002",
"name": "Billing",
"parent_team_id": "7ea11000-0000-4000-8000-000000000001",
"direct": true
},
{
"id": "7ea11000-0000-4000-8000-000000000001",
"name": "Finance",
"parent_team_id": null,
"direct": false
}
],
"roles": [
{
"id": "40000000-0000-4000-8000-000000000003",
"name": "member",
"is_system": true,
"source": "direct"
},
{
"id": "40000000-0000-4000-8000-0000000000aa",
"name": "billing-clerk",
"is_system": false,
"source": "7ea11000-0000-4000-8000-000000000001"
}
]
}/v1/auth/me/avatarUpload User Avatar
Upload or replace the current user's avatar image (multipart/form-data).
Bearer token required.
Request Body
| Name | Type | Description |
|---|---|---|
file* | binary (multipart/form-data) | Image file to upload |
curl -X PUT https://platform.ergondata.ai/v1/auth/me/avatar \
-H "Authorization: Bearer {token}" \
-F "file=@avatar.png"Response
200 OK{
"avatar_url": "https://ergon-files.s3.us-east-1.amazonaws.com/avatars/b10f8a92-1234-5678-9abc-def012345678/9b1c.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&X-Amz-Signature=..."
}/v1/auth/me/avatarDelete User Avatar
Remove the current user's avatar image.
Bearer token required.
curl -X DELETE https://platform.ergondata.ai/v1/auth/me/avatar \
-H "Authorization: Bearer {token}"Response
200 OK{}/v1/auth/me/identitiesList My Identities
List the federated (SSO) identities linked to the current user.
Bearer token required.
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Identity link ID |
provider* | string | Identity provider slug |
email_at_link* | string | Email returned by the provider when linked |
last_login_at | string (date-time) | null | Most recent login via this identity |
created_at* | string (date-time) | When the link was created |
curl https://platform.ergondata.ai/v1/auth/me/identities \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "11111111-2222-3333-4444-555555555555",
"provider": "google",
"email_at_link": "jane@example.com",
"last_login_at": "2026-02-01T09:00:00Z",
"created_at": "2026-01-05T14:20:00Z"
}
]/v1/auth/me/identities/{identity_id}Unlink Identity
Remove a federated identity link from the current user.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
identity_id* | string (UUID) | Identity link ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/me/identities/{identity_id} \
-H "Authorization: Bearer {token}"Response
204 No ContentMulti-Factor Authentication
Enroll, verify, disable, and recover TOTP-based multi-factor authentication.
/v1/auth/mfa/statusMFA Status
Report whether MFA is enabled for the current user and how many recovery codes remain.
Bearer token required.
Response Fields
| Name | Type | Description |
|---|---|---|
enabled* | boolean | Whether a confirmed factor exists |
company_requires_mfa | boolean | Whether the active company mandates MFA |
enrolled_at | string (date-time) | null | When the factor was enrolled |
last_used_at | string (date-time) | null | When MFA was last used |
recovery_codes_remaining | integer | Unused recovery codes left |
curl https://platform.ergondata.ai/v1/auth/mfa/status \
-H "Authorization: Bearer {token}"Response
200 OK{
"enabled": true,
"company_requires_mfa": false,
"enrolled_at": "2026-01-10T08:00:00Z",
"last_used_at": "2026-02-01T09:00:00Z",
"recovery_codes_remaining": 8
}/v1/auth/mfa/setupBegin MFA Setup
Start TOTP enrollment. Returns a secret and otpauth URI to render as a QR code. Pass mfa_token during forced enrollment (mid-login); omit it for voluntary enrollment while authenticated.
Bearer token or MFA challenge token.
Request Body
| Name | Type | Description |
|---|---|---|
label | string | null | Optional label for the authenticator entry (max 64 chars) |
mfa_token | string | null | Challenge token, required only during forced enrollment |
Response Fields
| Name | Type | Description |
|---|---|---|
secret* | string | TOTP shared secret |
otpauth_uri* | string | otpauth:// URI for QR codes |
curl -X POST https://platform.ergondata.ai/v1/auth/mfa/setup \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"label": "Ergon"}'Response
200 OK{
"secret": "JBSWY3DPEHPK3PXP",
"otpauth_uri": "otpauth://totp/Ergon:jane@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Ergon"
}/v1/auth/mfa/setup/verifyVerify MFA Setup
Confirm TOTP enrollment with a code from the authenticator app. Returns one-time recovery codes (shown only here) and, during forced enrollment, an access token to finish login. A forced enrollment that started from a login with entry_company_slug keeps it in the session. The same call completes a Google or Microsoft sign-in whose company requires two-factor on every sign-in, when the person sets up a factor first.
Bearer token or MFA challenge token.
Request Body
| Name | Type | Description |
|---|---|---|
code* | string | Current 6-digit TOTP code |
mfa_token | string | null | Challenge token, required only during forced enrollment |
Response Fields
| Name | Type | Description |
|---|---|---|
recovery_codes* | array<string> | One-time recovery codes (stored hashed; shown once) |
access_token | string | null | Bearer token (populated during forced enrollment) |
token_type | string | Always "bearer" |
curl -X POST https://platform.ergondata.ai/v1/auth/mfa/setup/verify \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"code": "123456"}'Response
200 OK{
"recovery_codes": ["a1b2-c3d4", "e5f6-g7h8", "i9j0-k1l2"],
"access_token": null,
"token_type": "bearer"
}/v1/auth/mfa/verifyVerify MFA Challenge
Complete an MFA challenge during login using the mfa_token from /login plus a TOTP code or a recovery code. Returns the access token. When the login was sent with entry_company_slug, the session keeps it: nothing extra is sent here. The same call completes the code step after a Google or Microsoft sign-in when a company requires two-factor on every sign-in.
No authentication required (uses the MFA challenge token).
Request Body
| Name | Type | Description |
|---|---|---|
mfa_token* | string | Challenge token from /login |
code | string | null | 6-digit TOTP code |
recovery_code | string | null | A recovery code (alternative to a TOTP code) |
Response Fields
| Name | Type | Description |
|---|---|---|
access_token* | string | Bearer token |
token_type | string | Always "bearer" |
company_id | string (UUID) | null | Active company bound to the token, if any |
curl -X POST https://platform.ergondata.ai/v1/auth/mfa/verify \
-H "Content-Type: application/json" \
-d '{"mfa_token": "{mfa_token}", "code": "123456"}'Response
200 OK{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "bearer",
"company_id": null
}/v1/auth/mfa/disableDisable MFA
Disable MFA for the current user. Requires the password plus either a TOTP code or a recovery code.
Bearer token required.
Request Body
| Name | Type | Description |
|---|---|---|
password* | string | Current password |
code | string | null | 6-digit TOTP code |
recovery_code | string | null | A recovery code |
curl -X POST https://platform.ergondata.ai/v1/auth/mfa/disable \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"password": "s3cret-passphrase", "code": "123456"}'Response
200 OK{}/v1/auth/mfa/recovery-codes/regenerateRegenerate Recovery Codes
Invalidate existing recovery codes and issue a fresh set. Requires the password plus a TOTP or recovery code.
Bearer token required.
Request Body
| Name | Type | Description |
|---|---|---|
password* | string | Current password |
code | string | null | 6-digit TOTP code |
recovery_code | string | null | A recovery code |
Response Fields
| Name | Type | Description |
|---|---|---|
recovery_codes* | array<string> | New one-time recovery codes (shown once) |
curl -X POST https://platform.ergondata.ai/v1/auth/mfa/recovery-codes/regenerate \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"password": "s3cret-passphrase", "code": "123456"}'Response
200 OK{
"recovery_codes": ["m3n4-o5p6", "q7r8-s9t0", "u1v2-w3x4"]
}Companies
Create and manage companies, profiles, avatars, and the per-company MFA policy.
/v1/auth/companiesCreate Company
Create a new company. The caller becomes its first member/owner. The session that creates it opens it: a session that signed in only at company start URLs lists the new company from its next token (Refresh Token).
Bearer token required.
Request Body
| Name | Type | Description |
|---|---|---|
name* | string | Company display name |
slug* | string | URL-safe slug (2–255 chars, ^[a-z0-9][a-z0-9-]*$) |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Company ID |
name* | string | Company name |
slug* | string | Company slug |
description | string | null | Description |
avatar_url | string | null | Avatar URL |
created_at* | string (date-time) | Creation timestamp |
curl -X POST https://platform.ergondata.ai/v1/auth/companies \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"name": "Acme Corp", "slug": "acme-corp"}'Response
201 Created{
"id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"name": "Acme Corp",
"slug": "acme-corp",
"description": null,
"avatar_url": null,
"created_at": "2026-01-05T14:20:00Z"
}/v1/auth/companiesList Companies
List companies the authenticated principal belongs to. A session that signed in at the platform login lists every company. A session that signed in only at company start URLs lists those companies, plus any company created or joined from it.
Bearer token required.
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Company ID |
name* | string | Company name |
slug* | string | Company slug |
created_at* | string (date-time) | Creation timestamp |
curl https://platform.ergondata.ai/v1/auth/companies \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"name": "Acme Corp",
"slug": "acme-corp",
"description": null,
"avatar_url": null,
"created_at": "2026-01-05T14:20:00Z"
}
]/v1/auth/companies/{company_id}Get Company
Retrieve company details including member count, enabled services, MFA policy, and the organization's access portal and sign-in requirement.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Company ID |
name* | string | Company name |
slug* | string | Company slug |
member_count* | integer | Number of members |
enabled_services* | array<string> | Service slugs enabled for the company |
require_mfa | boolean | Whether MFA is mandatory |
require_mfa_for | "password" | "every_sign_in" | Which sign-ins two-factor covers when require_mfa is on: password sign-ins only, or every sign-in including Google and Microsoft. Change it with Update MFA Policy. |
sign_in_methods | object | The methods members may sign in with and the SSO domain list, as Update Sign-in Methods returns them. |
access_portal | "platform_default" | "app:{app_id}" | null | The organization's access portal, which members inherit unless they have their own; null is Default. Change it with Update Company Access Portal. |
require_portal_sign_in* | boolean | Whether members who inherit it must sign in at the start URL. Change it with Update Company Access Portal. |
created_at* | string (date-time) | Creation timestamp |
curl https://platform.ergondata.ai/v1/auth/companies/{company_id} \
-H "Authorization: Bearer {token}"Response
200 OK{
"id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"name": "Acme Corp",
"slug": "acme-corp",
"description": null,
"avatar_url": null,
"member_count": 12,
"enabled_services": ["agents", "workflows", "buckets"],
"require_mfa": false,
"require_mfa_for": "password",
"sign_in_methods": {
"methods": ["password", "google", "microsoft"],
"google_workspace_domains": [],
"microsoft_tenant_ids": []
},
"access_portal": null,
"require_portal_sign_in": false,
"created_at": "2026-01-05T14:20:00Z"
}/v1/auth/companies/{company_id}Delete Company
Soft-delete a company. Irreversible from the public API.
Bearer token with iam:company:delete; the caller must also be an owner of the company.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id} \
-H "Authorization: Bearer {token}"Response
204 No Content/v1/auth/companies/{company_id}/profileUpdate Company Profile
Update a company's name and/or description.
Bearer token with iam:company:settings.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Request Body
| Name | Type | Description |
|---|---|---|
name | string | null | New name (1–255 chars) |
description | string | null | New description (max 5000) |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Company ID |
name* | string | Updated name |
description | string | null | Updated description |
curl -X PATCH https://platform.ergondata.ai/v1/auth/companies/{company_id}/profile \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"name": "Acme Corporation", "description": "We make everything."}'Response
200 OK{
"id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"name": "Acme Corporation",
"slug": "acme-corp",
"description": "We make everything.",
"member_count": 12,
"enabled_services": ["agents", "workflows"],
"require_mfa": false,
"created_at": "2026-01-05T14:20:00Z"
}/v1/auth/companies/{company_id}/mfa-policyUpdate MFA Policy
Set whether two-factor is mandatory for the company's members and which sign-ins it covers. require_mfa_for is password (the default: password sign-ins enter the code; Google and Microsoft sign-ins do not) or every_sign_in (Google and Microsoft sign-ins also enter the platform code). Members without a confirmed factor are asked to set one up on their next sign-in that needs the code. At the company's start URL only this company's choice counts. At the platform login, a member of several companies is asked for the code when any company it opens for them requires it; a company that requires its own start URL does not count there. Turning it on does not end any session. With every_sign_in, a session that signed in without the code is asked to sign in again at the company's start URL before it opens the company. Only the fields sent change. Returns 409 with reason sign_in_rules_lock_out_caller when the change would refuse your own current sign-in (turn it on after signing in with your code); API keys and agents can turn the requirement on or off for password sign-ins, but never turn on every_sign_in. every_sign_in needs require_mfa on, and turning require_mfa off also returns require_mfa_for to password. Returns 422 when the body is empty, a field is sent as null, or every_sign_in is sent with require_mfa off (every_sign_in_requires_mfa). Emits iam.company.mfa_policy_changed with the current and previous values. Agent ToolDef slug: iam.company.mfa_policy.update.
Bearer token with iam:company:settings.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Request Body
| Name | Type | Description |
|---|---|---|
require_mfa | boolean | Whether MFA is mandatory |
require_mfa_for | "password" | "every_sign_in" | Which sign-ins two-factor covers |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Company ID |
require_mfa | boolean | Updated MFA policy |
require_mfa_for | "password" | "every_sign_in" | Which sign-ins two-factor covers |
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"}'Response
200 OK{
"id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"name": "Acme Corp",
"slug": "acme-corp",
"member_count": 12,
"enabled_services": ["agents", "workflows"],
"require_mfa": true,
"require_mfa_for": "every_sign_in",
"created_at": "2026-01-05T14:20:00Z"
}/v1/auth/companies/{company_id}/sign-in-methodsUpdate Sign-in Methods
Choose how the company's members may sign in: password, Google, Microsoft, or any combination (a list without password is SSO only). Optionally restrict Google and Microsoft sign-ins to the Google Workspace domains and Microsoft Entra tenants you list. The domain and tenant are what the provider asserts for the account (the Workspace the Google account belongs to, the tenant that issued the Microsoft sign-in), never the email address. When either list has entries, a provider without entries accepts nobody. Every company starts with all three methods and no lists. The company's start URL shows only the allowed methods and refuses the others; a session signed in some other way is asked to sign in again at the start URL before it opens the company. Owners with a password and a two-factor factor can always sign in at the start URL with password and code, even when password is left out, and that sign-in is recorded in Access history. Only the fields sent change; methods are returned in a fixed order and lists are lower-cased and de-duplicated (at most 50 entries each). Returns 400 no_changes for an empty body, 422 for an empty methods list, a field sent as null, or an entry that is not a domain or tenant ID, and 409 with reason sign_in_rules_lock_out_caller when the change would refuse your own current sign-in (sign in with a method the new rules accept, then save again). API keys and agents can only loosen these rules: add methods, add entries to a list that already has some, or clear both lists. Emits iam.company.sign_in_methods_changed with the current and previous values. Agent ToolDef slug: iam.company.sign_in_methods.update.
Bearer token with iam:company:settings.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Request Body
| Name | Type | Description |
|---|---|---|
methods | array<"password" | "google" | "microsoft"> | Allowed sign-in methods (at least one) |
google_workspace_domains | array<string> | Google Workspace domains Google sign-ins must come from. Empty accepts any Google account only while microsoft_tenant_ids is empty too; once either list has entries, an empty list accepts nobody |
microsoft_tenant_ids | array<string (UUID)> | Microsoft Entra tenant IDs Microsoft sign-ins must come from. Empty accepts any Microsoft account only while google_workspace_domains is empty too; once either list has entries, an empty list accepts nobody |
Response Fields
| Name | Type | Description |
|---|---|---|
methods* | array<"password" | "google" | "microsoft"> | Allowed sign-in methods |
google_workspace_domains* | array<string> | Allowed Google Workspace domains |
microsoft_tenant_ids* | array<string> | Allowed Microsoft Entra tenant IDs |
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"]}'Response
200 OK{
"methods": ["google"],
"google_workspace_domains": ["acme.com"],
"microsoft_tenant_ids": []
}/v1/auth/companies/{company_id}/avatarUpload Company Icon or Logo
The company image endpoint: upload or replace the company's icon or one of its two logos, the images in IAM > Profile (multipart/form-data; JPEG, PNG, WebP, or GIF up to the size limit, 5 MB by default). kind=icon (the default) sets the Icon, the square image shown next to the company in the company switcher and pickers, on the organizations page, as the browser tab icon on the company's start URL, and, with the company name, on the start URL's sign-in page when no logo is set; without one, those places show the company's initials. It returns avatar_url and emits iam.company.avatar_updated. kind=logo sets a logo: variant=light (the default) is Logo for light mode and variant=dark is Logo for dark mode, named by the background the logo sits on. The platform shows the logo in the console sidebar header, the apps start page header, and the sign-in page at the company's start URL: the dark-mode logo in the dark theme, the light-mode one in the light theme, and the only one uploaded in both. Without a logo the sidebar and start page show the platform logo, and the sign-in page shows the icon with the company name. It returns logo_url and logo_dark_url and emits iam.company.logo_updated with the variant. Replacing an image deletes the previous one. Returns 400 variant_requires_logo when variant is sent without kind=logo, 400 for an unsupported image type or an image over the size limit, and 422 for an unknown kind or variant. Agent ToolDef slug: iam.company.avatar.upload.
Bearer token with iam:company:settings.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
kind | "icon" | "logo" | Which image to set: icon for the Icon, logo for a logoDefault: icon |
variant | "light" | "dark" | Only with kind=logo (defaults to light there): light for Logo for light mode, dark for Logo for dark mode |
Request Body
| Name | Type | Description |
|---|---|---|
file* | binary (multipart/form-data) | Image file to upload; for a logo, a wide image with a transparent background works best |
Response Fields
| Name | Type | Description |
|---|---|---|
avatar_url | string | kind=icon: the Icon as a temporary signed URL |
logo_url | string | null | kind=logo: Logo for light mode as a temporary signed URL, or null |
logo_dark_url | string | null | kind=logo: Logo for dark mode as a temporary signed URL, or null |
# Icon
curl -X PUT https://platform.ergondata.ai/v1/auth/companies/{company_id}/avatar \
-H "Authorization: Bearer {token}" \
-F "file=@icon.png"
# Logo for dark mode
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"Response
200 OK{
"avatar_url": "https://ergon-files.s3.us-east-1.amazonaws.com/avatars/companies/c0ffee00-cafe-babe-dead-beefcafebabe/7d3a.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&X-Amz-Signature=..."
}/v1/auth/companies/{company_id}/avatarDelete Company Icon or Logo
Remove the company's icon (kind=icon, the default) or one of its logos (kind=logo with variant=light, the default, or variant=dark), using the same company image endpoint as the upload. Removing the icon returns {"detail": "Avatar removed"}, or 404 No avatar set when there is none, and emits iam.company.avatar_removed. Removing a logo returns the remaining logo_url and logo_dark_url, or 404 No logo set when that variant has none, and emits iam.company.logo_removed with the variant; the places that showed it fall back at once, to the other logo when it exists, else to the platform logo in the sidebar and start page header and to the icon with the company name on the sign-in page. Returns 400 variant_requires_logo when variant is sent without kind=logo and 422 for an unknown kind or variant. Agent ToolDef slug: iam.company.avatar.delete.
Bearer token with iam:company:settings.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
kind | "icon" | "logo" | Which image to remove: icon for the Icon, logo for a logoDefault: icon |
variant | "light" | "dark" | Only with kind=logo (defaults to light there): which logo to remove |
Response Fields
| Name | Type | Description |
|---|---|---|
detail | string | kind=icon: "Avatar removed" |
logo_url | string | null | kind=logo: Logo for light mode after the removal, or null |
logo_dark_url | string | null | kind=logo: Logo for dark mode after the removal, or null |
# Icon
curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/avatar \
-H "Authorization: Bearer {token}"
# Logo for dark mode
curl -X DELETE "https://platform.ergondata.ai/v1/auth/companies/{company_id}/avatar?kind=logo&variant=dark" \
-H "Authorization: Bearer {token}"Response
200 OK{
"detail": "Avatar removed"
}Members
Add and remove company members, set each member's console access, access portal, and sign-in requirement, and manage each member's direct role assignments, permission grants, and service access.
/v1/auth/companies/{company_id}/membersList Members
List a company's members (paginated).
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
page | integer | Page number (min 1)Default: 1 |
limit | integer | Items per page (1–100)Default: 50 |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | array | Member records |
total* | integer | Total members |
page* | integer | Current page |
limit* | integer | Page size |
curl "https://platform.ergondata.ai/v1/auth/companies/{company_id}/members?page=1&limit=50" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "5d2e9a41-7b3c-4f10-9e8d-2c6a1b0f4e77",
"user_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"principal_id": "8f3c1d2e-4a5b-4c6d-9e7f-0a1b2c3d4e5f",
"email": "jane@example.com",
"name": "Jane Doe",
"avatar_url": null,
"roles": ["owner"],
"joined_at": "2026-01-05T14:25:00Z",
"invitation_id": null,
"console_access": true,
"access_portal": null,
"require_portal_sign_in": null,
"effective_access_portal": null,
"effective_require_portal_sign_in": false
}
],
"total": 1,
"page": 1,
"limit": 50
}/v1/auth/companies/{company_id}/membersAdd Member / Invite
Invite a user by email. An invitation is sent whether or not the user already has an account, and membership starts when it is accepted. Optionally assign roles and service access on join. Returns 403 (Sign-up is not open to this address) when the invitee has no account and the environment does not allow creating one; nothing is created or sent.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Request Body
| Name | Type | Description |
|---|---|---|
email* | string (email) | Email of the user to add/invite |
role | string | null | Single role name (max 50 chars) |
roles | array<string> | null | Role names to assign |
service_slugs | array<string> | null | Service slugs to grant on join |
team_ids | array<UUID> | null | Teams to add the invitee to on accept. The caller must be able to manage each team (iam:company:teams:manage); membership is materialized when the invitation is accepted. |
locale_hint | string | null | Optional en-US or pt-BR hint for the invitation email. The selected platform locale wins; an existing user's stored locale is used only when this hint is omitted. Otherwise it falls back to pt-BR. |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/members \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"email": "newhire@example.com",
"roles": ["member"],
"service_slugs": ["workflows"]
}'Response
201 Created{
"invitation_id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
"email": "newhire@example.com",
"status": "pending"
}/v1/auth/companies/{company_id}/members/{user_id}Remove Member
Remove a user from the company. Returns 400 when the user is the company's last system owner, and 409 last_console_owner when they are the only system owner with console access. A custom role named owner does not count.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
user_id* | string (UUID) | User to remove |
curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{user_id} \
-H "Authorization: Bearer {token}"Response
204 No Content/v1/auth/companies/{company_id}/members/{user_id}/accessUpdate Member Access
Change a member's console access, access portal, and sign-in requirement for this company. Every body field is optional: omitted fields keep their value, and an empty body returns 400 no_changes. Console access is on by default. With it off, the member can open and use the apps shared with them and nothing else: they land on the company's apps start page (/apps/{company_slug}), console pages redirect there, and other requests for this company's data return 403 console_access_denied, or are answered as if they had no access (for example, an empty list), including an app's source, versions and builds. Tool calls made by apps they may use keep working under their normal permissions, and a few personal settings stay available. API keys and agents the member created are separate principals and keep working; delete those keys and deactivate those agents to cut that access too. The member stays in the member list and can still receive roles, teams, service access, and grants. access_portal decides where the member lands after sign-in: the apps start page, one of the organization's portal Apps (app:{app_id}, which must be marked as portal, published with an auth module, and not archived: otherwise 400 access_portal_app_unavailable), or Default. require_portal_sign_in makes them sign in for this company at its start URL or one of its app addresses (selecting the company from a session signed in elsewhere then returns 403 portal_sign_in_required with portal_url); it is a routing and audit rule, not an extra authentication factor. Both inherit the organization's values (Update Company Access Portal) while null, and a value set here overrides them for this member. Require applies only while the resulting access portal is not Default. The request is checked against the member's resulting settings: require_portal_sign_in true when the resulting access portal (their own, or the organization's when they inherit) is Default returns 400 access_portal_required. The response carries the member's own values (null inherits) and effective_access_portal and effective_require_portal_sign_in, the values that apply. Returns 400 cannot_change_own_console_access when the body carries console_access and user_id is the caller (you may set your own access_portal and require_portal_sign_in), 403 when the target holds the system owner role and the caller does not (for any field), and 409 last_console_owner when switching console access off would leave the company with no system owner who has console access. A custom role named owner does not count. Sending current values is a no-op that returns 200. A console access change emits iam.member.console_access_changed; an access_portal or require_portal_sign_in change emits iam.member.access_portal_changed with both values. Agent ToolDef slug: iam.company.members.access.update.
Bearer token with iam:company:members:manage on the target member.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
user_id* | string (UUID) | Member user ID (your own only when console_access is omitted) |
Request Body
| Name | Type | Description |
|---|---|---|
console_access | boolean | true to allow the console and direct API use; false for app-only access |
access_portal | "default" | "platform_default" | "app:{app_id}" | null | "platform_default" lands the member on the company's apps start page after sign-in, even with console access; "app:{app_id}" lands them on that portal App of the company (400 access_portal_app_unavailable unless it is marked as portal, published with an auth module, and not archived); "default" lands them on the console with console access, otherwise the apps start page; null inherits the organization's access portal |
require_portal_sign_in | boolean | null | true requires the member to sign in for this company at its start URL (/apps/{company_slug}) or one of its app addresses, and needs a resulting access portal other than Default; false lets them sign in anywhere; null inherits the organization's setting |
Response Fields
| Name | Type | Description |
|---|---|---|
user_id* | string (UUID) | Member user ID |
company_id* | string (UUID) | Company ID |
console_access* | boolean | The member's console access after the update |
access_portal | "default" | "platform_default" | "app:{app_id}" | null | The member's own access portal after the update; null inherits |
require_portal_sign_in | boolean | null | The member's own sign-in requirement after the update; null inherits |
effective_access_portal | "platform_default" | "app:{app_id}" | null | The access portal that applies to the member; null is Default |
effective_require_portal_sign_in* | boolean | Whether the member must sign in at the start URL |
# App-only access
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}'
# Land on the apps start page and require sign-in at the start URL
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": "platform_default", "require_portal_sign_in": true}'Response
200 OK{
"user_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"console_access": true,
"access_portal": "platform_default",
"require_portal_sign_in": true,
"effective_access_portal": "platform_default",
"effective_require_portal_sign_in": true
}/v1/auth/companies/{company_id}/access-portalUpdate Company Access Portal
Set the organization's access portal and sign-in requirement, which members inherit unless they have their own (Update Member Access). access_portal "platform_default" sends members to the company's apps start page (/apps/{company_slug}) after sign-in; "app:{app_id}" sends them to that portal App's address (/apps/{company_slug}/{app_id}), and needs an App marked as portal, published with an auth module, and not archived (List Portal Apps): otherwise 400 access_portal_app_unavailable, and 503 when that cannot be checked. When the App later stops being a portal, members land on the apps start page instead. null is Default: the console with console access, otherwise the apps start page. require_portal_sign_in true means members who inherit it must sign in to this company at its start URL or one of its app addresses; selecting the company from a session signed in elsewhere returns 403 portal_sign_in_required with portal_url, for this company only. require_portal_sign_in true needs an access_portal other than null: otherwise 400 access_portal_required, including when clearing access_portal while the requirement stays on. Omitted fields stay unchanged; an empty body returns 400 no_changes; sending current values is a no-op that returns 200. Every organization starts at Default with the requirement off. A change emits iam.company.access_portal_changed with the new and previous values. Agent ToolDef slug: iam.company.access_portal.update.
Bearer token with iam:company:settings on the organization.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Request Body
| Name | Type | Description |
|---|---|---|
access_portal | "platform_default" | "app:{app_id}" | null | "platform_default" for the apps start page; "app:{app_id}" for one of the organization's portal Apps (List Portal Apps; 400 access_portal_app_unavailable for any other App); null for Default (the console with console access, otherwise the apps start page) |
require_portal_sign_in | boolean | true requires members who inherit it to sign in at the start URL or one of the organization's app addresses; needs an access_portal other than null in the resulting settings |
Response Fields
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
access_portal | "platform_default" | "app:{app_id}" | null | The organization's access portal after the update |
require_portal_sign_in* | boolean | Whether members who inherit it must sign in at the start URL |
start_url* | string | The organization's start URL: its sign-in page and apps start page |
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}'Response
200 OK{
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"access_portal": "platform_default",
"require_portal_sign_in": true,
"start_url": "https://platform.ergondata.ai/apps/acme"
}/v1/auth/companies/{company_id}/members/{user_id}/rolesList Member Roles
List the roles directly assigned to a company member. Agent ToolDef slug: iam.company.members.roles.list.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
user_id* | string (UUID) | Member user ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Assignment ID |
role_id* | string (UUID) | Role ID |
name* | string | Role name |
is_system* | boolean | Whether it is a built-in role |
granted_at* | string (date-time) | When assigned |
curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{user_id}/roles \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809",
"role_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "member",
"is_system": true,
"granted_at": "2026-01-06T10:00:00Z"
}
]/v1/auth/companies/{company_id}/members/{user_id}/rolesAssign Member Role
Assign a role to a company member. This changes the member and requires member-management authority; role-management authority alone is not sufficient. Assigning the admin or member base role to a system owner replaces their owner role, so it is refused with 409 last_console_owner when they are the only system owner with console access. A custom role named owner does not count. Agent ToolDef slug: iam.company.members.roles.assign.
Bearer token with iam:company:members:manage on the target member.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
user_id* | string (UUID) | Member user ID |
Request Body
| Name | Type | Description |
|---|---|---|
role_id* | string (UUID) | Role to assign |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Assignment ID |
role_id* | string (UUID) | Role ID |
name* | string | Role name |
is_system* | boolean | Whether it is a built-in role |
granted_at* | string (date-time) | When assigned |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{user_id}/roles \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"role_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"}'Response
201 Created{
"id": "1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809",
"role_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "member",
"is_system": true,
"granted_at": "2026-01-06T10:00:00Z"
}/v1/auth/companies/{company_id}/members/{user_id}/roles/{pr_id}Remove Member Role
Remove a role assignment from a company member. This changes the member and requires member-management authority; role-management authority alone is not sufficient. Removing the system owner role from the only system owner with console access is refused with 409 last_console_owner. A custom role named owner does not count. Agent ToolDef slug: iam.company.members.roles.remove.
Bearer token with iam:company:members:manage on the target member.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
user_id* | string (UUID) | Member user ID |
pr_id* | string (UUID) | Role-assignment ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{user_id}/roles/{pr_id} \
-H "Authorization: Bearer {token}"Response
204 No Content/v1/auth/companies/{company_id}/members/{user_id}/permissionsList Member Permissions
List the direct permission grants on a company member (paginated).
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
user_id* | string (UUID) | Member user ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
page | integer | Page number (min 1)Default: 1 |
limit | integer | Items per page (1–100)Default: 50 |
curl "https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{user_id}/permissions?page=1&limit=50" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "2b3c4d5e-6f70-8192-a3b4-c5d6e7f80910",
"permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0",
"name": "iam:company:members:view",
"resource": "*",
"effect": "allow",
"is_system": false,
"granted_at": "2026-01-06T10:05:00Z"
}
],
"total": 1,
"page": 1,
"limit": 50
}/v1/auth/companies/{company_id}/members/{user_id}/permissionsAdd Member Permission
Grant a direct permission to a company member.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
user_id* | string (UUID) | Member user ID |
Request Body
| Name | Type | Description |
|---|---|---|
permission_id* | string (UUID) | Permission to grant |
effect | string | Allow or denyDefault: allow |
resource | string | null | Resource path the grant applies to |
resource_id | string (UUID) | null | Specific resource instance ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Grant ID |
permission_id* | string (UUID) | Permission ID |
name* | string | Permission name |
resource* | string | Resource the grant applies to |
effect* | string | allow or deny |
is_system* | boolean | Whether it is a built-in grant |
granted_at* | string (date-time) | When granted |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{user_id}/permissions \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0", "effect": "allow"}'Response
201 Created{
"id": "2b3c4d5e-6f70-8192-a3b4-c5d6e7f80910",
"permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0",
"name": "iam:company:members:view",
"resource": "*",
"effect": "allow",
"is_system": false,
"granted_at": "2026-01-06T10:05:00Z"
}/v1/auth/companies/{company_id}/members/{user_id}/permissions/{pp_id}Remove Member Permission
Revoke a direct permission grant from a company member.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
user_id* | string (UUID) | Member user ID |
pp_id* | string (UUID) | Permission-grant ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{user_id}/permissions/{pp_id} \
-H "Authorization: Bearer {token}"Response
204 No Content/v1/auth/companies/{company_id}/members/{user_id}/servicesList Member Services
List the services a company member has access to: direct `principal_services` plus the member's own role-derived `role_services`. Service access is explicit per principal and is NOT inherited through team membership.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
user_id* | string (UUID) | Member user ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Service-access grant ID |
service_slug* | string | Service slug |
service_name* | string | Service name |
source | string | null | Where the access came from: `direct` or `role:<name>` |
granted_at* | string (date-time) | When granted |
curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{user_id}/services \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "3c4d5e6f-7081-92a3-b4c5-d6e7f8091011",
"service_slug": "workflows",
"service_name": "Workflows",
"source": "direct",
"granted_at": "2026-01-06T10:10:00Z"
}
]/v1/auth/companies/{company_id}/members/{user_id}/servicesGrant Member Service
Grant a member access to a service by slug.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
user_id* | string (UUID) | Member user ID |
Request Body
| Name | Type | Description |
|---|---|---|
service_slug* | string | Service slug to grant |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Service-access grant ID |
service_slug* | string | Service slug |
service_name* | string | Service name |
granted_at* | string (date-time) | When granted |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{user_id}/services \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"service_slug": "workflows"}'Response
201 Created{
"id": "3c4d5e6f-7081-92a3-b4c5-d6e7f8091011",
"service_slug": "workflows",
"service_name": "Workflows",
"source": "direct",
"granted_at": "2026-01-06T10:10:00Z"
}/v1/auth/companies/{company_id}/members/{user_id}/services/{access_id}Revoke Member Service
Revoke a member's access to a service.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
user_id* | string (UUID) | Member user ID |
access_id* | string (UUID) | Service-access grant ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{user_id}/services/{access_id} \
-H "Authorization: Bearer {token}"Response
204 No ContentRoles & Permissions
Create company roles, attach service access to roles, and manage the permissions granted to each role. These operations require iam:company:roles:manage; assigning a role to a member is a member operation and instead requires iam:company:members:manage on that member.
/v1/auth/companies/{company_id}/rolesList Roles
List a company's roles, including built-in system roles.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Role ID |
name* | string | Role name |
description | string | null | Role description |
is_system* | boolean | Whether it is a built-in role |
company_id | string (UUID) | null | Owning company (null for global roles) |
curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "member",
"description": "Standard member",
"is_system": true,
"company_id": null
}
]/v1/auth/companies/{company_id}/roles/manageableList Manageable Roles
List custom roles the caller can manage. Results are filtered by iam:company:roles:manage on each exact role instance.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Role ID |
name* | string | Role name |
description | string | null | Role description |
is_system* | boolean | Whether it is a built-in role |
company_id* | string (UUID) | Owning company |
curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/manageable \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "workflow-reviewer",
"description": "Reviews a scoped workflow",
"is_system": false,
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe"
}
]/v1/auth/companies/{company_id}/rolesCreate Role
Create a custom role in a company.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Request Body
| Name | Type | Description |
|---|---|---|
name* | string | Role name (1–50 chars) |
description | string | null | Role description |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Role ID |
name* | string | Role name |
description | string | null | Role description |
is_system* | boolean | Always false for custom roles |
company_id | string (UUID) | null | Owning company |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"name": "billing-admin", "description": "Manages billing"}'Response
201 Created{
"id": "5d6e7f80-9102-3343-5566-7788990011aa",
"name": "billing-admin",
"description": "Manages billing",
"is_system": false,
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe"
}/v1/auth/companies/{company_id}/roles/{role_id}Update Role
Update a custom role's name and/or description.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
role_id* | string (UUID) | Role ID |
Request Body
| Name | Type | Description |
|---|---|---|
name | string | null | New name (1–50 chars) |
description | string | null | New description |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Role ID |
name* | string | Role name |
description | string | null | Role description |
is_system* | boolean | Whether it is a built-in role |
company_id | string (UUID) | null | Owning company |
curl -X PATCH https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id} \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"description": "Manages billing and invoices"}'Response
200 OK{
"id": "5d6e7f80-9102-3343-5566-7788990011aa",
"name": "billing-admin",
"description": "Manages billing and invoices",
"is_system": false,
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe"
}/v1/auth/companies/{company_id}/roles/{role_id}Delete Role
Delete a custom role.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
role_id* | string (UUID) | Role ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id} \
-H "Authorization: Bearer {token}"Response
204 No Content/v1/auth/companies/{company_id}/roles/{role_id}/servicesList Role Services
List the services attached to a role.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
role_id* | string (UUID) | Role ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Role-service grant ID |
service_slug* | string | Service slug |
service_name* | string | Service name |
granted_at* | string (date-time) | When attached |
curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id}/services \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "6e7f8091-0233-4455-6677-8899aabbccdd",
"service_slug": "workflows",
"service_name": "Workflows",
"source": "role",
"granted_at": "2026-01-06T11:00:00Z"
}
]/v1/auth/companies/{company_id}/roles/{role_id}/servicesAdd Role Service
Attach a service to a role so members with the role inherit its access.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
role_id* | string (UUID) | Role ID |
Request Body
| Name | Type | Description |
|---|---|---|
service_slug* | string | Service slug to attach |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Role-service grant ID |
service_slug* | string | Service slug |
service_name* | string | Service name |
granted_at* | string (date-time) | When attached |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id}/services \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"service_slug": "workflows"}'Response
201 Created{
"id": "6e7f8091-0233-4455-6677-8899aabbccdd",
"service_slug": "workflows",
"service_name": "Workflows",
"source": "role",
"granted_at": "2026-01-06T11:00:00Z"
}/v1/auth/companies/{company_id}/roles/{role_id}/services/{rs_id}Remove Role Service
Detach a service from a role.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
role_id* | string (UUID) | Role ID |
rs_id* | string (UUID) | Role-service grant ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id}/services/{rs_id} \
-H "Authorization: Bearer {token}"Response
204 No Content/v1/auth/roles/{role_id}/permissionsList Role Permissions
List the permissions granted directly to a role.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
role_id* | string (UUID) | Role ID |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | GrantedPermission[] | Direct permission grants |
total* | integer | Total direct grants |
curl https://platform.ergondata.ai/v1/auth/roles/{role_id}/permissions \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "7f809102-3344-5566-7788-99aabbccddee",
"permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0",
"name": "iam:company:members:view",
"resource": "*",
"effect": "allow",
"is_system": false,
"granted_at": "2026-01-06T11:05:00Z"
}
],
"total": 1
}/v1/auth/roles/{role_id}/permissionsAdd Role Permission
Grant a permission to a role.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
role_id* | string (UUID) | Role ID |
Request Body
| Name | Type | Description |
|---|---|---|
permission_id* | string (UUID) | Permission to grant |
effect | string | allow or denyDefault: allow |
resource | string | null | Resource path the grant applies to |
resource_id | string (UUID) | null | Specific resource instance ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Grant ID |
permission_id* | string (UUID) | Permission ID |
name* | string | Permission name |
resource* | string | Resource the grant applies to |
effect* | string | allow or deny |
is_system* | boolean | Whether it is a built-in grant |
granted_at* | string (date-time) | When granted |
curl -X POST https://platform.ergondata.ai/v1/auth/roles/{role_id}/permissions \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0", "effect": "allow"}'Response
201 Created{
"id": "7f809102-3344-5566-7788-99aabbccddee",
"permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0",
"name": "iam:company:members:view",
"resource": "*",
"effect": "allow",
"is_system": false,
"granted_at": "2026-01-06T11:05:00Z"
}/v1/auth/roles/{role_id}/permissions/{pp_id}Remove Role Permission
Revoke a permission from a role.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
role_id* | string (UUID) | Role ID |
pp_id* | string (UUID) | Permission-grant ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/roles/{role_id}/permissions/{pp_id} \
-H "Authorization: Bearer {token}"Response
204 No ContentAPI Keys
Create, list, update, and delete machine API keys and manage each key's permissions, role assignments, and service access.
/v1/auth/api-keysCreate API Key
Create a machine API key for a company. The client_secret is returned only once at creation time — store it securely.
Bearer token required.
Request Body
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Owning company |
name* | string | Human-readable key name |
service_slugs* | array<string> | Services the key may access |
expires_at | string (date-time) | null | Optional expiry timestamp |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | API key ID |
client_id* | string | Public client identifier (ek_...) |
client_secret* | string | Secret (eks_...), shown once at creation |
curl -X POST https://platform.ergondata.ai/v1/auth/api-keys \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"name": "CI pipeline",
"service_slugs": ["workflows"]
}'Response
201 Created{
"id": "a1a2a3a4-b5b6-c7c8-d9d0-e1e2e3e4e5e6",
"client_id": "ek_live_8f2c1d...",
"client_secret": "eks_live_a9b8c7..."
}/v1/auth/companies/{company_id}/api-keysList API Keys
List a company's API keys (paginated). Secrets are never returned.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
page | integer | Page number (min 1)Default: 1 |
limit | integer | Items per page (1–100)Default: 50 |
curl "https://platform.ergondata.ai/v1/auth/companies/{company_id}/api-keys?page=1&limit=50" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "a1a2a3a4-b5b6-c7c8-d9d0-e1e2e3e4e5e6",
"name": "CI pipeline",
"client_id": "ek_live_8f2c1d...",
"expires_at": null,
"services": ["workflows"],
"created_at": "2026-01-07T09:00:00Z"
}
],
"total": 1,
"page": 1,
"limit": 50
}/v1/auth/api-keys/{key_id}Update API Key
Update an API key's name and/or expiry.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
key_id* | string (UUID) | API key ID |
Request Body
| Name | Type | Description |
|---|---|---|
name | string | null | New name (1–100 chars) |
expires_at | string (date-time) | null | New expiry timestamp |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | API key ID |
name* | string | Key name |
client_id | string | null | Public client identifier |
expires_at | string (date-time) | null | Expiry |
services* | array<string> | Services the key may access |
created_at* | string (date-time) | Creation timestamp |
curl -X PATCH https://platform.ergondata.ai/v1/auth/api-keys/{key_id} \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"name": "CI pipeline (prod)"}'Response
200 OK{
"id": "a1a2a3a4-b5b6-c7c8-d9d0-e1e2e3e4e5e6",
"name": "CI pipeline (prod)",
"client_id": "ek_live_8f2c1d...",
"expires_at": null,
"services": ["workflows"],
"created_at": "2026-01-07T09:00:00Z"
}/v1/auth/api-keys/{key_id}Delete API Key
Permanently revoke an API key.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
key_id* | string (UUID) | API key ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/api-keys/{key_id} \
-H "Authorization: Bearer {token}"Response
204 No Content/v1/auth/api-keys/{key_id}/permissionsList API Key Permissions
List the direct permission grants on an API key (paginated).
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
key_id* | string (UUID) | API key ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
page | integer | Page number (min 1)Default: 1 |
limit | integer | Items per page (1–100)Default: 50 |
curl "https://platform.ergondata.ai/v1/auth/api-keys/{key_id}/permissions?page=1&limit=50" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "b2b3b4b5-c6c7-d8d9-e0e1-f2f3f4f5f6f7",
"permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0",
"name": "workflows:workflows:items:create",
"resource": "*",
"effect": "allow",
"is_system": false,
"granted_at": "2026-01-07T09:10:00Z"
}
],
"total": 1,
"page": 1,
"limit": 50
}/v1/auth/api-keys/{key_id}/permissionsAdd API Key Permission
Grant a direct permission to an API key.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
key_id* | string (UUID) | API key ID |
Request Body
| Name | Type | Description |
|---|---|---|
permission_id* | string (UUID) | Permission to grant |
effect | string | allow or denyDefault: allow |
resource | string | null | Resource path the grant applies to |
resource_id | string (UUID) | null | Specific resource instance ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Grant ID |
permission_id* | string (UUID) | Permission ID |
name* | string | Permission name |
resource* | string | Resource the grant applies to |
effect* | string | allow or deny |
is_system* | boolean | Whether it is a built-in grant |
granted_at* | string (date-time) | When granted |
curl -X POST https://platform.ergondata.ai/v1/auth/api-keys/{key_id}/permissions \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0", "effect": "allow"}'Response
201 Created{
"id": "b2b3b4b5-c6c7-d8d9-e0e1-f2f3f4f5f6f7",
"permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0",
"name": "workflows:workflows:items:create",
"resource": "*",
"effect": "allow",
"is_system": false,
"granted_at": "2026-01-07T09:10:00Z"
}/v1/auth/api-keys/{key_id}/permissions/{pp_id}Remove API Key Permission
Revoke a direct permission grant from an API key.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
key_id* | string (UUID) | API key ID |
pp_id* | string (UUID) | Permission-grant ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/api-keys/{key_id}/permissions/{pp_id} \
-H "Authorization: Bearer {token}"Response
204 No Content/v1/auth/api-keys/{key_id}/rolesList API Key Roles
List the roles assigned to an API key.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
key_id* | string (UUID) | API key ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Assignment ID |
role_id* | string (UUID) | Role ID |
name* | string | Role name |
is_system* | boolean | Whether it is a built-in role |
granted_at* | string (date-time) | When assigned |
curl https://platform.ergondata.ai/v1/auth/api-keys/{key_id}/roles \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "c3c4c5c6-d7d8-e9e0-f1f2-031415161718",
"role_id": "5d6e7f80-9102-3343-5566-7788990011aa",
"name": "billing-admin",
"is_system": false,
"granted_at": "2026-01-07T09:15:00Z"
}
]/v1/auth/api-keys/{key_id}/rolesAssign API Key Role
Assign a role to an API key.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
key_id* | string (UUID) | API key ID |
Request Body
| Name | Type | Description |
|---|---|---|
role_id* | string (UUID) | Role to assign |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Assignment ID |
role_id* | string (UUID) | Role ID |
name* | string | Role name |
is_system* | boolean | Whether it is a built-in role |
granted_at* | string (date-time) | When assigned |
curl -X POST https://platform.ergondata.ai/v1/auth/api-keys/{key_id}/roles \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"role_id": "5d6e7f80-9102-3343-5566-7788990011aa"}'Response
201 Created{
"id": "c3c4c5c6-d7d8-e9e0-f1f2-031415161718",
"role_id": "5d6e7f80-9102-3343-5566-7788990011aa",
"name": "billing-admin",
"is_system": false,
"granted_at": "2026-01-07T09:15:00Z"
}/v1/auth/api-keys/{key_id}/roles/{pr_id}Remove API Key Role
Remove a role assignment from an API key.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
key_id* | string (UUID) | API key ID |
pr_id* | string (UUID) | Role-assignment ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/api-keys/{key_id}/roles/{pr_id} \
-H "Authorization: Bearer {token}"Response
204 No Content/v1/auth/api-keys/{key_id}/servicesList API Key Services
List the services an API key has access to.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
key_id* | string (UUID) | API key ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Service-access grant ID |
service_slug* | string | Service slug |
service_name* | string | Service name |
granted_at* | string (date-time) | When granted |
curl https://platform.ergondata.ai/v1/auth/api-keys/{key_id}/services \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "d4d5d6d7-e8e9-f0f1-0203-1a2b3c4d5e6f",
"service_slug": "workflows",
"service_name": "Workflows",
"source": "direct",
"granted_at": "2026-01-07T09:20:00Z"
}
]/v1/auth/api-keys/{key_id}/servicesGrant API Key Service
Grant an API key access to a service by slug.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
key_id* | string (UUID) | API key ID |
Request Body
| Name | Type | Description |
|---|---|---|
service_slug* | string | Service slug to grant |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Service-access grant ID |
service_slug* | string | Service slug |
service_name* | string | Service name |
granted_at* | string (date-time) | When granted |
curl -X POST https://platform.ergondata.ai/v1/auth/api-keys/{key_id}/services \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"service_slug": "workflows"}'Response
201 Created{
"id": "d4d5d6d7-e8e9-f0f1-0203-1a2b3c4d5e6f",
"service_slug": "workflows",
"service_name": "Workflows",
"source": "direct",
"granted_at": "2026-01-07T09:20:00Z"
}/v1/auth/api-keys/{key_id}/services/{access_id}Revoke API Key Service
Revoke an API key's access to a service.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
key_id* | string (UUID) | API key ID |
access_id* | string (UUID) | Service-access grant ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/api-keys/{key_id}/services/{access_id} \
-H "Authorization: Bearer {token}"Response
204 No ContentAgent Identities
Create and manage agent principals plus their permissions, roles, service access, and the human/API-key principals linked to act as them.
/v1/auth/companies/{company_id}/agentsCreate Agent
Create an agent identity in a company. A service agent holds its own access. A personal agent acts as its owner with the owner's access, and only the owner can use it. The owner receives the creator bundle; a creator who is not the owner receives a manage-only bundle: agents:agents:view, agents:agents:settings:manage, agents:agents:skills:manage, agents:agents:budgets:manage and iam:company:agents:view|manage|delete (never use, and not agents:permissions:manage).
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Request Body
| Name | Type | Description |
|---|---|---|
name* | string | Agent name (1–200 chars) |
description | string | null | Agent description |
agent_type | "service" | "personal" | Agent type, fixed at creation (default service) |
owner_member_id | string (UUID) | null | Personal agents only. Any active member of the company with console access; defaults to the caller's membership. 400 personal_agent_owner_not_eligible for an ineligible member (not active, no console access, removed, or not in this company), 400 personal_agent_owner_required when the caller has no membership and omits it, and 400 when sent for a service agent. |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Agent ID |
company_id* | string (UUID) | Owning company |
name* | string | Agent name |
description* | string | null | Agent description |
is_active* | boolean | Whether the agent is active |
agent_type* | "service" | "personal" | Agent type, fixed at creation |
owner* | object | null | A personal agent's owner (member_id, principal_id, name, email, is_active); null for a service agent |
is_default* | boolean | true when this personal agent is its owner's default for new conversations |
show_sent_by_marker* | boolean | true when other people see "sent by <agent>" on the messages this personal agent sends as its owner; false by default |
roles* | array<string> | Assigned role names |
services* | array<string> | Service slugs the agent can access |
created_at* | string (date-time) | Creation timestamp |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/agents \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"name": "Support Bot", "description": "Handles tier-1 tickets"}'Response
201 Created{
"id": "ae10b020-c030-d040-e050-f060a070b080",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"name": "Support Bot",
"description": "Handles tier-1 tickets",
"is_active": true,
"agent_type": "personal",
"owner": {
"member_id": "b1e2a3d4-0001-4c2d-8e3f-a1b2c3d4e5f6",
"principal_id": "b1e2a3d4-0002-4c2d-8e3f-a1b2c3d4e5f6",
"name": "Maria Silva",
"email": "maria@example.com",
"is_active": true
},
"is_default": true,
"show_sent_by_marker": false,
"avatar_url": null,
"authorized_count": 0,
"roles": [],
"services": [],
"created_at": "2026-01-08T12:00:00Z"
}/v1/auth/companies/{company_id}/agentsList Agents
List a company's agents (paginated).
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
page | integer | Page number (min 1)Default: 1 |
limit | integer | Items per page (1–100)Default: 50 |
grantable | boolean | true leaves personal agents out, for grantee pickersDefault: false |
curl "https://platform.ergondata.ai/v1/auth/companies/{company_id}/agents?page=1&limit=50" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "ae10b020-c030-d040-e050-f060a070b080",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"name": "Support Bot",
"description": "Handles tier-1 tickets",
"is_active": true,
"agent_type": "service",
"owner": null,
"roles": [],
"services": [],
"created_at": "2026-01-08T12:00:00Z"
}
],
"total": 1,
"page": 1,
"limit": 50
}/v1/auth/agents/{agent_id}Get Agent
Retrieve a single agent by ID.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
agent_id* | string (UUID) | Agent ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Agent ID |
company_id* | string (UUID) | Owning company |
name* | string | Agent name |
description* | string | null | Agent description |
is_active* | boolean | Whether the agent is active |
agent_type* | "service" | "personal" | Agent type, fixed at creation |
owner* | object | null | A personal agent's owner (member_id, principal_id, name, email, is_active); null for a service agent |
is_default* | boolean | true when this personal agent is its owner's default for new conversations |
show_sent_by_marker* | boolean | true when other people see "sent by <agent>" on the messages this personal agent sends as its owner; false by default |
roles* | array<string> | Assigned role names |
services* | array<string> | Service slugs |
created_at* | string (date-time) | Creation timestamp |
curl https://platform.ergondata.ai/v1/auth/agents/{agent_id} \
-H "Authorization: Bearer {token}"Response
200 OK{
"id": "ae10b020-c030-d040-e050-f060a070b080",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"name": "Support Bot",
"description": "Handles tier-1 tickets",
"is_active": true,
"agent_type": "personal",
"owner": {
"member_id": "b1e2a3d4-0001-4c2d-8e3f-a1b2c3d4e5f6",
"principal_id": "b1e2a3d4-0002-4c2d-8e3f-a1b2c3d4e5f6",
"name": "Maria Silva",
"email": "maria@example.com",
"is_active": true
},
"is_default": true,
"show_sent_by_marker": false,
"avatar_url": null,
"authorized_count": 2,
"roles": ["member"],
"services": ["workflows"],
"created_at": "2026-01-08T12:00:00Z"
}/v1/auth/agents/{agent_id}Update Agent
Activate or deactivate an agent, or change whether it is its owner's default agent. The name and description are not changed here; they belong to Agent Hub. A member can have one default personal agent per company: new conversations open with it already chosen, and the member can still pick another agent. Only the owner, signed in as a person, can send is_default; anyone else, including the agent itself, gets 403 personal_agent_default_owner_only. Setting a new default clears the previous one. A member's first personal agent becomes their default when it is created. Deactivating or deleting the agent, or removing its owner from the company, clears it. A personal agent writes as its owner in the owner's conversations it does not take part in; the owner always sees which messages their agent sent, and show_sent_by_marker decides whether everyone else sees it too. Only the owner, signed in as a person, can send show_sent_by_marker; anyone else, including the agent itself, gets 403 personal_agent_sent_by_marker_owner_only.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
agent_id* | string (UUID) | Agent ID |
Request Body
| Name | Type | Description |
|---|---|---|
is_active | boolean | null | Activate or deactivate |
is_default | boolean | null | Personal agents only, sent by the owner. true makes this the owner's default agent; false clears it. 409 default_agent_must_be_personal for a service agent, 409 default_agent_must_be_active for an inactive one. |
show_sent_by_marker | boolean | null | Personal agents only, sent by the owner. true shows "sent by <agent>" to everyone on the messages the agent sends as its owner from then on; false (the default) shows it only to the owner. Messages already sent keep what they had. 409 sent_by_marker_must_be_personal for a service agent. |
curl -X PATCH https://platform.ergondata.ai/v1/auth/agents/{agent_id} \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"is_active": false}'Response
200 OK{
"id": "ae10b020-c030-d040-e050-f060a070b080",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"name": "Support Bot",
"description": "Handles tier-1 tickets",
"is_active": false,
"roles": ["member"],
"services": ["workflows"],
"created_at": "2026-01-08T12:00:00Z"
}/v1/auth/agents/{agent_id}Delete Agent
Delete an agent identity.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
agent_id* | string (UUID) | Agent ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/agents/{agent_id} \
-H "Authorization: Bearer {token}"Response
204 No Content/v1/auth/agents/{agent_id}/permissionsList Agent Permissions
List the direct permission grants on an agent (paginated).
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
agent_id* | string (UUID) | Agent ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
page | integer | Page number (min 1)Default: 1 |
limit | integer | Items per page (1–100)Default: 50 |
curl "https://platform.ergondata.ai/v1/auth/agents/{agent_id}/permissions?page=1&limit=50" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "bf20c030-d040-e050-f060-a070b080c090",
"permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0",
"name": "workflows:workflows:items:claim",
"resource": "*",
"effect": "allow",
"is_system": false,
"granted_at": "2026-01-08T12:05:00Z"
}
],
"total": 1,
"page": 1,
"limit": 50
}/v1/auth/agents/{agent_id}/permissionsAdd Agent Permission
Grant a direct permission to an agent.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
agent_id* | string (UUID) | Agent ID |
Request Body
| Name | Type | Description |
|---|---|---|
permission_id* | string (UUID) | Permission to grant |
effect | string | allow or denyDefault: allow |
resource | string | null | Resource path the grant applies to |
resource_id | string (UUID) | null | Specific resource instance ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Grant ID |
permission_id* | string (UUID) | Permission ID |
name* | string | Permission name |
resource* | string | Resource the grant applies to |
effect* | string | allow or deny |
is_system* | boolean | Whether it is a built-in grant |
granted_at* | string (date-time) | When granted |
curl -X POST https://platform.ergondata.ai/v1/auth/agents/{agent_id}/permissions \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0", "effect": "allow"}'Response
201 Created{
"id": "bf20c030-d040-e050-f060-a070b080c090",
"permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0",
"name": "workflows:workflows:items:claim",
"resource": "*",
"effect": "allow",
"is_system": false,
"granted_at": "2026-01-08T12:05:00Z"
}/v1/auth/agents/{agent_id}/permissions/{pp_id}Remove Agent Permission
Revoke a direct permission grant from an agent.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
agent_id* | string (UUID) | Agent ID |
pp_id* | string (UUID) | Permission-grant ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/agents/{agent_id}/permissions/{pp_id} \
-H "Authorization: Bearer {token}"Response
204 No Content/v1/auth/agents/{agent_id}/rolesList Agent Roles
List the roles assigned to an agent.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
agent_id* | string (UUID) | Agent ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Assignment ID |
role_id* | string (UUID) | Role ID |
name* | string | Role name |
is_system* | boolean | Whether it is a built-in role |
granted_at* | string (date-time) | When assigned |
curl https://platform.ergondata.ai/v1/auth/agents/{agent_id}/roles \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "c030d040-e050-f060-a070-b080c090d0a0",
"role_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "member",
"is_system": true,
"granted_at": "2026-01-08T12:10:00Z"
}
]/v1/auth/agents/{agent_id}/rolesAssign Agent Role
Assign a role to an agent.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
agent_id* | string (UUID) | Agent ID |
Request Body
| Name | Type | Description |
|---|---|---|
role_id* | string (UUID) | Role to assign |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Assignment ID |
role_id* | string (UUID) | Role ID |
name* | string | Role name |
is_system* | boolean | Whether it is a built-in role |
granted_at* | string (date-time) | When assigned |
curl -X POST https://platform.ergondata.ai/v1/auth/agents/{agent_id}/roles \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"role_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"}'Response
201 Created{
"id": "c030d040-e050-f060-a070-b080c090d0a0",
"role_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "member",
"is_system": true,
"granted_at": "2026-01-08T12:10:00Z"
}/v1/auth/agents/{agent_id}/roles/{pr_id}Remove Agent Role
Remove a role assignment from an agent.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
agent_id* | string (UUID) | Agent ID |
pr_id* | string (UUID) | Role-assignment ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/agents/{agent_id}/roles/{pr_id} \
-H "Authorization: Bearer {token}"Response
204 No Content/v1/auth/agents/{agent_id}/servicesList Agent Services
List the services an agent has access to.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
agent_id* | string (UUID) | Agent ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Service-access grant ID |
service_slug* | string | Service slug |
service_name* | string | Service name |
granted_at* | string (date-time) | When granted |
curl https://platform.ergondata.ai/v1/auth/agents/{agent_id}/services \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "d040e050-f060-a070-b080-c090d0a0e0b0",
"service_slug": "workflows",
"service_name": "Workflows",
"source": "direct",
"granted_at": "2026-01-08T12:15:00Z"
}
]/v1/auth/agents/{agent_id}/servicesGrant Agent Service
Grant an agent access to a service by slug.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
agent_id* | string (UUID) | Agent ID |
Request Body
| Name | Type | Description |
|---|---|---|
service_slug* | string | Service slug to grant |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Service-access grant ID |
service_slug* | string | Service slug |
service_name* | string | Service name |
granted_at* | string (date-time) | When granted |
curl -X POST https://platform.ergondata.ai/v1/auth/agents/{agent_id}/services \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"service_slug": "workflows"}'Response
201 Created{
"id": "d040e050-f060-a070-b080-c090d0a0e0b0",
"service_slug": "workflows",
"service_name": "Workflows",
"source": "direct",
"granted_at": "2026-01-08T12:15:00Z"
}/v1/auth/agents/{agent_id}/services/{access_id}Revoke Agent Service
Revoke an agent's access to a service.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
agent_id* | string (UUID) | Agent ID |
access_id* | string (UUID) | Service-access grant ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/agents/{agent_id}/services/{access_id} \
-H "Authorization: Bearer {token}"Response
204 No Content/v1/auth/agents/{agent_id}/principalsList Agent Principals
List the principals (members or API keys) linked to act as the agent (paginated).
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
agent_id* | string (UUID) | Agent ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
page | integer | Page number (min 1)Default: 1 |
limit | integer | Items per page (1–100)Default: 50 |
curl "https://platform.ergondata.ai/v1/auth/agents/{agent_id}/principals?page=1&limit=50" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "e050f060-a070-b080-c090-d0a0e0b0f0c0",
"principal_type": "member",
"principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"principal_label": "Jane Doe",
"granted_at": "2026-01-08T12:20:00Z"
}
],
"total": 1,
"page": 1,
"limit": 50
}/v1/auth/agents/{agent_id}/principalsAdd Agent Principal
Authorize a member or API key to act as the agent.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
agent_id* | string (UUID) | Agent ID |
Request Body
| Name | Type | Description |
|---|---|---|
principal_type* | string | Principal type ("member" or "api_key") |
principal_id* | string (UUID) | Principal to authorize |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Link ID |
principal_type* | string | Principal type |
principal_id* | string (UUID) | Principal ID |
principal_label* | string | Human-readable label |
granted_at* | string (date-time) | When linked |
curl -X POST https://platform.ergondata.ai/v1/auth/agents/{agent_id}/principals \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"principal_type": "member",
"principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc"
}'Response
201 Created{
"id": "e050f060-a070-b080-c090-d0a0e0b0f0c0",
"principal_type": "member",
"principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"principal_label": "Jane Doe",
"granted_at": "2026-01-08T12:20:00Z"
}/v1/auth/agents/{agent_id}/principals/{ap_id}Remove Agent Principal
Revoke a principal's authorization to act as the agent.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
agent_id* | string (UUID) | Agent ID |
ap_id* | string (UUID) | Agent-principal link ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/agents/{agent_id}/principals/{ap_id} \
-H "Authorization: Bearer {token}"Response
204 No ContentService Catalog & Entitlements
Browse the platform's service catalog and permission/resource-type metadata, manage which services a company has enabled, feature flags, and per-service principal access.
/v1/auth/servicesList Services
Public catalog of global services available on the platform.
No authentication required.
Query Parameters
| Name | Type | Description |
|---|---|---|
include_hidden | boolean | Include hidden servicesDefault: false |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Service ID |
name* | string | Service name |
slug* | string | Service slug |
hidden* | boolean | Whether the service is hidden |
required | boolean | Whether the service is mandatory |
self_service | boolean | Whether admins can self-enable |
stage | string | Lifecycle stage (e.g. ga) |
curl https://platform.ergondata.ai/v1/auth/servicesResponse
200 OK[
{
"id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
"name": "Workflows",
"slug": "workflows",
"hidden": false,
"required": false,
"self_service": true,
"stage": "ga"
}
]/v1/auth/services/{service_slug}/permissionsList Service Permissions
List the permissions defined by a service.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
service_slug* | string | Service slug |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Permission ID |
name* | string | Permission name |
is_system* | boolean | Whether it is a built-in permission |
description | string | null | Permission description |
curl https://platform.ergondata.ai/v1/auth/services/{service_slug}/permissions \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0",
"name": "workflows:workflows:items:create",
"is_system": true,
"description": "Create workflow items",
"resource_type_slug": "item"
}
]/v1/auth/services/{service_slug}/resource-typesList Service Resource Types
Return the resource-type tree and associated permissions for a service.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
service_slug* | string | Service slug |
curl https://platform.ergondata.ai/v1/auth/services/{service_slug}/resource-types \
-H "Authorization: Bearer {token}"Response
200 OK{
"resource_types": [
{"id": "rt-1", "name": "Workflow", "slug": "workflow", "parent_id": null}
],
"resource_type_edges": [],
"permissions": []
}/v1/auth/companies/{company_id}/available-servicesList Available Services
List services an admin can enable for the company (global non-hidden + tenant services).
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Service ID |
name* | string | Service name |
slug* | string | Service slug |
hidden* | boolean | Whether the service is hidden |
curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/available-services \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
"name": "Workflows",
"slug": "workflows",
"hidden": false,
"required": false,
"self_service": true,
"stage": "ga"
}
]/v1/auth/companies/{company_id}/servicesList Company Services
List the services currently enabled for a company.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Service ID |
name* | string | Service name |
slug* | string | Service slug |
hidden* | boolean | Whether the service is hidden |
curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/services \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
"name": "Workflows",
"slug": "workflows",
"hidden": false,
"required": false,
"self_service": true,
"stage": "ga"
}
]/v1/auth/companies/{company_id}/permissionsList Company Permissions
List the permissions a company can grant — from non-hidden services available to the org plus global wildcards.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Permission ID |
name* | string | Permission name |
is_system* | boolean | Whether it is a built-in permission |
curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/permissions \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0",
"name": "workflows:workflows:items:create",
"is_system": true,
"resource_type_slug": "item"
}
]/v1/auth/companies/{company_id}/iam-grantable-permissionsList IAM Grantable Permissions
Return the narrowed permission catalog for IAM-owned grant surfaces.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Permission ID |
name* | string | Permission name |
is_system* | boolean | Whether it is a built-in permission |
curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/iam-grantable-permissions \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0",
"name": "iam:company:members:view",
"is_system": true
}
]/v1/auth/companies/{company_id}/company-services/{service_id}Enable Company Service
Enable a service for a company.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
service_id* | string (UUID) | Service ID |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/company-services/{service_id} \
-H "Authorization: Bearer {token}"Response
201 Created{
"service_id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
"service_slug": "workflows",
"enabled": true
}/v1/auth/companies/{company_id}/company-services/{service_id}Disable Company Service
Disable a service for a company.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
service_id* | string (UUID) | Service ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/company-services/{service_id} \
-H "Authorization: Bearer {token}"Response
204 No Content/v1/auth/companies/{company_id}/feature-flagsList Feature Flags
List the feature flags resolved for a company.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/feature-flags \
-H "Authorization: Bearer {token}"Response
200 OK{
"beta_dashboard": true,
"new_editor": false
}/v1/auth/companies/{company_id}/feature-flags/{key}Update Feature Flag
Set the value of a single feature flag for a company.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
key* | string | Feature flag key |
Request Body
| Name | Type | Description |
|---|---|---|
value* | boolean | string | number | New flag value |
curl -X PUT https://platform.ergondata.ai/v1/auth/companies/{company_id}/feature-flags/{key} \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"value": true}'Response
200 OK{
"key": "beta_dashboard",
"value": true
}/v1/auth/companies/{company_id}/services/{service_slug}/accessList Service Access
List which principals have access to a given service in a company (paginated).
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
service_slug* | string | Service slug |
Query Parameters
| Name | Type | Description |
|---|---|---|
page | integer | Page number (min 1)Default: 1 |
limit | integer | Items per page (1–100)Default: 50 |
curl "https://platform.ergondata.ai/v1/auth/companies/{company_id}/services/{service_slug}/access?page=1&limit=50" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "f060a070-b080-c090-d0a0-e0b0f0c0a0b0",
"principal_type": "member",
"principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"principal_label": "Jane Doe",
"granted_at": "2026-01-09T08:00:00Z"
}
],
"total": 1,
"page": 1,
"limit": 50
}/v1/auth/companies/{company_id}/services/{service_slug}/accessGrant Service Access
Grant a principal access to a service. The principal is identified via query parameters.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
service_slug* | string | Service slug |
Query Parameters
| Name | Type | Description |
|---|---|---|
principal_type* | string | Principal type ("member", "api_key", or "agent") |
principal_id* | string | Principal to grant |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Service-access grant ID |
principal_type* | string | Principal type |
principal_id* | string (UUID) | Principal ID |
principal_label* | string | Human-readable label |
granted_at* | string (date-time) | When granted |
curl -X POST "https://platform.ergondata.ai/v1/auth/companies/{company_id}/services/{service_slug}/access?principal_type=member&principal_id={principal_id}" \
-H "Authorization: Bearer {token}"Response
201 Created{
"id": "f060a070-b080-c090-d0a0-e0b0f0c0a0b0",
"principal_type": "member",
"principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"principal_label": "Jane Doe",
"granted_at": "2026-01-09T08:00:00Z"
}/v1/auth/companies/{company_id}/services/{service_slug}/access/{access_id}Revoke Service Access
Revoke a principal's access to a service.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
service_slug* | string | Service slug |
access_id* | string (UUID) | Service-access grant ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/services/{service_slug}/access/{access_id} \
-H "Authorization: Bearer {token}"Response
204 No Content/v1/auth/companies/{company_id}/conversation-agentsList Conversation Agents
List agents in a company that are available to participate in conversations (paginated). The caller's default personal agent has is_default true.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
page | integer | Page number (min 1)Default: 1 |
limit | integer | Items per page (1–100)Default: 50 |
curl "https://platform.ergondata.ai/v1/auth/companies/{company_id}/conversation-agents?page=1&limit=50" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"agent_id": "ae10b020-c030-d040-e050-f060a070b080",
"name": "Support Bot",
"principal_id": "p1a2b3c4-d5e6-f7a8-b9c0-d1e2f3a4b5c6"
}
],
"total": 1,
"page": 1,
"limit": 50
}/v1/auth/companies/{company_id}/conversation-principalsList Conversation Principals
List principals in a company that can participate in conversations.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/conversation-principals \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"principal_type": "member",
"label": "Jane Doe"
}
]
}Grants & Service Access
Review and revoke a company's effective permission grants and service-access entitlements.
/v1/auth/companies/{company_id}/grantsList Org Grants
List every permission grant in a company across all principals (paginated). Grants are ordered by granted_at then id, oldest first, so the order is stable across pages.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
page | integer | Page number (min 1)Default: 1 |
limit | integer | Items per page (1–100)Default: 50 |
curl "https://platform.ergondata.ai/v1/auth/companies/{company_id}/grants?page=1&limit=50" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "a0b0c0d0-e0f0-1020-3040-5060708090a0",
"principal_type": "member",
"principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"principal_label": "Jane Doe",
"permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0",
"permission_name": "workflows:workflows:items:create",
"resource": "*",
"effect": "allow",
"granted_at": "2026-01-09T08:30:00Z"
}
],
"total": 1,
"page": 1,
"limit": 50
}/v1/auth/companies/{company_id}/grants/groupedList Org Grants (Grouped)
List a company's grants grouped by principal (members, API keys, agents, then roles), with optional search over principal labels, role names, permissions and scopes. Pass include_grants=false to get each row's counts, services and last grant without its grants, then page a row's grants with List Org Grants for One Principal. Agent ToolDef slug: iam.company.grants.grouped.list.
Bearer token with iam:company:grants:view.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
page | integer | Page number (min 1)Default: 1 |
limit | integer | Items per page (1–100)Default: 25 |
q | string | null | Search query (max 200 chars) |
include_grants | boolean | false returns every row with grants: [] and its counts computed server-sideDefault: true |
curl "https://platform.ergondata.ai/v1/auth/companies/{company_id}/grants/grouped?page=1&limit=25" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"principal_label": "Jane Doe",
"grants": [
{"permission_name": "workflows:workflows:items:create", "resource": "*", "effect": "allow"}
]
}
],
"total": 1,
"page": 1,
"limit": 25
}/v1/auth/companies/{company_id}/grants/grouped/{principal_type}/{principal_id}/grantsList Org Grants for One Principal
Page one grouped row's grants, newest first: its direct grants plus those it holds through its roles (grant_source, source_role_name), each with a resource_breadcrumb. principal_type and principal_id are the row's values from List Org Grants (Grouped). With q, a row that matched on its own name lists every grant; otherwise only the grants that match. Principals and roles of other companies return 404. Agent ToolDef slug: iam.company.grants.grouped.grants.list.
Bearer token with iam:company:grants:view.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
principal_type* | string | member, api_key, agent, or role |
principal_id* | string (UUID) | The row's principal_id (company member, API key, agent or role ID) |
Query Parameters
| Name | Type | Description |
|---|---|---|
page | integer | Page number (min 1)Default: 1 |
limit | integer | Grants per page (1–100)Default: 50 |
q | string | null | Same search as the grouped listing (max 200 chars) |
curl "https://platform.ergondata.ai/v1/auth/companies/{company_id}/grants/grouped/agent/{agent_id}/grants?page=1&limit=50" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "6a1d0c2e-1f3b-4d5e-8a9b-0c1d2e3f4a5b",
"principal_type": "agent",
"permission_name": "buckets:files:view",
"resource": "org/{company_id}/bucket/{bucket_id}/folder/{folder_id}",
"resource_breadcrumb": [{"kind": "organization", "label": null}, {"kind": "resource", "label": "notes"}],
"grant_source": "direct",
"granted_at": "2026-10-19T17:24:00Z"
}
],
"total": 1946,
"page": 1,
"limit": 50
}/v1/auth/companies/{company_id}/grants/batchCreate Org Grants Batch
Create up to 200 expanded IAM-native or organization-border grants with ordered, independent outcomes. Operations expand resources first and permission IDs second. Whole-request retries are idempotent: existing natural grant tuples return already_exists. Agent ToolDef slug: iam.company.grants.batch_create.
Bearer token with iam:company:grants:create.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Request Body
| Name | Type | Description |
|---|---|---|
operations* | array | Grouped operations whose full Cartesian expansion is at most 200 grants |
Response Fields
| Name | Type | Description |
|---|---|---|
results* | array | Outcomes ordered by operation, resource, then permission ID |
summary* | object | created, already_exists, and failed counts |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/grants/batch \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"operations": [{
"client_ref": "onboarding",
"principal_type": "member",
"principal_id": "{member_principal_id}",
"resources": ["org/{company_id}"],
"permission_ids": ["{members_view_permission_id}", "{services_view_permission_id}"],
"effect": "allow"
}]
}'Response
200 OK{
"results": [{
"index": 0,
"client_ref": "onboarding",
"status": "created",
"principal_type": "member",
"principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0",
"resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe",
"effect": "allow",
"grant": {
"id": "a0b0c0d0-e0f0-1020-3040-5060708090a0",
"permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0",
"name": "iam:company:members:view",
"resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe",
"effect": "allow",
"is_system": false,
"granted_at": "2026-07-15T16:30:00Z"
},
"error_status": null,
"error_detail": null,
"side_effect_error_status": null,
"side_effect_error_detail": null
}],
"summary": {"created": 1, "already_exists": 0, "failed": 0}
}/v1/auth/companies/{company_id}/roles/access/grants/batchCreate Role Access Grants Batch
Create grants across concrete role roots. Uses the grouped request, 200-item expansion limit, ordered partial outcomes, and idempotency contract documented by Create Org Grants Batch. Agent ToolDef slug: iam.company.roles.access.grants.batch_create.
Bearer token with iam:company:roles:manage on every concrete role root represented in the batch.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Request Body
| Name | Type | Description |
|---|---|---|
operations* | array | BatchGrantOperation[]; same grouped shape as Create Org Grants Batch |
Response Fields
| Name | Type | Description |
|---|---|---|
results* | array | Ordered BatchGrantResult[] partial outcomes |
summary* | object | created, already_exists, and failed counts |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/access/grants/batch \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"operations":[{"principal_type":"member","principal_id":"{principal_id}","resources":["org/{company_id}/role/{resource_id}"],"permission_ids":["{permission_id}"]}]}'Response
200 OK{
"results": [{"index": 0, "status": "created", "client_ref": null}],
"summary": {"created": 1, "already_exists": 0, "failed": 0}
}/v1/auth/companies/{company_id}/teams/access/grants/batchCreate Team Access Grants Batch
Create grants across concrete team roots. Uses the grouped request, 200-item expansion limit, ordered partial outcomes, and idempotency contract documented by Create Org Grants Batch. Agent ToolDef slug: iam.company.teams.access.grants.batch_create.
Bearer token with iam:company:teams:manage on every concrete team root represented in the batch.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Request Body
| Name | Type | Description |
|---|---|---|
operations* | array | BatchGrantOperation[]; same grouped shape as Create Org Grants Batch |
Response Fields
| Name | Type | Description |
|---|---|---|
results* | array | Ordered BatchGrantResult[] partial outcomes |
summary* | object | created, already_exists, and failed counts |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/teams/access/grants/batch \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"operations":[{"principal_type":"member","principal_id":"{principal_id}","resources":["org/{company_id}/team/{resource_id}"],"permission_ids":["{permission_id}"]}]}'Response
200 OK{
"results": [{"index": 0, "status": "created", "client_ref": null}],
"summary": {"created": 1, "already_exists": 0, "failed": 0}
}/v1/auth/companies/{company_id}/api-keys/access/grants/batchCreate API Key Access Grants Batch
Create grants across concrete api key roots. Uses the grouped request, 200-item expansion limit, ordered partial outcomes, and idempotency contract documented by Create Org Grants Batch. Agent ToolDef slug: iam.company.api_keys.access.grants.batch_create.
Bearer token with iam:company:api-keys:manage on every concrete api key root represented in the batch.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Request Body
| Name | Type | Description |
|---|---|---|
operations* | array | BatchGrantOperation[]; same grouped shape as Create Org Grants Batch |
Response Fields
| Name | Type | Description |
|---|---|---|
results* | array | Ordered BatchGrantResult[] partial outcomes |
summary* | object | created, already_exists, and failed counts |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/api-keys/access/grants/batch \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"operations":[{"principal_type":"member","principal_id":"{principal_id}","resources":["org/{company_id}/api-key/{resource_id}"],"permission_ids":["{permission_id}"]}]}'Response
200 OK{
"results": [{"index": 0, "status": "created", "client_ref": null}],
"summary": {"created": 1, "already_exists": 0, "failed": 0}
}/v1/auth/companies/{company_id}/agents/access/grants/batchCreate Agent Access Grants Batch
Create grants across concrete agent roots. Uses the grouped request, 200-item expansion limit, ordered partial outcomes, and idempotency contract documented by Create Org Grants Batch. Agent ToolDef slug: iam.company.agents.access.grants.batch_create.
Bearer token with iam:company:agents:manage on every concrete agent root represented in the batch.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Request Body
| Name | Type | Description |
|---|---|---|
operations* | array | BatchGrantOperation[]; same grouped shape as Create Org Grants Batch |
Response Fields
| Name | Type | Description |
|---|---|---|
results* | array | Ordered BatchGrantResult[] partial outcomes |
summary* | object | created, already_exists, and failed counts |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/agents/access/grants/batch \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"operations":[{"principal_type":"member","principal_id":"{principal_id}","resources":["org/{company_id}/agent/{resource_id}"],"permission_ids":["{permission_id}"]}]}'Response
200 OK{
"results": [{"index": 0, "status": "created", "client_ref": null}],
"summary": {"created": 1, "already_exists": 0, "failed": 0}
}/v1/auth/companies/{company_id}/members/access/grants/batchCreate Member Access Grants Batch
Create grants across concrete member roots. Uses the grouped request, 200-item expansion limit, ordered partial outcomes, and idempotency contract documented by Create Org Grants Batch. Agent ToolDef slug: iam.company.members.access.grants.batch_create.
Bearer token with iam:company:members:manage on every concrete member root represented in the batch.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Request Body
| Name | Type | Description |
|---|---|---|
operations* | array | BatchGrantOperation[]; same grouped shape as Create Org Grants Batch |
Response Fields
| Name | Type | Description |
|---|---|---|
results* | array | Ordered BatchGrantResult[] partial outcomes |
summary* | object | created, already_exists, and failed counts |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/access/grants/batch \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"operations":[{"principal_type":"member","principal_id":"{principal_id}","resources":["org/{company_id}/member/{resource_id}"],"permission_ids":["{permission_id}"]}]}'Response
200 OK{
"results": [{"index": 0, "status": "created", "client_ref": null}],
"summary": {"created": 1, "already_exists": 0, "failed": 0}
}/v1/auth/companies/{company_id}/grants/{grant_id}Delete Org Grant
Revoke a specific permission grant in a company.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
grant_id* | string (UUID) | Grant ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/grants/{grant_id} \
-H "Authorization: Bearer {token}"Response
204 No Content/v1/auth/companies/{company_id}/service-accessList Org Service Access
List every service-access entitlement in a company across all principals (paginated).
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
page | integer | Page number (min 1)Default: 1 |
limit | integer | Items per page (1–100)Default: 50 |
q | string | null | Search query (max 200 chars) |
curl "https://platform.ergondata.ai/v1/auth/companies/{company_id}/service-access?page=1&limit=50" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "b0c0d0e0-f010-2030-4050-60708090a0b0",
"principal_type": "member",
"principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"service_slug": "workflows",
"granted_at": "2026-01-09T09:00:00Z"
}
],
"total": 1,
"page": 1,
"limit": 50
}/v1/auth/companies/{company_id}/service-access/{access_id}Revoke Org Service Access
Revoke a service-access entitlement in a company by its grant ID.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
access_id* | string (UUID) | Service-access grant ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/service-access/{access_id} \
-H "Authorization: Bearer {token}"Response
204 No ContentInvitations
Recipient-facing invitation flow plus resending pending company invitations.
/v1/auth/invitations/mineList My Invitations
Return all pending, non-expired invitations addressed to the logged-in user's email.
Bearer token required.
Response Fields
| Name | Type | Description |
|---|---|---|
token* | string | Invitation token |
company_name* | string | Inviting company name |
company_slug* | string | Inviting company slug |
inviter_name* | string | null | Who sent the invite |
role | string | null | Proposed single role |
roles | array<string> | Proposed roles |
expires_at* | string (date-time) | Expiry timestamp |
curl https://platform.ergondata.ai/v1/auth/invitations/mine \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"token": "inv-token-abc123",
"company_name": "Acme Corp",
"company_slug": "acme-corp",
"inviter_name": "Jane Doe",
"role": "member",
"roles": ["member"],
"service_slugs": ["workflows"],
"expires_at": "2026-02-01T00:00:00Z"
}
]/v1/auth/invitations/{token}Get Invitation
Look up invitation details by token, including whether the recipient must register first.
No authentication required.
Path Parameters
| Name | Type | Description |
|---|---|---|
token* | string | Invitation token |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Invitation ID |
email* | string | Invited email |
company_name* | string | Inviting company name |
company_slug* | string | Inviting company slug |
needs_registration* | boolean | Whether the recipient must register first |
roles | array<string> | Proposed roles |
locale_hint | string | null | Locale for the invitation email and accept UI |
curl https://platform.ergondata.ai/v1/auth/invitations/{token}Response
200 OK{
"id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
"email": "newhire@example.com",
"company_name": "Acme Corp",
"company_slug": "acme-corp",
"needs_registration": true,
"role": "member",
"roles": ["member"],
"service_slugs": ["workflows"],
"locale_hint": "pt-BR"
}/v1/auth/invitations/{token}/acceptAccept Invitation
Accept an invitation and join the company as the authenticated user. The session that accepts opens the company, unless the membership has require_portal_sign_in, in which case the person signs in at the company's start URL: a session that signed in only at company start URLs lists the new company from its next token (Refresh Token). When the company requires two-factor and the account has none set up, returns 403 with reason mfa_setup_required: set it up (Begin MFA Setup, then Verify MFA Setup) and accept again.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
token* | string | Invitation token |
curl -X POST https://platform.ergondata.ai/v1/auth/invitations/{token}/accept \
-H "Authorization: Bearer {token}"Response
200 OK{
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"status": "accepted"
}/v1/auth/companies/{company_id}/invitations/{invitation_id}/resendResend Invitation
Resend the invitation email with a fresh token, extended expiry, and the sender's currently selected platform language. Returns 403 (Sign-up is not open to this address) when the invitee has no account and the environment does not allow creating one; the old token is kept and nothing is sent.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
invitation_id* | string (UUID) | Invitation ID |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/invitations/{invitation_id}/resend \
-H "Authorization: Bearer {token}"Response
200 OK{}Permission Checks
Evaluate whether the authenticated caller is authorized for an action.
/v1/auth/check-permissionCheck Permission
Evaluate whether the authenticated caller has a given permission on a resource.
Bearer token required.
Request Body
| Name | Type | Description |
|---|---|---|
company_id* | string | Company context to evaluate in |
action* | string | Permission/action to check |
resource* | string | Resource the action targets |
Response Fields
| Name | Type | Description |
|---|---|---|
allowed* | boolean | Whether the action is permitted |
reason | string | null | Explanation when denied. For a member without console access in this company, every action except apps:apps:use is denied with reason console_access_denied; calls made by apps on the member's behalf are evaluated normally. |
curl -X POST https://platform.ergondata.ai/v1/auth/check-permission \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"action": "workflows:workflows:items:create",
"resource": "*"
}'Response
200 OK{
"allowed": true,
"reason": null
}/v1/auth/check-permissionsBatch Check Permissions
Evaluate a single action against multiple candidate resources in one call.
Bearer token required.
Request Body
| Name | Type | Description |
|---|---|---|
company_id* | string | Company context to evaluate in |
action* | string | Permission/action to check |
resources* | array<string> | Resources to evaluate the action against |
Response Fields
| Name | Type | Description |
|---|---|---|
results* | object<string, boolean> | Map of resource → whether allowed |
reason | string | null | Explanation when denied. For a member without console access in this company, every action except apps:apps:use is denied with reason console_access_denied; calls made by apps on the member's behalf are evaluated normally. |
curl -X POST https://platform.ergondata.ai/v1/auth/check-permissions \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"action": "workflows:workflows:items:edit",
"resources": ["item:1", "item:2"]
}'Response
200 OK{
"results": {
"item:1": true,
"item:2": false
},
"reason": null
}/v1/auth/check-capabilitiesCheck Capabilities
Evaluate multiple actions against multiple resources in one request.
Bearer token required.
Request Body
| Name | Type | Description |
|---|---|---|
company_id* | string | Company context to evaluate in |
actions* | array<string> | Permissions/actions to check |
resources* | array<string> | Resources to evaluate each action against |
Response Fields
| Name | Type | Description |
|---|---|---|
results* | object<string, object<string, boolean>> | Map of resource → action → whether allowed |
reason | string | null | Explanation when all checks are denied. For a member without console access in this company, every action except apps:apps:use returns false, and reason is console_access_denied when at least one action was refused for console access and none of the remaining actions is within the caller's service access; calls made by apps on the member's behalf are evaluated normally. |
curl -X POST https://platform.ergondata.ai/v1/auth/check-capabilities \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"actions": ["buckets:folders:view", "buckets:folders:edit"],
"resources": ["org/company/folder/one", "org/company/folder/two"]
}'Response
200 OK{
"results": {
"org/company/folder/one": {
"buckets:folders:view": true,
"buckets:folders:edit": true
},
"org/company/folder/two": {
"buckets:folders:view": true,
"buckets:folders:edit": false
}
},
"reason": null
}/v1/auth/check-scopesCheck Scopes
Classify how far the caller's grants reach below each root resource, per action. `full` means the action is allowed on the root (and everything below it); `partial` lists the grant prefixes below the root that may allow some descendants; `none` means no descendant can be allowed. Lets callers skip whole subtrees before batch-checking individual children.
Bearer token required.
Request Body
| Name | Type | Description |
|---|---|---|
company_id* | string | Company context to evaluate in |
actions* | array<string> | Permissions/actions to classify |
resources* | array<string> | Root resources to classify each action under |
Response Fields
| Name | Type | Description |
|---|---|---|
results* | object<string, object<string, { access: "full" | "partial" | "none", prefixes: array<string> }>> | Map of resource → action → scope. `prefixes` is only populated for `partial`. |
reason | string | null | Explanation when the caller has no access to the service, or console_access_denied when a member without console access asks about actions other than apps:apps:use and none of the remaining actions is within their service access (the refused actions report access none). |
curl -X POST https://platform.ergondata.ai/v1/auth/check-scopes \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"actions": ["workflows:workflows:items:view"],
"resources": ["org/company/folder/f1/workflow/w1", "org/company/folder/f1/workflow/w2"]
}'Response
200 OK{
"results": {
"org/company/folder/f1/workflow/w1": {
"workflows:workflows:items:view": {
"access": "partial",
"prefixes": ["org/company/folder/f1/workflow/w1/phase/p1"]
}
},
"org/company/folder/f1/workflow/w2": {
"workflows:workflows:items:view": { "access": "none", "prefixes": [] }
}
},
"reason": null
}Activity & Audit
Read the audit log of IAM events and the catalog of event types.
/v1/auth/companies/{company_id}/activityList Company Activity
List audit-log events for a company, optionally filtered by event type (paginated).
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
event_type | string | null | Filter by event type |
page | integer | Page number (min 1)Default: 1 |
limit | integer | Items per page (1–100)Default: 50 |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | array | Activity events |
total* | integer | Total events |
page* | integer | Current page |
limit* | integer | Page size |
curl "https://platform.ergondata.ai/v1/auth/companies/{company_id}/activity?page=1&limit=50" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "11112222-3333-4444-5555-666677778888",
"event_type": "member.added",
"actor_label": "Jane Doe",
"actor_type": "member",
"data": {"user_id": "b10f8a92-3c4d-5e6f-7890-123456789abc"},
"created_at": "2026-01-09T10:00:00Z"
}
],
"total": 1,
"page": 1,
"limit": 50
}/v1/auth/activity/{event_id}Get Activity Event
Retrieve a single audit-log event by ID.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
event_id* | string | Event ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Event ID |
event_type* | string | Event type |
actor_label | string | null | Actor display label |
actor_type | string | null | Actor type |
data | object | null | Event payload |
created_at* | string (date-time) | When it occurred |
curl https://platform.ergondata.ai/v1/auth/activity/{event_id} \
-H "Authorization: Bearer {token}"Response
200 OK{
"id": "11112222-3333-4444-5555-666677778888",
"event_type": "member.added",
"actor_label": "Jane Doe",
"actor_type": "member",
"correlation_id": null,
"data": {"user_id": "b10f8a92-3c4d-5e6f-7890-123456789abc"},
"created_at": "2026-01-09T10:00:00Z"
}/v1/auth/event-typesList Event Types
List the catalog of activity event types.
Bearer token required.
curl https://platform.ergondata.ai/v1/auth/event-types \
-H "Authorization: Bearer {token}"Response
200 OK[
{"key": "member.added", "label": "Member added", "category": "members"},
{"key": "role.created", "label": "Role created", "category": "roles"}
]IP Allowlists
Define company IP allowlists (CIDR ranges) and bind them to principals to restrict where they can authenticate from.
/v1/companies/{company_id}/ip-allowlistsList IP Allowlists
List a company's IP allowlists and their CIDR entries.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Allowlist ID |
company_id* | string (UUID) | Owning company |
slug* | string | Allowlist slug |
name* | string | Allowlist name |
entries* | array | CIDR entries |
created_at* | string (date-time) | Creation timestamp |
curl https://platform.ergondata.ai/v1/companies/{company_id}/ip-allowlists \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "1c2d3e4f-5061-7283-94a5-b6c7d8e9f0a1",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"slug": "office",
"name": "Office network",
"entries": [
{"id": "e1e2e3e4-0506-0708-090a-0b0c0d0e0f10", "cidr": "203.0.113.0/24", "label": "HQ"}
],
"created_at": "2026-01-10T08:00:00Z"
}
]/v1/companies/{company_id}/ip-allowlistsCreate IP Allowlist
Create an IP allowlist with one or more CIDR entries.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Request Body
| Name | Type | Description |
|---|---|---|
slug* | string | Allowlist slug (1–100 chars) |
name* | string | Allowlist name (min 1 char) |
entries | array | CIDR entries |
curl -X POST https://platform.ergondata.ai/v1/companies/{company_id}/ip-allowlists \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"slug": "office",
"name": "Office network",
"entries": [{"cidr": "203.0.113.0/24", "label": "HQ"}]
}'Response
201 Created{
"id": "1c2d3e4f-5061-7283-94a5-b6c7d8e9f0a1",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"slug": "office",
"name": "Office network",
"entries": [
{"id": "e1e2e3e4-0506-0708-090a-0b0c0d0e0f10", "cidr": "203.0.113.0/24", "label": "HQ"}
],
"created_at": "2026-01-10T08:00:00Z"
}/v1/ip-allowlists/{allowlist_id}Update IP Allowlist
Update an allowlist's name and/or replace its CIDR entries.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
allowlist_id* | string (UUID) | Allowlist ID |
Request Body
| Name | Type | Description |
|---|---|---|
name | string | null | New name |
entries | array | null | Replacement CIDR entries |
curl -X PATCH https://platform.ergondata.ai/v1/ip-allowlists/{allowlist_id} \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"name": "Office network (updated)"}'Response
200 OK{
"id": "1c2d3e4f-5061-7283-94a5-b6c7d8e9f0a1",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"slug": "office",
"name": "Office network (updated)",
"entries": [
{"id": "e1e2e3e4-0506-0708-090a-0b0c0d0e0f10", "cidr": "203.0.113.0/24", "label": "HQ"}
],
"created_at": "2026-01-10T08:00:00Z"
}/v1/ip-allowlists/{allowlist_id}Delete IP Allowlist
Delete an IP allowlist.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
allowlist_id* | string (UUID) | Allowlist ID |
curl -X DELETE https://platform.ergondata.ai/v1/ip-allowlists/{allowlist_id} \
-H "Authorization: Bearer {token}"Response
204 No Content/v1/companies/{company_id}/ip-allowlist-assignmentsList IP Allowlist Assignments
List which principals are bound to which IP allowlists in a company.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Response Fields
| Name | Type | Description |
|---|---|---|
principal_id* | string (UUID) | Principal ID |
allowlists* | array | Allowlists bound to the principal |
curl https://platform.ergondata.ai/v1/companies/{company_id}/ip-allowlist-assignments \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"allowlists": [
{
"id": "1c2d3e4f-5061-7283-94a5-b6c7d8e9f0a1",
"slug": "office",
"name": "Office network",
"entries": [],
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"created_at": "2026-01-10T08:00:00Z"
}
]
}
]/v1/companies/{company_id}/ip-allowlist-assignments/{principal_id}Set IP Allowlist Assignment
Replace the set of IP allowlists bound to a principal. Pass an empty array to clear.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
principal_id* | string (UUID) | Principal ID |
Request Body
| Name | Type | Description |
|---|---|---|
allowlist_ids* | array<string (UUID)> | Allowlist IDs to bind (empty array clears) |
Response Fields
| Name | Type | Description |
|---|---|---|
principal_id* | string (UUID) | Principal ID |
allowlists* | array | Allowlists now bound |
curl -X PUT https://platform.ergondata.ai/v1/companies/{company_id}/ip-allowlist-assignments/{principal_id} \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"allowlist_ids": ["1c2d3e4f-5061-7283-94a5-b6c7d8e9f0a1"]}'Response
200 OK{
"principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"allowlists": [
{
"id": "1c2d3e4f-5061-7283-94a5-b6c7d8e9f0a1",
"slug": "office",
"name": "Office network",
"entries": [],
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"created_at": "2026-01-10T08:00:00Z"
}
]
}/v1/companies/{company_id}/ip-allowlist-assignments/{principal_id}Delete IP Allowlist Assignment
Remove all IP allowlist bindings from a principal.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
principal_id* | string (UUID) | Principal ID |
curl -X DELETE https://platform.ergondata.ai/v1/companies/{company_id}/ip-allowlist-assignments/{principal_id} \
-H "Authorization: Bearer {token}"Response
204 No ContentWorking Hours
Define weekly working-hours schedules, assign them to principals (routing-only or platform-access enforcement), and read the caller's effective hours.
/v1/companies/{company_id}/working-hoursList Working Hours
List a company's working-hours configurations and their weekly slots.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Config ID |
company_id* | string (UUID) | Owning company |
slug* | string | Config slug |
name* | string | Config name |
timezone* | string | IANA timezone |
slots* | array | Weekly time slots |
created_at* | string (date-time) | Creation timestamp |
curl https://platform.ergondata.ai/v1/companies/{company_id}/working-hours \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "2d3e4f50-6172-8394-a5b6-c7d8e9f0a1b2",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"slug": "business-hours",
"name": "Business Hours",
"timezone": "America/Sao_Paulo",
"slots": [
{"id": "5a5b5c5d-0102-0304-0506-0708090a0b0c", "day_of_week": 0, "start_time": "09:00", "end_time": "17:00"}
],
"created_at": "2026-01-10T09:00:00Z"
}
]/v1/companies/{company_id}/working-hoursCreate Working Hours
Create a working-hours configuration with weekly slots.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Request Body
| Name | Type | Description |
|---|---|---|
slug* | string | Config slug (1–100 chars) |
name* | string | Config name (min 1 char) |
timezone | string | IANA timezone (1–50 chars)Default: UTC |
slots | array | Weekly time slots |
curl -X POST https://platform.ergondata.ai/v1/companies/{company_id}/working-hours \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"slug": "business-hours",
"name": "Business Hours",
"timezone": "America/Sao_Paulo",
"slots": [{"day_of_week": 0, "start_time": "09:00", "end_time": "17:00"}]
}'Response
201 Created{
"id": "2d3e4f50-6172-8394-a5b6-c7d8e9f0a1b2",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"slug": "business-hours",
"name": "Business Hours",
"timezone": "America/Sao_Paulo",
"slots": [
{"id": "5a5b5c5d-0102-0304-0506-0708090a0b0c", "day_of_week": 0, "start_time": "09:00", "end_time": "17:00"}
],
"created_at": "2026-01-10T09:00:00Z"
}/v1/working-hours/{config_id}Update Working Hours
Update a working-hours config's name, timezone, and/or slots.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Config ID |
Request Body
| Name | Type | Description |
|---|---|---|
name | string | null | New name |
timezone | string | null | New IANA timezone |
slots | array | null | Replacement weekly slots |
curl -X PATCH https://platform.ergondata.ai/v1/working-hours/{config_id} \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"name": "Extended Hours"}'Response
200 OK{
"id": "2d3e4f50-6172-8394-a5b6-c7d8e9f0a1b2",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"slug": "business-hours",
"name": "Extended Hours",
"timezone": "America/Sao_Paulo",
"slots": [
{"id": "5a5b5c5d-0102-0304-0506-0708090a0b0c", "day_of_week": 0, "start_time": "09:00", "end_time": "17:00"}
],
"created_at": "2026-01-10T09:00:00Z"
}/v1/working-hours/{config_id}Delete Working Hours
Delete a working-hours configuration.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
config_id* | string (UUID) | Config ID |
curl -X DELETE https://platform.ergondata.ai/v1/working-hours/{config_id} \
-H "Authorization: Bearer {token}"Response
204 No Content/v1/working-hours/grantedList Granted Working Hours
Return the working-hours configs of the company named in the X-Company-Id header, for phase binding. Returns 400 when the header is missing or not a UUID, and 403 when the caller lacks iam:company:policies:view on that company. A member without console access gets 403 console_access_denied.
Bearer token with iam:company:policies:view on the company in X-Company-Id.
curl https://platform.ergondata.ai/v1/working-hours/granted \
-H "Authorization: Bearer {token}" \
-H "X-Company-Id: {company_id}"Response
200 OK[
{
"id": "2d3e4f50-6172-8394-a5b6-c7d8e9f0a1b2",
"slug": "business-hours",
"name": "Business Hours",
"timezone": "America/Sao_Paulo",
"windows": [
{ "day_of_week": 0, "start_time": "09:00:00", "end_time": "18:00:00" }
]
}
]/v1/companies/{company_id}/working-hours-assignmentsList Working Hours Assignments
List which working-hours configs are assigned to which principals in a company.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Response Fields
| Name | Type | Description |
|---|---|---|
principal_id* | string (UUID) | Principal ID |
configs* | array | Assigned configs with enforcement mode |
warnings | array<string> | Assignment warnings |
curl https://platform.ergondata.ai/v1/companies/{company_id}/working-hours-assignments \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"configs": [
{
"id": "2d3e4f50-6172-8394-a5b6-c7d8e9f0a1b2",
"slug": "business-hours",
"name": "Business Hours",
"enforcement_mode": "platform_access"
}
],
"warnings": []
}
]/v1/companies/{company_id}/working-hours-assignments/{principal_id}Set Working Hours Assignment
Replace the working-hours configs assigned to a principal. Use config_ids for routing-only, or assignments for per-config enforcement mode.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
principal_id* | string (UUID) | Principal ID |
Request Body
| Name | Type | Description |
|---|---|---|
config_ids | array<string (UUID)> | null | Config IDs to assign (routing-only enforcement) |
assignments | array | null | Per-config assignments with enforcement mode |
Response Fields
| Name | Type | Description |
|---|---|---|
principal_id* | string (UUID) | Principal ID |
configs* | array | Configs now assigned |
warnings | array<string> | Assignment warnings |
curl -X PUT https://platform.ergondata.ai/v1/companies/{company_id}/working-hours-assignments/{principal_id} \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"assignments": [
{"config_id": "2d3e4f50-6172-8394-a5b6-c7d8e9f0a1b2", "enforcement_mode": "platform_access"}
]
}'Response
200 OK{
"principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"configs": [
{
"id": "2d3e4f50-6172-8394-a5b6-c7d8e9f0a1b2",
"slug": "business-hours",
"name": "Business Hours",
"enforcement_mode": "platform_access"
}
],
"warnings": []
}/v1/companies/{company_id}/working-hours-assignments/{principal_id}Delete Working Hours Assignment
Remove all working-hours assignments from a principal.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
principal_id* | string (UUID) | Principal ID |
curl -X DELETE https://platform.ergondata.ai/v1/companies/{company_id}/working-hours-assignments/{principal_id} \
-H "Authorization: Bearer {token}"Response
204 No ContentStatus Types & Presence
Define company status types (e.g. available, busy) and set the current availability status of principals.
/v1/companies/{company_id}/status-typesList Status Types
List a company's principal status types.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Status type ID |
company_id* | string (UUID) | Owning company |
slug* | string | Status type slug |
name* | string | Status type name |
color* | string | null | Hex color |
icon* | string | null | Icon name |
is_available* | boolean | Counts as available |
is_default* | boolean | Default for new principals |
position* | integer | Sort order |
created_at* | string (date-time) | Creation timestamp |
curl https://platform.ergondata.ai/v1/companies/{company_id}/status-types \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "3e4f5061-7283-94a5-b6c7-d8e9f0a1b2c3",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"slug": "available",
"name": "Available",
"color": "#22c55e",
"icon": "circle",
"is_available": true,
"is_default": true,
"position": 0,
"created_at": "2026-01-11T08:00:00Z"
}
]/v1/companies/{company_id}/status-typesCreate Status Type
Create a principal status type.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Request Body
| Name | Type | Description |
|---|---|---|
slug* | string | Status type slug (1–50 chars) |
name* | string | Status type name (1–200 chars) |
color | string | null | Hex color (max 7 chars) |
icon | string | null | Icon name (max 50 chars) |
is_available | boolean | Whether it counts as availableDefault: false |
is_default | boolean | Whether it is the defaultDefault: false |
position | integer | Sort orderDefault: 0 |
curl -X POST https://platform.ergondata.ai/v1/companies/{company_id}/status-types \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"slug": "busy", "name": "Busy", "color": "#ef4444", "is_available": false}'Response
201 Created{
"id": "4f506172-8394-a5b6-c7d8-e9f0a1b2c3d4",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"slug": "busy",
"name": "Busy",
"color": "#ef4444",
"icon": null,
"is_available": false,
"is_default": false,
"position": 0,
"created_at": "2026-01-11T08:05:00Z"
}/v1/status-types/{status_type_id}Update Status Type
Update a status type's attributes.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
status_type_id* | string (UUID) | Status type ID |
Request Body
| Name | Type | Description |
|---|---|---|
name | string | null | New name (1–200 chars) |
color | string | null | New hex color |
icon | string | null | New icon name |
is_available | boolean | null | Counts as available |
is_default | boolean | null | Is the default |
position | integer | null | Sort order |
curl -X PATCH https://platform.ergondata.ai/v1/status-types/{status_type_id} \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"name": "In a meeting"}'Response
200 OK{
"id": "4f506172-8394-a5b6-c7d8-e9f0a1b2c3d4",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"slug": "busy",
"name": "In a meeting",
"color": "#ef4444",
"icon": null,
"is_available": false,
"is_default": false,
"position": 0,
"created_at": "2026-01-11T08:05:00Z"
}/v1/status-types/{status_type_id}Delete Status Type
Delete a status type.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
status_type_id* | string (UUID) | Status type ID |
curl -X DELETE https://platform.ergondata.ai/v1/status-types/{status_type_id} \
-H "Authorization: Bearer {token}"Response
204 No Content/v1/companies/{company_id}/principal-statusesList Principal Statuses
List the current availability status of every principal in a company.
Bearer token required.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Status record ID |
company_id* | string (UUID) | Company ID |
principal_id* | string (UUID) | Principal ID |
status_type_id* | string (UUID) | Current status type |
status_type_name | string | null | Status type name |
custom_message* | string | null | Custom status message |
is_available | boolean | null | Whether available |
updated_at* | string (date-time) | Last updated |
curl https://platform.ergondata.ai/v1/companies/{company_id}/principal-statuses \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "50617283-94a5-b6c7-d8e9-f0a1b2c3d4e5",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"status_type_id": "3e4f5061-7283-94a5-b6c7-d8e9f0a1b2c3",
"status_type_name": "Available",
"status_type_color": "#22c55e",
"custom_message": null,
"is_available": true,
"updated_at": "2026-01-11T09:00:00Z"
}
]/v1/principal-statuses/meGet My Status
Return the authenticated principal's current status without requiring access to the company-wide status list. Returns null when no explicit status is set.
Bearer token for a selected company, with that company's member principal. A sign-in that has not selected a company gets 401 company_token_required. A company token with no member principal, and a principal token with no company, get 400 Company principal context required.
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Status record ID |
company_id* | string (UUID) | Active company ID |
principal_id* | string (UUID) | Authenticated principal ID |
status_type_id* | string (UUID) | Applied status type |
status_type_slug* | string | null | Applied status slug |
is_available* | boolean | null | Whether this status permits new assignments |
custom_message* | string | null | Optional custom message |
updated_at* | string (date-time) | Last updated |
curl https://platform.ergondata.ai/v1/principal-statuses/me \
-H "Authorization: Bearer {token}"Response
200 OK{
"id": "50617283-94a5-b6c7-d8e9-f0a1b2c3d4e5",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"status_type_id": "3e4f5061-7283-94a5-b6c7-d8e9f0a1b2c3",
"status_type_name": "Available",
"status_type_color": "#22c55e",
"custom_message": null,
"is_available": true,
"updated_at": "2026-08-02T09:00:00Z"
}/v1/principal-statuses/meSet My Status
Set the authenticated principal's current availability status.
Bearer token for a selected company, with that company's member principal. A sign-in that has not selected a company gets 401 company_token_required. A company token with no member principal, and a principal token with no company, get 400 Company principal context required.
Request Body
| Name | Type | Description |
|---|---|---|
status_type_id* | string (UUID) | Status type to apply |
custom_message | string | null | Optional custom status message |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Status record ID |
principal_id* | string (UUID) | Principal ID |
status_type_id* | string (UUID) | Applied status type |
custom_message* | string | null | Custom message |
updated_at* | string (date-time) | Last updated |
curl -X PUT https://platform.ergondata.ai/v1/principal-statuses/me \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"status_type_id": "4f506172-8394-a5b6-c7d8-e9f0a1b2c3d4",
"custom_message": "Back at 2pm"
}'Response
200 OK{
"id": "50617283-94a5-b6c7-d8e9-f0a1b2c3d4e5",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"status_type_id": "4f506172-8394-a5b6-c7d8-e9f0a1b2c3d4",
"status_type_name": "Busy",
"custom_message": "Back at 2pm",
"is_available": false,
"updated_at": "2026-01-11T09:10:00Z"
}/v1/principal-statuses/{principal_id}Set Principal Status
Set another principal's current availability status (requires permission).
Bearer token for a selected company, with iam:company:policies:manage. A sign-in that has not selected a company gets 401 company_token_required. A principal token with no company gets 400 Company context required.
Path Parameters
| Name | Type | Description |
|---|---|---|
principal_id* | string (UUID) | Principal ID |
Request Body
| Name | Type | Description |
|---|---|---|
status_type_id* | string (UUID) | Status type to apply |
custom_message | string | null | Optional custom status message |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Status record ID |
principal_id* | string (UUID) | Principal ID |
status_type_id* | string (UUID) | Applied status type |
custom_message* | string | null | Custom message |
updated_at* | string (date-time) | Last updated |
curl -X PUT https://platform.ergondata.ai/v1/principal-statuses/{principal_id} \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"status_type_id": "4f506172-8394-a5b6-c7d8-e9f0a1b2c3d4"}'Response
200 OK{
"id": "50617283-94a5-b6c7-d8e9-f0a1b2c3d4e5",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"status_type_id": "4f506172-8394-a5b6-c7d8-e9f0a1b2c3d4",
"status_type_name": "Busy",
"custom_message": null,
"is_available": false,
"updated_at": "2026-01-11T09:15:00Z"
}Teams
Teams are first-class principals that group members (and, optionally, nested teams). A team has no credentials of its own, but it holds roles, permission grants, service access, and zone connections directly — and its members inherit all of them through the subject graph. Prefer permission → role → team → members over per-member grants so onboarding is a single assignment. Team management is gated by the iam:company:teams:* permissions; granting and revoking on a team principal additionally use iam:company:grants:*.
/v1/auth/companies/{company_id}/teamsList Teams
List all non-deleted teams in a company, each with its current member count.
Bearer token. Requires iam:company:teams:view.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Team ID |
company_id* | string (UUID) | Owning company |
name* | string | Team name |
description* | string | null | Optional description |
parent_team_id* | string (UUID) | null | Parent team, if nested |
principal_id* | string (UUID) | null | The team's principal |
member_count* | integer | Number of members |
created_at* | string (date-time) | Creation timestamp |
curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/teams \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "7ea11000-0000-4000-8000-000000000001",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"name": "Billing",
"description": "Finance & billing operators",
"parent_team_id": null,
"principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"member_count": 4,
"created_at": "2026-01-10T12:00:00Z"
}
]/v1/auth/companies/{company_id}/teams/manageableList Manageable Teams
Teams the caller can manage grants/membership on. Unlike List Teams (which requires org-wide iam:company:teams:view and returns every team), this returns only teams for which the caller holds iam:company:teams:manage — org-wide or scoped to a specific team instance. Gated on membership alone, so delegated per-team managers who lack org-wide view still get their manageable teams. Powers the member-invite "assign to teams" step.
Bearer token. Company member; results filtered to teams the caller can manage.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Team ID |
company_id* | string (UUID) | Owning company |
name* | string | Team name |
description* | string | null | Optional description |
parent_team_id* | string (UUID) | null | Parent team, if nested |
principal_id* | string (UUID) | null | The team's principal |
member_count* | integer | Number of members |
created_at* | string (date-time) | Creation timestamp |
curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/teams/manageable \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "7ea11000-0000-4000-8000-000000000001",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"name": "Billing",
"description": "Finance & billing operators",
"parent_team_id": null,
"principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"member_count": 4,
"created_at": "2026-01-10T12:00:00Z"
}
]/v1/auth/companies/{company_id}/teamsCreate Team
Create a team. The platform also creates the team's principal and IAM resource row so the team can immediately hold roles, grants, and connections.
Bearer token. Requires iam:company:teams:create.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Request Body
| Name | Type | Description |
|---|---|---|
name* | string | Team name |
description | string | null | Optional description |
parent_team_id | string (UUID) | null | Parent team for nesting |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | New team ID |
principal_id* | string (UUID) | null | The team's principal |
name* | string | Team name |
member_count* | integer | Member count (0 at creation) |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/teams \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"name": "Billing", "description": "Finance & billing operators"}'Response
201 Created{
"id": "7ea11000-0000-4000-8000-000000000001",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"name": "Billing",
"description": "Finance & billing operators",
"parent_team_id": null,
"principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"member_count": 0,
"created_at": "2026-01-10T12:00:00Z"
}/v1/auth/teams/{team_id}Update Team
Update a team's name, description, or parent. Re-parenting is cycle-safe.
Bearer token. Requires iam:company:teams:manage.
Path Parameters
| Name | Type | Description |
|---|---|---|
team_id* | string (UUID) | Team ID |
Request Body
| Name | Type | Description |
|---|---|---|
name | string | null | New name |
description | string | null | New description |
parent_team_id | string (UUID) | null | New parent team (null detaches) |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Team ID |
name* | string | Updated name |
parent_team_id* | string (UUID) | null | Updated parent |
curl -X PATCH https://platform.ergondata.ai/v1/auth/teams/{team_id} \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"name": "Billing & Collections"}'Response
200 OK{
"id": "7ea11000-0000-4000-8000-000000000001",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"name": "Billing & Collections",
"description": "Finance & billing operators",
"parent_team_id": null,
"principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"member_count": 4,
"created_at": "2026-01-10T12:00:00Z"
}/v1/auth/teams/{team_id}Delete Team
Soft-delete a team. Detaches any child teams, removes its memberships, and purges the team principal's grants, service access, connections, and pending connection requests.
Bearer token. Requires iam:company:teams:delete.
Path Parameters
| Name | Type | Description |
|---|---|---|
team_id* | string (UUID) | Team ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/teams/{team_id} \
-H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/v1/auth/teams/{team_id}/membersList Team Members
List the principals that belong to a team.
Bearer token. Requires iam:company:teams:view.
Path Parameters
| Name | Type | Description |
|---|---|---|
team_id* | string (UUID) | Team ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Membership row ID |
member_principal_id* | string (UUID) | The member principal |
principal_type* | string | member | agent | api_key | team |
label* | string | null | Display label |
created_at* | string (date-time) | When added |
curl https://platform.ergondata.ai/v1/auth/teams/{team_id}/members \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "11111111-0000-4000-8000-000000000001",
"member_principal_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
"principal_type": "member",
"label": "ana@acme.com",
"created_at": "2026-01-10T12:05:00Z"
}
]/v1/auth/teams/{team_id}/membersAdd Team Member
Add a principal to the team. The member can be a human member, an agent, an API key, or another team (for nesting).
Bearer token. Requires iam:company:teams:manage.
Path Parameters
| Name | Type | Description |
|---|---|---|
team_id* | string (UUID) | Team ID |
Request Body
| Name | Type | Description |
|---|---|---|
member_principal_id* | string (UUID) | Principal to add |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Membership row ID |
member_principal_id* | string (UUID) | Added principal |
principal_type* | string | Kind of principal added |
curl -X POST https://platform.ergondata.ai/v1/auth/teams/{team_id}/members \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"member_principal_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"}'Response
201 Created{
"id": "11111111-0000-4000-8000-000000000001",
"member_principal_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
"principal_type": "member",
"label": "ana@acme.com",
"created_at": "2026-01-10T12:05:00Z"
}/v1/auth/teams/{team_id}/members/{tm_id}Remove Team Member
Remove a membership row from the team. The principal keeps any access it holds directly.
Bearer token. Requires iam:company:teams:manage.
Path Parameters
| Name | Type | Description |
|---|---|---|
team_id* | string (UUID) | Team ID |
tm_id* | string (UUID) | Membership row ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/teams/{team_id}/members/{tm_id} \
-H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/v1/auth/teams/{team_id}/rolesList Team Roles
List roles assigned to the team principal. Members inherit these roles.
Bearer token. Requires iam:company:teams:view.
Path Parameters
| Name | Type | Description |
|---|---|---|
team_id* | string (UUID) | Team ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Assignment row ID |
role_id* | string (UUID) | Assigned role |
name* | string | Role name |
is_system* | boolean | Whether it's a built-in role |
granted_at* | string (date-time) | When assigned |
curl https://platform.ergondata.ai/v1/auth/teams/{team_id}/roles \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "22222222-0000-4000-8000-000000000001",
"role_id": "33333333-0000-4000-8000-000000000001",
"name": "workflow-operator",
"is_system": false,
"granted_at": "2026-01-10T12:06:00Z"
}
]/v1/auth/teams/{team_id}/rolesAssign Role to Team
Assign a role to the team principal so every member inherits its grants.
Bearer token. Requires iam:company:teams:manage.
Path Parameters
| Name | Type | Description |
|---|---|---|
team_id* | string (UUID) | Team ID |
Request Body
| Name | Type | Description |
|---|---|---|
role_id* | string (UUID) | Role to assign |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Assignment row ID |
role_id* | string (UUID) | Assigned role |
name* | string | Role name |
curl -X POST https://platform.ergondata.ai/v1/auth/teams/{team_id}/roles \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"role_id": "33333333-0000-4000-8000-000000000001"}'Response
201 Created{
"id": "22222222-0000-4000-8000-000000000001",
"role_id": "33333333-0000-4000-8000-000000000001",
"name": "workflow-operator",
"is_system": false,
"granted_at": "2026-01-10T12:06:00Z"
}/v1/auth/teams/{team_id}/roles/{pr_id}Unassign Role from Team
Remove a role assignment from the team principal.
Bearer token. Requires iam:company:teams:manage.
Path Parameters
| Name | Type | Description |
|---|---|---|
team_id* | string (UUID) | Team ID |
pr_id* | string (UUID) | Role-assignment row ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/teams/{team_id}/roles/{pr_id} \
-H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/v1/auth/teams/{team_id}/permissionsList Team Permission Grants
List permission grants attached directly to the team principal.
Bearer token. Requires iam:company:teams:view.
Path Parameters
| Name | Type | Description |
|---|---|---|
team_id* | string (UUID) | Team ID |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | GrantedPermission[] | Direct permission grants |
total* | integer | Total direct grants |
curl https://platform.ergondata.ai/v1/auth/teams/{team_id}/permissions \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "44444444-0000-4000-8000-000000000001",
"permission_id": "55555555-0000-4000-8000-000000000001",
"name": "workflows:workflows:view",
"resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/folder/f1/workflow/w1",
"effect": "allow",
"is_system": false,
"granted_at": "2026-01-10T12:07:00Z"
}
],
"total": 1
}/v1/auth/teams/{team_id}/permissionsGrant Permission to Team
Grant a permission to the team principal. If the resource is a concrete zone the team isn't yet connected to, the covering connection is minted automatically.
Bearer token. Requires iam:company:grants:create.
Path Parameters
| Name | Type | Description |
|---|---|---|
team_id* | string (UUID) | Team ID |
Request Body
| Name | Type | Description |
|---|---|---|
permission_id* | string (UUID) | Permission to grant |
resource | string | null | Resource path; resolved from resource_id if omitted |
resource_id | string (UUID) | null | Resource id (alternative to resource) |
effect | string | allow | denyDefault: allow |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Grant row ID |
permission_id* | string (UUID) | Permission granted |
resource* | string | Resource path |
effect* | string | allow | deny |
curl -X POST https://platform.ergondata.ai/v1/auth/teams/{team_id}/permissions \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"permission_id": "55555555-0000-4000-8000-000000000001",
"resource": "org/{company_id}/folder/{folder_id}/workflow/{workflow_id}",
"effect": "allow"
}'Response
201 Created{
"id": "44444444-0000-4000-8000-000000000001",
"permission_id": "55555555-0000-4000-8000-000000000001",
"name": "workflows:workflows:view",
"resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/folder/f1/workflow/w1",
"effect": "allow",
"is_system": false,
"granted_at": "2026-01-10T12:07:00Z"
}/v1/auth/teams/{team_id}/permissions/{pp_id}Revoke Team Permission Grant
Revoke a permission grant from the team principal.
Bearer token. Requires iam:company:grants:delete.
Path Parameters
| Name | Type | Description |
|---|---|---|
team_id* | string (UUID) | Team ID |
pp_id* | string (UUID) | Grant row ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/teams/{team_id}/permissions/{pp_id} \
-H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/v1/auth/teams/{team_id}/servicesList Team Service Access
List the team's service access, both granted directly and inherited from its roles.
Bearer token. Requires iam:company:teams:view.
Path Parameters
| Name | Type | Description |
|---|---|---|
team_id* | string (UUID) | Team ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Service-access row ID |
service_slug* | string | Service slug (e.g. workflows) |
service_name* | string | Human-readable service name |
source* | string | null | direct or the role it was inherited from |
granted_at* | string (date-time) | When granted |
curl https://platform.ergondata.ai/v1/auth/teams/{team_id}/services \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"id": "66666666-0000-4000-8000-000000000001",
"service_slug": "workflows",
"service_name": "Workflows",
"granted_at": "2026-01-10T12:08:00Z",
"source": "direct"
}
]/v1/auth/teams/{team_id}/servicesGrant Team Service Access
Grant the team direct access to a service so members can reach it through the team.
Bearer token. Requires iam:company:teams:manage.
Path Parameters
| Name | Type | Description |
|---|---|---|
team_id* | string (UUID) | Team ID |
Request Body
| Name | Type | Description |
|---|---|---|
service_slug* | string | Service slug to grant |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Service-access row ID |
service_slug* | string | Granted service |
service_name* | string | Service name |
curl -X POST https://platform.ergondata.ai/v1/auth/teams/{team_id}/services \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"service_slug": "workflows"}'Response
201 Created{
"id": "66666666-0000-4000-8000-000000000001",
"service_slug": "workflows",
"service_name": "Workflows",
"granted_at": "2026-01-10T12:08:00Z",
"source": null
}/v1/auth/teams/{team_id}/services/{access_id}Revoke Team Service Access
Revoke a team's direct service access. Access inherited from a role is unaffected.
Bearer token. Requires iam:company:teams:manage.
Path Parameters
| Name | Type | Description |
|---|---|---|
team_id* | string (UUID) | Team ID |
access_id* | string (UUID) | Service-access row ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/teams/{team_id}/services/{access_id} \
-H "Authorization: Bearer {token}"Response
204 No Content// 204 No ContentConnections
A connection ties a principal (the subject) to a specific zone — a top-level resource such as a workflow, bucket, or agent. Service access lets a principal reach a service; a connection makes it eligible inside one zone, and acts as a runtime kill switch (revoke it and every grant on that zone goes inert). Subjects are identified either by subject_type + subject_id or by a single subject ERN. Valid subject types: member, api_key, agent, team, role, automation, compute_api. These endpoints currently authenticate with a user session token; the caller must be able to manage the subject. Connection comes first and grants live downstream: a standalone grant never creates a connection (IAM rejects a grant to an unconnected subject), so connect via these endpoints / the request-offer handshake (which can carry grants in one step), or let a create action self-connect its creator.
/v1/auth/companies/{company_id}/connectionsList Connections
List a subject's active connections plus its pending outgoing requests.
Bearer (user) token. Caller must manage the subject.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
subject_type | string | member | api_key | agent | team | role | automation | compute_api |
subject_id | string (UUID) | Subject id (with subject_type) |
subject | string | Subject ERN/path (alternative to the pair) |
q | string | Filter by target resource path or service |
limit | integer | Page size (1–200) |
offset | integer | Pagination offsetDefault: 0 |
Response Fields
| Name | Type | Description |
|---|---|---|
connections* | array | Active connection entries |
pending_requests* | array | Outgoing requests awaiting approval |
total* | integer | null | Total active connections ignoring paging |
curl "https://platform.ergondata.ai/v1/auth/companies/{company_id}/connections?subject_type=team&subject_id={team_id}" \
-H "Authorization: Bearer {token}"Response
200 OK{
"connections": [
{
"id": "c1c1c1c1-0000-4000-8000-000000000001",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"role_id": null,
"target_service": "workflows",
"target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/folder/f1/workflow/w1",
"target_ern": "ern:workflows:org/c0ffee00-cafe-babe-dead-beefcafebabe/folder/f1/workflow/w1",
"label": "Invoices",
"created_at": "2026-01-10T12:10:00Z"
}
],
"pending_requests": [],
"total": 1
}/v1/auth/companies/{company_id}/connectionsConnect or Request Connection
Connect the subject to a zone. If the caller manages the target zone the connection is created immediately (status "connected"); otherwise a pending request is opened for a zone admin to approve (status "requested"). Permissions listed are granted on connect, or recorded as requested permissions. A request to a zone with no manager returns 409: nobody could approve it, so someone with the recover permission has to recover the zone.
Bearer token (user or machine principal). Caller must manage the subject. Available to agents as the iam.company.connections.request tool.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Request Body
| Name | Type | Description |
|---|---|---|
subject_type | string | member | api_key | agent | team | role | automation | compute_api |
subject_id | string (UUID) | Subject id (with subject_type) |
subject | string | Subject ERN (alternative to the pair) |
target_service* | string | Service that owns the zone |
target_resource* | string | Zone resource path or ERN |
permissions | (string | {name, resource})[] | null | Permissions to grant on connect (or record as requested). Each entry is a bare permission name (granted at the zone root) or a {name, resource} object scoping the grant to a sub-resource within the target zone. |
message | string | null | Optional note for the approver |
Response Fields
| Name | Type | Description |
|---|---|---|
status* | string | connected | requested |
connection* | object | null | The connection, when connected |
request* | object | null | The pending request, when requested |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/connections \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"subject_type": "team",
"subject_id": "{team_id}",
"target_service": "workflows",
"target_resource": "org/{company_id}/folder/{folder_id}/workflow/{workflow_id}",
"permissions": ["workflows:workflows:view"]
}'Response
200 OK{
"status": "connected",
"connection": {
"id": "c1c1c1c1-0000-4000-8000-000000000001",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"role_id": null,
"target_service": "workflows",
"target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/folder/f1/workflow/w1",
"target_ern": "ern:workflows:org/c0ffee00-cafe-babe-dead-beefcafebabe/folder/f1/workflow/w1",
"label": "Invoices",
"created_at": "2026-01-10T12:10:00Z"
},
"request": null
}/v1/auth/companies/{company_id}/connections/{connection_id}Revoke Connection
Revoke a connection. Every grant on that zone for the subject goes inert immediately; re-connecting reactivates them. Returns 409 if the connection is system-managed (auto-provisioned for a service-owned principal).
Bearer (user) token. Caller must manage the subject.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
connection_id* | string (UUID) | Connection ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/connections/{connection_id} \
-H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/v1/auth/companies/{company_id}/principals/resolveResolve Principals
Permission-aware principal picker for the connection UI. The result tier reflects the caller's view permission for that subject type: "list" returns a searchable list, "handle" returns only an exact-handle match, and "id" echoes a pasted UUID back as an ERN.
Bearer (user) token. Company member; results tiered by the relevant *:view permission.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
type* | string | Subject type: member | api_key | agent | team | role | automation | compute_api |
q | string | Search term or exact handle |
limit | integer | Max results (1–25)Default: 10 |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | array | Resolved principals. Each item: subject_type, subject_id, ern, label, source, plus optional email (members) and avatar_url (presigned; members/agents that have one) for the picker preview. |
tier* | string | list | handle | id |
curl "https://platform.ergondata.ai/v1/auth/companies/{company_id}/principals/resolve?type=team&q=bill" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"subject_type": "team",
"subject_id": "7ea11000-0000-4000-8000-000000000001",
"ern": "ern:iam:org/c0ffee00-cafe-babe-dead-beefcafebabe/team/7ea11000-0000-4000-8000-000000000001",
"label": "Billing",
"email": null,
"avatar_url": null,
"source": "list"
}
],
"tier": "list"
}/v1/auth/companies/{company_id}/connection-policyView Connection Policy
Which principal types may connect to a resource and which permissions each may be granted there. Types in open_principal_types have no connection policy. A declared type (declared by the service that owns it) may only be granted on its declared resource types, and may only connect to one of those types or to a zone type that contains one (a credential edge allows a connection to its namespace), never to the organization.
Bearer token (user or machine principal). Any company member, or an agent, API key or other machine principal of the company. Available to agents as the iam.company.connection_policy.view tool.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
resource* | string | Resource path or ERN inside the company |
service | string | Owning service of the resource, when its resource type slug exists in several services. Without it, an unregistered resource with a shared slug gets allowed: null |
Response Fields
| Name | Type | Description |
|---|---|---|
resource* | string | Canonical resource path |
resource_type* | string | null | Type of the deepest typed segment of the path |
target_service* | string | null | Service that owns the resource |
open_principal_types* | array | Principal types with no connection policy |
declared* | array | One item per declared type: principal_type, allowed (may connect to this resource; null when the resource's service is unknown and the answer depends on it), permissions (grantable on this resource type), edges (every edge the type declares in the resource's service: service, resource_type, permissions). |
curl "https://platform.ergondata.ai/v1/auth/companies/{company_id}/connection-policy?resource=org/{company_id}/namespace/{namespace_id}" \
-H "Authorization: Bearer {token}"Response
200 OK{
"resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/namespace/5ec0de00-0000-4000-8000-000000000001",
"resource_type": "namespace",
"target_service": "vault",
"open_principal_types": ["agent", "api_key", "app", "automation", "member", "role", "team"],
"declared": [
{
"principal_type": "channel_config",
"allowed": true,
"permissions": [],
"edges": [
{ "service": "vault", "resource_type": "credential", "permissions": ["vault:credentials:use", "vault:credentials:view"] }
]
},
{
"principal_type": "compute_api",
"allowed": true,
"permissions": [],
"edges": [
{ "service": "vault", "resource_type": "credential", "permissions": ["vault:credentials:use", "vault:credentials:view"] }
]
},
{ "principal_type": "workflow", "allowed": false, "permissions": [], "edges": [] },
{ "principal_type": "worksheet", "allowed": false, "permissions": [], "edges": [] }
]
}Connection Requests
Connections are a two-party handshake. A request is raised by (or on behalf of) a subject and approved by an admin of the target zone; an offer is raised by a zone admin and accepted by the subject's controller. Neither side approves its own move. Accepting materializes the connection and, optionally, the requested grants. Like the Connections endpoints, these authenticate with a user session token.
/v1/auth/companies/{company_id}/connection-offersOffer a Connection
A zone admin invites a subject into the zone (direction "offer"). The subject's controller accepts or rejects; the inviting admin can withdraw but never self-accepts. When the caller also manages the subject, the connection and grants are applied immediately with no handshake.
Bearer token (user or machine principal). Caller must manage the target zone. Available to agents as the iam.company.connections.offer tool.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Request Body
| Name | Type | Description |
|---|---|---|
subject_type | string | member | api_key | agent | team | role | automation | compute_api |
subject_id | string (UUID) | Subject id (with subject_type) |
subject | string | Subject ERN (alternative to the pair) |
target_service* | string | Service that owns the zone |
target_resource* | string | Zone resource path or ERN |
permissions | (string | {name, resource})[] | null | Permissions to grant on acceptance. Each entry is a bare permission name (granted at the zone root) or a {name, resource} object scoping the grant to a sub-resource within the target zone. The resource must be the target itself or a descendant of it. |
message | string | null | Optional note for the invitee |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Request ID |
direction* | string | offer |
status* | string | pending |
target_resource* | string | Zone resource path |
requested_permissions* | string[] | null | Permissions to grant on accept |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/connection-offers \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"subject_type": "agent",
"subject_id": "{agent_id}",
"target_service": "buckets",
"target_resource": "org/{company_id}/bucket/{bucket_id}",
"permissions": ["buckets:files:view"]
}'Response
201 Created{
"id": "d1d1d1d1-0000-4000-8000-000000000001",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"principal_id": "a9e27000-0000-4000-8000-000000000001",
"role_id": null,
"direction": "offer",
"target_service": "buckets",
"target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/bucket/b1",
"target_ern": "ern:buckets:org/c0ffee00-cafe-babe-dead-beefcafebabe/bucket/b1",
"requested_permissions": ["buckets:files:view"],
"message": null,
"status": "pending",
"created_at": "2026-01-10T12:12:00Z"
}/v1/auth/companies/{company_id}/connection-requestsList Connection Requests
List connection requests and offers for a subject the caller manages.
Bearer (user) token. Caller must manage the subject.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
subject_type | string | member | api_key | agent | team | role | automation | compute_api |
subject_id | string (UUID) | Subject id (with subject_type) |
subject | string | Subject ERN (alternative to the pair) |
direction | string | request | offer |
status | string | Filter by statusDefault: pending |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | array | Connection request/offer entries |
curl "https://platform.ergondata.ai/v1/auth/companies/{company_id}/connection-requests?subject_type=team&subject_id={team_id}" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "d1d1d1d1-0000-4000-8000-000000000001",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"role_id": null,
"direction": "request",
"target_service": "workflows",
"target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/folder/f1/workflow/w1",
"target_ern": "ern:workflows:org/c0ffee00-cafe-babe-dead-beefcafebabe/folder/f1/workflow/w1",
"requested_permissions": ["workflows:workflows:view"],
"message": "Need read access for the billing dashboard",
"status": "pending",
"created_at": "2026-01-10T12:12:00Z"
}
]
}/v1/auth/companies/{company_id}/connection-requests/inboxConnection Inbox
Company-wide inbox of items awaiting the current member's action: approvals are pending requests on zones the caller manages; offers are pending offers to subjects the caller controls (including their own member principal). Items the caller opened are left out. Each entry carries target_label and subject_label, plus requested_by_label when someone other than the subject opened it (for example an agent asking on an API key's behalf).
Bearer (user) token. Company member.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
Response Fields
| Name | Type | Description |
|---|---|---|
approvals* | array | Pending requests the caller can approve/reject |
offers* | array | Pending offers the caller can accept/reject |
curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/connection-requests/inbox \
-H "Authorization: Bearer {token}"Response
200 OK{
"approvals": [
{
"id": "d1d1d1d1-0000-4000-8000-000000000001",
"direction": "request",
"target_service": "workflows",
"target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/folder/f1/workflow/w1",
"target_label": "Invoice approval",
"requested_permissions": ["workflows:workflows:view"],
"status": "pending",
"created_at": "2026-01-10T12:12:00Z",
"requested_by": "e5e5e5e5-0000-4000-8000-000000000002",
"subject_label": "Billing API key",
"requested_by_label": "Billing assistant"
}
],
"offers": []
}/v1/auth/companies/{company_id}/connection-requests/{request_id}/acceptAccept / Approve
Accept an offer (subject side) or approve a request (target-zone admin side). Materializes the connection and, when grant is true, issues the requested (or overridden) permissions.
Bearer (user) token. Offers require subject-manage; requests require target-zone manage.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
request_id* | string (UUID) | Request/offer ID |
Request Body
| Name | Type | Description |
|---|---|---|
permissions | (string | {name, resource})[] | null | Override the permission set granted on accept. Bare names or {name, resource} objects (scoped to a descendant of the target), mirroring the offer body. When omitted, the request/offer's stored permissions are used. |
grant | boolean | Whether to issue grants on acceptDefault: true |
reason | string | null | Optional note |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Request ID |
status* | string | accepted |
direction* | string | request | offer |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/connection-requests/{request_id}/accept \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"grant": true}'Response
200 OK{
"id": "d1d1d1d1-0000-4000-8000-000000000001",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
"role_id": null,
"direction": "request",
"target_service": "workflows",
"target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/folder/f1/workflow/w1",
"target_ern": "ern:workflows:org/c0ffee00-cafe-babe-dead-beefcafebabe/folder/f1/workflow/w1",
"requested_permissions": ["workflows:workflows:view"],
"message": null,
"status": "accepted",
"created_at": "2026-01-10T12:12:00Z"
}/v1/auth/companies/{company_id}/connection-requests/{request_id}/rejectReject
Reject a pending request or offer. Same authority split as accept.
Bearer (user) token. Offers require subject-manage; requests require target-zone manage.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
request_id* | string (UUID) | Request/offer ID |
Request Body
| Name | Type | Description |
|---|---|---|
reason | string | null | Optional rejection reason |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Request ID |
status* | string | rejected |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/connection-requests/{request_id}/reject \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"reason": "Not needed"}'Response
200 OK{
"id": "d1d1d1d1-0000-4000-8000-000000000001",
"direction": "request",
"status": "rejected",
"target_service": "workflows",
"target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/folder/f1/workflow/w1",
"requested_permissions": ["workflows:workflows:view"],
"created_at": "2026-01-10T12:12:00Z"
}/v1/auth/companies/{company_id}/connection-requests/{request_id}/withdrawWithdraw
Withdraw a pending item from the initiating side: the requester withdraws a request, the offering admin withdraws an offer.
Bearer (user) token. Requests require subject-manage; offers require target-zone manage.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
request_id* | string (UUID) | Request/offer ID |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Request ID |
status* | string | withdrawn |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/connection-requests/{request_id}/withdraw \
-H "Authorization: Bearer {token}"Response
200 OK{
"id": "d1d1d1d1-0000-4000-8000-000000000001",
"direction": "offer",
"status": "withdrawn",
"target_service": "buckets",
"target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/bucket/b1",
"requested_permissions": ["buckets:files:view"],
"created_at": "2026-01-10T12:12:00Z"
}Per-Instance Access
Every IAM governance instance — a role, team, API key, agent, or member — has its own Access panel for granting access to that one resource. Each route is gated by the matching iam:company:<resource>:manage permission on that concrete instance and only exposes the grantable verbs for that resource (view, manage, delete/remove). These routes accept user, API key, or agent bearer tokens. Exact agent ToolDef slugs by zone: Role: iam.company.roles.access.eligible.list, iam.company.roles.access.resource_types.list, iam.company.roles.access.grants.list, iam.company.roles.access.grants.create, iam.company.roles.access.grants.batch_create, iam.company.roles.access.grants.delete, iam.company.roles.access.connection_requests.list, iam.company.roles.access.connection_requests.approve, iam.company.roles.access.connection_requests.reject, iam.company.roles.access.connections.list, iam.company.roles.access.connections.revoke; Team: iam.company.teams.access.eligible.list, iam.company.teams.access.resource_types.list, iam.company.teams.access.grants.list, iam.company.teams.access.grants.create, iam.company.teams.access.grants.batch_create, iam.company.teams.access.grants.delete, iam.company.teams.access.connection_requests.list, iam.company.teams.access.connection_requests.approve, iam.company.teams.access.connection_requests.reject, iam.company.teams.access.connections.list, iam.company.teams.access.connections.revoke; API Key: iam.company.api_keys.access.eligible.list, iam.company.api_keys.access.resource_types.list, iam.company.api_keys.access.grants.list, iam.company.api_keys.access.grants.create, iam.company.api_keys.access.grants.batch_create, iam.company.api_keys.access.grants.delete, iam.company.api_keys.access.connection_requests.list, iam.company.api_keys.access.connection_requests.approve, iam.company.api_keys.access.connection_requests.reject, iam.company.api_keys.access.connections.list, iam.company.api_keys.access.connections.revoke; Agent: iam.company.agents.access.eligible.list, iam.company.agents.access.resource_types.list, iam.company.agents.access.grants.list, iam.company.agents.access.grants.create, iam.company.agents.access.grants.batch_create, iam.company.agents.access.grants.delete, iam.company.agents.access.connection_requests.list, iam.company.agents.access.connection_requests.approve, iam.company.agents.access.connection_requests.reject, iam.company.agents.access.connections.list, iam.company.agents.access.connections.revoke; Member: iam.company.members.access.eligible.list, iam.company.members.access.resource_types.list, iam.company.members.access.grants.list, iam.company.members.access.grants.create, iam.company.members.access.grants.batch_create, iam.company.members.access.grants.delete, iam.company.members.access.connection_requests.list, iam.company.members.access.connection_requests.approve, iam.company.members.access.connection_requests.reject, iam.company.members.access.connections.list, iam.company.members.access.connections.revoke.
/v1/auth/companies/{company_id}/roles/{role_id}/access/eligibleRole: List Eligible Principals
List connected principals that are eligible to receive grants on this IAM governance instance. Agent ToolDef slug: iam.company.roles.access.eligible.list.
Bearer token with iam:company:roles:manage on the concrete role instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
role_id* | string (UUID) | Role ID |
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id}/access/eligible -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/roles/{role_id}/access/resource-typesRole: List Grantable Resource Types
Return the authoritative grantable permissions and UUIDs for this instance. Use these IDs when creating grants; never guess a permission ID. Agent ToolDef slug: iam.company.roles.access.resource_types.list.
Bearer token with iam:company:roles:manage on the concrete role instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
role_id* | string (UUID) | Role ID |
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id}/access/resource-types -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/roles/{role_id}/access/grantsRole: List Access Grants
List direct grants scoped to this IAM governance instance. Agent ToolDef slug: iam.company.roles.access.grants.list.
Bearer token with iam:company:roles:manage on the concrete role instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
role_id* | string (UUID) | Role ID |
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id}/access/grants -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/roles/{role_id}/access/grantsRole: Create Access Grant
Create a grant on this instance after selecting an eligible subject and a permission UUID returned by the resource-types operation. Agent ToolDef slug: iam.company.roles.access.grants.create.
Bearer token with iam:company:roles:manage on the concrete role instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
role_id* | string (UUID) | Role ID |
Request Body
| Name | Type | Description |
|---|---|---|
body* | object | Grant subject, permission ID, resource, and effect |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id}/access/grants -H "Authorization: Bearer {token}"Response
201 Created{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/roles/{role_id}/access/grants/{grant_id}Role: Delete Access Grant
Revoke a direct grant scoped to this IAM governance instance. Agent ToolDef slug: iam.company.roles.access.grants.delete.
Bearer token with iam:company:roles:manage on the concrete role instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
role_id* | string (UUID) | Role ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id}/access/grants/{grant_id} -H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/v1/auth/companies/{company_id}/roles/{role_id}/access/connection-requestsRole: List Connection Requests
List pending connection requests and offers targeting this instance. Agent ToolDef slug: iam.company.roles.access.connection_requests.list.
Bearer token with iam:company:roles:manage on the concrete role instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
role_id* | string (UUID) | Role ID |
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id}/access/connection-requests -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/roles/{role_id}/access/connection-requests/{request_id}/approveRole: Approve Connection Request
Approve a request targeting this instance, creating the connection before any requested grants. Agent ToolDef slug: iam.company.roles.access.connection_requests.approve.
Bearer token with iam:company:roles:manage on the concrete role instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
role_id* | string (UUID) | Role ID |
Request Body
| Name | Type | Description |
|---|---|---|
body | object | Decision options, requested permissions, or rejection reason |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id}/access/connection-requests/{request_id}/approve -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/roles/{role_id}/access/connection-requests/{request_id}/rejectRole: Reject Connection Request
Reject a pending connection request targeting this instance. Agent ToolDef slug: iam.company.roles.access.connection_requests.reject.
Bearer token with iam:company:roles:manage on the concrete role instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
role_id* | string (UUID) | Role ID |
Request Body
| Name | Type | Description |
|---|---|---|
body | object | Decision options, requested permissions, or rejection reason |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id}/access/connection-requests/{request_id}/reject -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/roles/{role_id}/access/connectionsRole: List Inbound Connections
List principals and roles currently connected to this instance. Agent ToolDef slug: iam.company.roles.access.connections.list.
Bearer token with iam:company:roles:manage on the concrete role instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
role_id* | string (UUID) | Role ID |
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id}/access/connections -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/roles/{role_id}/access/connections/{connection_id}Role: Revoke Inbound Connection
Sever a connection to this instance without widening any authorization scope. Agent ToolDef slug: iam.company.roles.access.connections.revoke.
Bearer token with iam:company:roles:manage on the concrete role instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
role_id* | string (UUID) | Role ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id}/access/connections/{connection_id} -H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/v1/auth/companies/{company_id}/teams/{team_id}/access/connection-requestsTeam: List Connection Requests
List pending connection requests and offers targeting this instance. Agent ToolDef slug: iam.company.teams.access.connection_requests.list.
Bearer token with iam:company:teams:manage on the concrete team instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
team_id* | string (UUID) | Team ID |
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/teams/{team_id}/access/connection-requests -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/teams/{team_id}/access/connection-requests/{request_id}/approveTeam: Approve Connection Request
Approve a request targeting this instance, creating the connection before any requested grants. Agent ToolDef slug: iam.company.teams.access.connection_requests.approve.
Bearer token with iam:company:teams:manage on the concrete team instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
team_id* | string (UUID) | Team ID |
Request Body
| Name | Type | Description |
|---|---|---|
body | object | Decision options, requested permissions, or rejection reason |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/teams/{team_id}/access/connection-requests/{request_id}/approve -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/teams/{team_id}/access/connection-requests/{request_id}/rejectTeam: Reject Connection Request
Reject a pending connection request targeting this instance. Agent ToolDef slug: iam.company.teams.access.connection_requests.reject.
Bearer token with iam:company:teams:manage on the concrete team instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
team_id* | string (UUID) | Team ID |
Request Body
| Name | Type | Description |
|---|---|---|
body | object | Decision options, requested permissions, or rejection reason |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/teams/{team_id}/access/connection-requests/{request_id}/reject -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/teams/{team_id}/access/connectionsTeam: List Inbound Connections
List principals and roles currently connected to this instance. Agent ToolDef slug: iam.company.teams.access.connections.list.
Bearer token with iam:company:teams:manage on the concrete team instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
team_id* | string (UUID) | Team ID |
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/teams/{team_id}/access/connections -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/teams/{team_id}/access/connections/{connection_id}Team: Revoke Inbound Connection
Sever a connection to this instance without widening any authorization scope. Agent ToolDef slug: iam.company.teams.access.connections.revoke.
Bearer token with iam:company:teams:manage on the concrete team instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
team_id* | string (UUID) | Team ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/teams/{team_id}/access/connections/{connection_id} -H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/eligibleAPI Key: List Eligible Principals
List connected principals that are eligible to receive grants on this IAM governance instance. Agent ToolDef slug: iam.company.api_keys.access.eligible.list.
Bearer token with iam:company:api-keys:manage on the concrete api key instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
api_key_id* | string (UUID) | API Key ID |
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/eligible -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/resource-typesAPI Key: List Grantable Resource Types
Return the authoritative grantable permissions and UUIDs for this instance. Use these IDs when creating grants; never guess a permission ID. Agent ToolDef slug: iam.company.api_keys.access.resource_types.list.
Bearer token with iam:company:api-keys:manage on the concrete api key instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
api_key_id* | string (UUID) | API Key ID |
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/resource-types -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/grantsAPI Key: List Access Grants
List direct grants scoped to this IAM governance instance. Agent ToolDef slug: iam.company.api_keys.access.grants.list.
Bearer token with iam:company:api-keys:manage on the concrete api key instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
api_key_id* | string (UUID) | API Key ID |
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/grants -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/grantsAPI Key: Create Access Grant
Create a grant on this instance after selecting an eligible subject and a permission UUID returned by the resource-types operation. Agent ToolDef slug: iam.company.api_keys.access.grants.create.
Bearer token with iam:company:api-keys:manage on the concrete api key instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
api_key_id* | string (UUID) | API Key ID |
Request Body
| Name | Type | Description |
|---|---|---|
body* | object | Grant subject, permission ID, resource, and effect |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/grants -H "Authorization: Bearer {token}"Response
201 Created{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/grants/{grant_id}API Key: Delete Access Grant
Revoke a direct grant scoped to this IAM governance instance. Agent ToolDef slug: iam.company.api_keys.access.grants.delete.
Bearer token with iam:company:api-keys:manage on the concrete api key instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
api_key_id* | string (UUID) | API Key ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/grants/{grant_id} -H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/connection-requestsAPI Key: List Connection Requests
List pending connection requests and offers targeting this instance. Agent ToolDef slug: iam.company.api_keys.access.connection_requests.list.
Bearer token with iam:company:api-keys:manage on the concrete api key instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
api_key_id* | string (UUID) | API Key ID |
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/connection-requests -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/connection-requests/{request_id}/approveAPI Key: Approve Connection Request
Approve a request targeting this instance, creating the connection before any requested grants. Agent ToolDef slug: iam.company.api_keys.access.connection_requests.approve.
Bearer token with iam:company:api-keys:manage on the concrete api key instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
api_key_id* | string (UUID) | API Key ID |
Request Body
| Name | Type | Description |
|---|---|---|
body | object | Decision options, requested permissions, or rejection reason |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/connection-requests/{request_id}/approve -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/connection-requests/{request_id}/rejectAPI Key: Reject Connection Request
Reject a pending connection request targeting this instance. Agent ToolDef slug: iam.company.api_keys.access.connection_requests.reject.
Bearer token with iam:company:api-keys:manage on the concrete api key instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
api_key_id* | string (UUID) | API Key ID |
Request Body
| Name | Type | Description |
|---|---|---|
body | object | Decision options, requested permissions, or rejection reason |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/connection-requests/{request_id}/reject -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/connectionsAPI Key: List Inbound Connections
List principals and roles currently connected to this instance. Agent ToolDef slug: iam.company.api_keys.access.connections.list.
Bearer token with iam:company:api-keys:manage on the concrete api key instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
api_key_id* | string (UUID) | API Key ID |
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/connections -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/connections/{connection_id}API Key: Revoke Inbound Connection
Sever a connection to this instance without widening any authorization scope. Agent ToolDef slug: iam.company.api_keys.access.connections.revoke.
Bearer token with iam:company:api-keys:manage on the concrete api key instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
api_key_id* | string (UUID) | API Key ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/connections/{connection_id} -H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/v1/auth/companies/{company_id}/agents/{agent_id}/access/eligibleAgent: List Eligible Principals
List connected principals that are eligible to receive grants on this IAM governance instance. Agent ToolDef slug: iam.company.agents.access.eligible.list.
Bearer token with iam:company:agents:manage on the concrete agent instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
agent_id* | string (UUID) | Agent ID |
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/agents/{agent_id}/access/eligible -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/agents/{agent_id}/access/resource-typesAgent: List Grantable Resource Types
Return the authoritative grantable permissions and UUIDs for this instance. Use these IDs when creating grants; never guess a permission ID. Agent ToolDef slug: iam.company.agents.access.resource_types.list.
Bearer token with iam:company:agents:manage on the concrete agent instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
agent_id* | string (UUID) | Agent ID |
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/agents/{agent_id}/access/resource-types -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/agents/{agent_id}/access/grantsAgent: List Access Grants
List direct grants scoped to this IAM governance instance. Agent ToolDef slug: iam.company.agents.access.grants.list.
Bearer token with iam:company:agents:manage on the concrete agent instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
agent_id* | string (UUID) | Agent ID |
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/agents/{agent_id}/access/grants -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/agents/{agent_id}/access/grantsAgent: Create Access Grant
Create a grant on this instance after selecting an eligible subject and a permission UUID returned by the resource-types operation. Agent ToolDef slug: iam.company.agents.access.grants.create.
Bearer token with iam:company:agents:manage on the concrete agent instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
agent_id* | string (UUID) | Agent ID |
Request Body
| Name | Type | Description |
|---|---|---|
body* | object | Grant subject, permission ID, resource, and effect |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/agents/{agent_id}/access/grants -H "Authorization: Bearer {token}"Response
201 Created{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/agents/{agent_id}/access/grants/{grant_id}Agent: Delete Access Grant
Revoke a direct grant scoped to this IAM governance instance. Agent ToolDef slug: iam.company.agents.access.grants.delete.
Bearer token with iam:company:agents:manage on the concrete agent instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
agent_id* | string (UUID) | Agent ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/agents/{agent_id}/access/grants/{grant_id} -H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/v1/auth/companies/{company_id}/agents/{agent_id}/access/connection-requestsAgent: List Connection Requests
List pending connection requests and offers targeting this instance. Agent ToolDef slug: iam.company.agents.access.connection_requests.list.
Bearer token with iam:company:agents:manage on the concrete agent instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
agent_id* | string (UUID) | Agent ID |
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/agents/{agent_id}/access/connection-requests -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/agents/{agent_id}/access/connection-requests/{request_id}/approveAgent: Approve Connection Request
Approve a request targeting this instance, creating the connection before any requested grants. Agent ToolDef slug: iam.company.agents.access.connection_requests.approve.
Bearer token with iam:company:agents:manage on the concrete agent instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
agent_id* | string (UUID) | Agent ID |
Request Body
| Name | Type | Description |
|---|---|---|
body | object | Decision options, requested permissions, or rejection reason |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/agents/{agent_id}/access/connection-requests/{request_id}/approve -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/agents/{agent_id}/access/connection-requests/{request_id}/rejectAgent: Reject Connection Request
Reject a pending connection request targeting this instance. Agent ToolDef slug: iam.company.agents.access.connection_requests.reject.
Bearer token with iam:company:agents:manage on the concrete agent instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
agent_id* | string (UUID) | Agent ID |
Request Body
| Name | Type | Description |
|---|---|---|
body | object | Decision options, requested permissions, or rejection reason |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/agents/{agent_id}/access/connection-requests/{request_id}/reject -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/agents/{agent_id}/access/connectionsAgent: List Inbound Connections
List principals and roles currently connected to this instance. Agent ToolDef slug: iam.company.agents.access.connections.list.
Bearer token with iam:company:agents:manage on the concrete agent instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
agent_id* | string (UUID) | Agent ID |
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/agents/{agent_id}/access/connections -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/agents/{agent_id}/access/connections/{connection_id}Agent: Revoke Inbound Connection
Sever a connection to this instance without widening any authorization scope. Agent ToolDef slug: iam.company.agents.access.connections.revoke.
Bearer token with iam:company:agents:manage on the concrete agent instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
agent_id* | string (UUID) | Agent ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/agents/{agent_id}/access/connections/{connection_id} -H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/v1/auth/companies/{company_id}/members/{member_id}/access/eligibleMember: List Eligible Principals
List connected principals that are eligible to receive grants on this IAM governance instance. Agent ToolDef slug: iam.company.members.access.eligible.list.
Bearer token with iam:company:members:manage on the concrete member instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
member_id* | string (UUID) | Member ID |
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{member_id}/access/eligible -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/members/{member_id}/access/resource-typesMember: List Grantable Resource Types
Return the authoritative grantable permissions and UUIDs for this instance. Use these IDs when creating grants; never guess a permission ID. Agent ToolDef slug: iam.company.members.access.resource_types.list.
Bearer token with iam:company:members:manage on the concrete member instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
member_id* | string (UUID) | Member ID |
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{member_id}/access/resource-types -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/members/{member_id}/access/grantsMember: List Access Grants
List direct grants scoped to this IAM governance instance. Agent ToolDef slug: iam.company.members.access.grants.list.
Bearer token with iam:company:members:manage on the concrete member instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
member_id* | string (UUID) | Member ID |
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{member_id}/access/grants -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/members/{member_id}/access/grantsMember: Create Access Grant
Create a grant on this instance after selecting an eligible subject and a permission UUID returned by the resource-types operation. Agent ToolDef slug: iam.company.members.access.grants.create.
Bearer token with iam:company:members:manage on the concrete member instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
member_id* | string (UUID) | Member ID |
Request Body
| Name | Type | Description |
|---|---|---|
body* | object | Grant subject, permission ID, resource, and effect |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{member_id}/access/grants -H "Authorization: Bearer {token}"Response
201 Created{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/members/{member_id}/access/grants/{grant_id}Member: Delete Access Grant
Revoke a direct grant scoped to this IAM governance instance. Agent ToolDef slug: iam.company.members.access.grants.delete.
Bearer token with iam:company:members:manage on the concrete member instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
member_id* | string (UUID) | Member ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{member_id}/access/grants/{grant_id} -H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/v1/auth/companies/{company_id}/members/{member_id}/access/connection-requestsMember: List Connection Requests
List pending connection requests and offers targeting this instance. Agent ToolDef slug: iam.company.members.access.connection_requests.list.
Bearer token with iam:company:members:manage on the concrete member instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
member_id* | string (UUID) | Member ID |
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{member_id}/access/connection-requests -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/members/{member_id}/access/connection-requests/{request_id}/approveMember: Approve Connection Request
Approve a request targeting this instance, creating the connection before any requested grants. Agent ToolDef slug: iam.company.members.access.connection_requests.approve.
Bearer token with iam:company:members:manage on the concrete member instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
member_id* | string (UUID) | Member ID |
Request Body
| Name | Type | Description |
|---|---|---|
body | object | Decision options, requested permissions, or rejection reason |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{member_id}/access/connection-requests/{request_id}/approve -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/members/{member_id}/access/connection-requests/{request_id}/rejectMember: Reject Connection Request
Reject a pending connection request targeting this instance. Agent ToolDef slug: iam.company.members.access.connection_requests.reject.
Bearer token with iam:company:members:manage on the concrete member instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
member_id* | string (UUID) | Member ID |
Request Body
| Name | Type | Description |
|---|---|---|
body | object | Decision options, requested permissions, or rejection reason |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{member_id}/access/connection-requests/{request_id}/reject -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/members/{member_id}/access/connectionsMember: List Inbound Connections
List principals and roles currently connected to this instance. Agent ToolDef slug: iam.company.members.access.connections.list.
Bearer token with iam:company:members:manage on the concrete member instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
member_id* | string (UUID) | Member ID |
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{member_id}/access/connections -H "Authorization: Bearer {token}"Response
200 OK{ "items": [], "total": 0 }/v1/auth/companies/{company_id}/members/{member_id}/access/connections/{connection_id}Member: Revoke Inbound Connection
Sever a connection to this instance without widening any authorization scope. Agent ToolDef slug: iam.company.members.access.connections.revoke.
Bearer token with iam:company:members:manage on the concrete member instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
member_id* | string (UUID) | Member ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{member_id}/access/connections/{connection_id} -H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/v1/auth/companies/{company_id}/teams/{team_id}/access/eligibleList Eligible Principals
List the principals eligible to receive a grant on this instance — those with the right service access and a connection to it.
Bearer token. Requires iam:company:teams:manage on the instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
team_id* | string (UUID) | Instance ID (here, a team) |
Response Fields
| Name | Type | Description |
|---|---|---|
principal_type* | string | member | api_key | agent | team | role |
principal_id* | string (UUID) | Principal ID |
label* | string | Display label |
display_name* | string | null | Display name |
avatar_url* | string | null | Avatar URL |
curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/teams/{team_id}/access/eligible \
-H "Authorization: Bearer {token}"Response
200 OK[
{
"principal_type": "member",
"principal_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
"label": "ana@acme.com",
"display_name": "Ana Ribeiro",
"avatar_url": null
}
]/v1/auth/companies/{company_id}/teams/{team_id}/access/resource-typesList Grantable Permissions
Return the grantable permission catalog scoped to this instance surface (filtered to the verbs that can be granted on this resource type).
Bearer token. Requires iam:company:teams:manage on the instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
team_id* | string (UUID) | Instance ID |
Response Fields
| Name | Type | Description |
|---|---|---|
resource_types* | array | Resource-type tree nodes |
permissions* | array | Grantable permissions with their resource type |
resource_type_edges* | array | Edges between resource types |
curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/teams/{team_id}/access/resource-types \
-H "Authorization: Bearer {token}"Response
200 OK{
"resource_types": [
{ "id": "rt-team", "name": "Team", "slug": "team", "parent_id": null, "children": [] }
],
"permissions": [
{ "id": "55555555-0000-4000-8000-000000000010", "name": "iam:company:teams:view" },
{ "id": "55555555-0000-4000-8000-000000000011", "name": "iam:company:teams:manage" }
],
"resource_type_edges": []
}/v1/auth/companies/{company_id}/teams/{team_id}/access/grantsList Instance Grants
List the grants minted on this instance (direct grants only; inherited grants are excluded).
Bearer token. Requires iam:company:teams:manage on the instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
team_id* | string (UUID) | Instance ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
page | integer | Page number (>= 1)Default: 1 |
limit | integer | Page size (1–500)Default: 100 |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | array | Grant entries on this instance |
total* | integer | Total grants |
page* | integer | Current page |
limit* | integer | Page size |
curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/teams/{team_id}/access/grants \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "44444444-0000-4000-8000-000000000020",
"principal_type": "member",
"principal_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
"principal_label": "ana@acme.com",
"permission_id": "55555555-0000-4000-8000-000000000010",
"permission_name": "iam:company:teams:view",
"resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/team/7ea11000-0000-4000-8000-000000000001",
"effect": "allow",
"granted_at": "2026-01-10T12:14:00Z"
}
],
"total": 1,
"page": 1,
"limit": 100
}/v1/auth/companies/{company_id}/teams/{team_id}/access/grantsCreate Instance Grant
Grant a principal access to this instance. The permission must be in the instance's grantable set; the resource is pinned to the instance. Pass either permission_id or permission_name.
Bearer token. Requires iam:company:teams:manage on the instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
team_id* | string (UUID) | Instance ID |
Request Body
| Name | Type | Description |
|---|---|---|
principal_type* | string | member | api_key | agent | team | role | automation | workflow | worksheet |
principal_id* | string (UUID) | Principal to grant |
permission_id | string (UUID) | null | Permission to grant (or use permission_name) |
permission_name | string | null | Permission name (or use permission_id) |
resource | string | null | Resource path; defaults to this instance |
effect | string | allow | denyDefault: allow |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | string (UUID) | Grant row ID |
permission_id* | string (UUID) | Permission granted |
resource* | string | Resource path |
effect* | string | allow | deny |
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/teams/{team_id}/access/grants \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"principal_type": "member",
"principal_id": "{member_id}",
"permission_name": "iam:company:teams:view",
"effect": "allow"
}'Response
201 Created{
"id": "44444444-0000-4000-8000-000000000020",
"permission_id": "55555555-0000-4000-8000-000000000010",
"name": "iam:company:teams:view",
"resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/team/7ea11000-0000-4000-8000-000000000001",
"effect": "allow",
"is_system": false,
"granted_at": "2026-01-10T12:14:00Z"
}/v1/auth/companies/{company_id}/teams/{team_id}/access/grants/{grant_id}Delete Instance Grant
Revoke a grant scoped to this instance. Returns 404 if the grant is outside the instance's resource prefix.
Bearer token. Requires iam:company:teams:manage on the instance.
Path Parameters
| Name | Type | Description |
|---|---|---|
company_id* | string (UUID) | Company ID |
team_id* | string (UUID) | Instance ID |
grant_id* | string (UUID) | Grant row ID |
curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/teams/{team_id}/access/grants/{grant_id} \
-H "Authorization: Bearer {token}"Response
204 No Content// 204 No ContentProtocol and Platform Operations
Public IAM operations that either document agent-callable invitation/team capabilities or support interactive SSO and privileged platform administration. The SSO and platform-admin routes remain intentionally outside the agent tool catalog.
/v1/auth/companies/{company_id}/invitations/{invitation_id}Cancel Company Invitation
Cancel a pending or expired invitation so it can no longer be accepted. Already-cancelled invitations return 204. Agent ToolDef slug: iam.company.invitations.cancel.
Bearer token with iam:company:members:invite.
curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/invitations/{invitation_id} -H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/v1/auth/team-principals/{principal_id}/expanded-membersExpand Team Principal Members
Flatten a team principal into its concrete leaf members. Agent ToolDef slug: iam.company.teams.members.expanded.list.
Authenticated bearer token with iam:company:teams:view in the team's company.
curl -X GET https://platform.ergondata.ai/v1/auth/team-principals/{principal_id}/expanded-members -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }/v1/auth/companies/{company_id}/resourcesList Organization Resources
List every federated zone in the organization with its creator, live managers, orphaned flag and your own access. Filters: services, resource_types, status, created_by, managed_by, q, include_system, include_deleted; sort recent or name; cursor paging. Seeing a zone grants nothing inside it. Agent ToolDef slug: iam.company.resources.list.
Bearer token with iam:company:resources:view.
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/resources -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }/v1/auth/companies/{company_id}/resources/summarySummarize Organization Resources
Inventory counters (zones, orphaned, your open requests, created by former members) and filter facets, scoped by services and the system/deleted toggles. Agent ToolDef slug: iam.company.resources.summary.
Bearer token with iam:company:resources:view.
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/resources/summary -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }/v1/auth/companies/{company_id}/resources/{resource_id}Get Organization Resource
One inventory zone with its nested zones, connections and pending access requests. Agent ToolDef slug: iam.company.resources.get.
Bearer token with iam:company:resources:view.
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/resources/{resource_id} -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }/v1/auth/companies/{company_id}/resources/{resource_id}/accessList Who Has Access to an Organization Resource
Who holds grants on one inventory zone, one entry per member, team, role, agent or API key, paged by subject (page, limit up to 100). Each grant has a scope: zone (on the zone), inherited (on a parent zone or a covering wildcard) or organization (organization-wide); only the zone's own service permissions count, not organization-level ones such as launcher or create. Roles with only organization-wide grants (owner, admin) are summarized in organization_roles. Each entry says whether the subject is connected to the zone or a parent, directly or through its teams and roles, and whether its grants need that connection. Grants on things inside the zone (scope inside) are included only when you also hold iam:company:grants:view; otherwise inner_visible is false and they are left out entirely. Inherited and inside grants carry a breadcrumb of labelled path segments. Agent ToolDef slug: iam.company.resources.access.
Bearer token with iam:company:resources:view (inside grants also need iam:company:grants:view).
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/resources/{resource_id}/access -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }/v1/auth/companies/{company_id}/resources/{resource_id}/recoverablePreview Resource Recovery
Dry run of a recover or takeover (mode=recover|takeover): whether you may claim the zone, the reason when you may not, the managers who would be notified and the nested zones it would include (at most 200 per call; nested_total and nested_truncated say when more remain). Writes nothing. Agent ToolDef slug: iam.company.resources.recoverable.
Bearer token with iam:company:resources:view.
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/resources/{resource_id}/recoverable -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }/v1/auth/companies/{company_id}/resources/{resource_id}/access-presetsGet Resource Access Presets
The permissions an access request for this zone can ask for: view (the zone's view permission) and full (Full control: manage the zone and everything in it; conversations also get privacy management). default_preset is view for conversations and full for every other zone. Writes nothing. Agent ToolDef slug: iam.company.resources.access_presets.
Bearer token with iam:company:resources:view.
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/resources/{resource_id}/access-presets -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }/v1/auth/companies/{company_id}/resources/{resource_id}/recoverRecover Organization Resource
Claim a zone nobody can answer for because it has no manager. Connects you to the zone and always grants full control (its creator access); include_nested adds orphaned nested zones. Never applies to deleted, platform-managed or resource-owned zones; a zone with managers returns 409 has_managers, even after your request to it escalated (take it over instead). awaiting_requests in the response counts the pending requests on or under the claimed zones that wait in your connection inbox, by the inbox's own rule. Emits iam.resource.recovered. Agent ToolDef slug: iam.company.resources.recover.
Bearer token with iam:company:resources:recover.
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/resources/{resource_id}/recover -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }/v1/auth/companies/{company_id}/resources/{resource_id}/takeoverTake Over Organization Resource
Claim any claimable zone with a reason of at least 10 characters, with full control (preset full) or view only (preset view). This is how an escalated request is acted on. Current managers keep their access and are emailed; include_nested adds every nested zone except those an owner manages, and only owners may take over a zone an owner manages (403 managed_by_owner). awaiting_requests in the response counts the pending requests on or under the claimed zones that wait in your connection inbox, by the inbox's own rule. Emits iam.resource.taken_over. Agent ToolDef slug: iam.company.resources.takeover.
Bearer token with iam:company:resources:takeover.
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/resources/{resource_id}/takeover -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }/v1/auth/sso/providersList SSO Providers
List enabled OIDC providers for the interactive sign-in UI. This protocol route is intentionally not an agent tool.
No authentication required.
curl -X GET https://platform.ergondata.ai/v1/auth/sso/providers -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }/v1/auth/sso/{provider_slug}/callbackComplete SSO Callback
Provider callback that validates state and completes login or account linking. A sign-in started with entry_company_slug follows that company's sign-in methods: a method it leaves out returns to the sign-in page with sso_method_not_allowed, and an account outside its Google Workspace domains or Microsoft tenants with sso_domain_not_allowed. When two-factor covers every sign-in for a company the account belongs to, the callback returns to the sign-in page to enter the platform code (or set up a factor first) before the session starts; the code is completed with Verify MFA Challenge, or Verify MFA Setup when a factor is set up first. This provider callback is intentionally not an agent tool.
OIDC provider callback; rate limited.
curl -X GET https://platform.ergondata.ai/v1/auth/sso/{provider_slug}/callback -H "Authorization: Bearer {token}"Response
302{ "detail": "See response schema" }/v1/auth/sso/{provider_slug}/linkLink SSO Provider
Start an authenticated interactive flow to link an OIDC identity to the current user. This session operation is intentionally not an agent tool.
Authenticated user bearer token.
curl -X POST https://platform.ergondata.ai/v1/auth/sso/{provider_slug}/link -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }/v1/auth/platform-admin/meGet Platform Admin Session
Return the current operator's platform-level permissions. Platform-admin operations are intentionally not agent tools.
Bearer token with iam:platform:*.
curl -X GET https://platform.ergondata.ai/v1/auth/platform-admin/me -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }/v1/auth/platform-admin/companiesList Platform Companies
List companies for the platform operations console. Platform-admin operations are intentionally not agent tools.
Bearer token with iam:platform:companies:view.
curl -X GET https://platform.ergondata.ai/v1/auth/platform-admin/companies -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }/v1/auth/platform-admin/companies/{company_id}/servicesList Platform Company Services
List platform-controlled service entitlements for a company. This platform-admin operation is intentionally not an agent tool.
Bearer token with iam:platform:company-services:manage.
curl -X GET https://platform.ergondata.ai/v1/auth/platform-admin/companies/{company_id}/services -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }/v1/auth/platform-admin/companies/{company_id}/services/{service_id}Enable Platform Company Service
Enable a service entitlement at the platform boundary. This platform-admin operation is intentionally not an agent tool.
Bearer token with iam:platform:company-services:manage.
curl -X PUT https://platform.ergondata.ai/v1/auth/platform-admin/companies/{company_id}/services/{service_id} -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }/v1/auth/platform-admin/companies/{company_id}/services/{service_id}Disable Platform Company Service
Disable a service entitlement at the platform boundary. This platform-admin operation is intentionally not an agent tool.
Bearer token with iam:platform:company-services:manage.
curl -X DELETE https://platform.ergondata.ai/v1/auth/platform-admin/companies/{company_id}/services/{service_id} -H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/v1/auth/platform-admin/companies/{company_id}/feature-flagsList Platform Feature Flags
List effective company feature flags and dependency state. This platform-admin operation is intentionally not an agent tool.
Bearer token with iam:platform:feature-flags:manage.
curl -X GET https://platform.ergondata.ai/v1/auth/platform-admin/companies/{company_id}/feature-flags -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }/v1/auth/platform-admin/companies/{company_id}/feature-flags/{key}Set Platform Feature Flag
Set a company feature-flag override after dependency validation. This platform-admin operation is intentionally not an agent tool.
Bearer token with iam:platform:feature-flags:manage.
curl -X PUT https://platform.ergondata.ai/v1/auth/platform-admin/companies/{company_id}/feature-flags/{key} -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }/v1/auth/platform-admin/companies/{company_id}/feature-flags/{key}Clear Platform Feature Flag
Remove a company feature-flag override and restore its default. This platform-admin operation is intentionally not an agent tool.
Bearer token with iam:platform:feature-flags:manage.
curl -X DELETE https://platform.ergondata.ai/v1/auth/platform-admin/companies/{company_id}/feature-flags/{key} -H "Authorization: Bearer {token}"Response
204 No Content// 204 No Content/v1/auth/platform-admin/usersList Platform Users
Search the global user directory (email/name, paginated) with MFA status, sign-in methods, lock state, last sign-in and live company count. Server-side filters: mfa (on|off), locked (true|false), sso (any|none|<provider>), company_id. This platform-admin operation is intentionally not an agent tool.
Bearer token with iam:platform:*.
curl -X GET https://platform.ergondata.ai/v1/auth/platform-admin/users -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }/v1/auth/platform-admin/users/{user_id}Get Platform User
Return one user's sign-in methods, MFA state (pending enrollment, recovery codes remaining) and company memberships with roles. This platform-admin operation is intentionally not an agent tool.
Bearer token with iam:platform:*.
curl -X GET https://platform.ergondata.ai/v1/auth/platform-admin/users/{user_id} -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }/v1/auth/platform-admin/users/{user_id}/mfa/resetReset Platform User MFA
Operator break-glass: delete every TOTP factor and recovery code for a user so they re-enroll at next login. Emits iam.mfa.admin_reset. This platform-admin operation is intentionally not an agent tool.
Bearer token with iam:platform:*.
curl -X POST https://platform.ergondata.ai/v1/auth/platform-admin/users/{user_id}/mfa/reset -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }/v1/auth/me/access-historyGet My Access History
Paginated canonical auth events for the calling user: sign-ins, failed attempts, password changes, lockouts and session terminations with IP, user agent, method and result. Query: page, limit (max 100). This self-service session route is intentionally not an agent tool.
Authenticated user bearer token.
curl -X GET https://platform.ergondata.ai/v1/auth/me/access-history -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }/v1/auth/me/sessions/revoke-allRevoke My Sessions
Revoke every refresh token of the calling user (sign out everywhere) and clear the refresh cookie. Emits auth.session.terminated. This self-service session route is intentionally not an agent tool.
Authenticated user bearer token.
curl -X POST https://platform.ergondata.ai/v1/auth/me/sessions/revoke-all -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }/v1/auth/companies/{company_id}/security-policyUpdate Company Security Policy
Set per-company account-lockout (threshold, window, duration) and idle-session timeout overrides; null inherits the platform default. The values apply when members sign in at the company's start URL; at the platform login, members of several companies get the strictest values across the companies it opens. Too many failed attempts across all sign-in pages lock the account on every one of them for a while. Also sets access-request escalation: connection_request_escalation_days (1-90, null = off) and connection_request_warning_days (reminder window, default 3). Emits iam.company.security_policy_changed. Agent ToolDef slug: iam.company.security_policy.update.
Bearer token with iam:company:settings.
curl -X PATCH https://platform.ergondata.ai/v1/auth/companies/{company_id}/security-policy -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }/v1/auth/companies/{company_id}/members/{user_id}/access-historyList Member Access History
Paginated auth events (including failed attempts) for an active member of the company. A sign-in made at this company's start URL or one of its app addresses has details.surface start_url, and details.portal_app_id and details.portal_app_title when it was made in one of its portal Apps; other companies see the same event without those details. Agent ToolDef slug: iam.company.members.access_history.list.
Bearer token with iam:company:members:manage.
curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{user_id}/access-history -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }/v1/auth/companies/{company_id}/members/{user_id}/sessions/revokeRevoke Member Sessions
Tenant admin: revoke every refresh token of a company member (user-global sign-out). Emits auth.session.terminated. Agent ToolDef slug: iam.company.members.sessions.revoke.
Bearer token with iam:company:members:manage.
curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{user_id}/sessions/revoke -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }/v1/auth/platform-admin/auth-eventsList Platform Auth Events
Cross-user canonical auth events with filters: email, event_type, success, from, to, page, limit (max 200). Includes failed attempts for unknown e-mails. Platform-admin operations are intentionally not agent tools.
Bearer token with iam:platform:*.
curl -X GET https://platform.ergondata.ai/v1/auth/platform-admin/auth-events -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }/v1/auth/platform-admin/users/{user_id}/access-historyGet Platform User Access History
Paginated canonical auth events for one user. Platform-admin operations are intentionally not agent tools.
Bearer token with iam:platform:*.
curl -X GET https://platform.ergondata.ai/v1/auth/platform-admin/users/{user_id}/access-history -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }/v1/auth/platform-admin/users/{user_id}/unlockUnlock Platform User
Operator manual unlock of an account locked after repeated failed sign-ins. Emits auth.account.unlocked. This platform-admin operation is intentionally not an agent tool.
Bearer token with iam:platform:*.
curl -X POST https://platform.ergondata.ai/v1/auth/platform-admin/users/{user_id}/unlock -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }/v1/auth/platform-admin/users/{user_id}/sessions/revokeRevoke Platform User Sessions
Operator: revoke every refresh token of a user. Emits auth.session.terminated. This platform-admin operation is intentionally not an agent tool.
Bearer token with iam:platform:*.
curl -X POST https://platform.ergondata.ai/v1/auth/platform-admin/users/{user_id}/sessions/revoke -H "Authorization: Bearer {token}"Response
200 OK{ "detail": "See response schema" }