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.

Base URL/v1/auth

Automation triggers: view every IAM event, payload field, and predicate.

Authentication

Exchange API key credentials for short-lived access tokens.

POST/v1/auth/token

Create 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

NameTypeDescription
client_id*
stringAPI key client ID
client_secret*
stringAPI key client secret

Response Fields

NameTypeDescription
access_token*
stringBearer token for API calls
token_type*
stringAlways "bearer"
expires_in*
integerToken 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.

POST/v1/auth/register

Register 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

NameTypeDescription
email*
string (email)User email address
password*
stringPassword (minimum 12 characters, with at least 3 of: lowercase, uppercase, digits, symbols)
name*
stringDisplay name (minimum 1 character)

Response Fields

NameTypeDescription
id*
string (UUID)User ID
email*
stringUser email
name*
stringDisplay name
is_active*
booleanWhether the account is active
avatar_url
string | nullAvatar 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"
}
POST/v1/auth/login

Login

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

NameTypeDescription
email*
string (email)User email address
password*
stringUser password
entry_company_slug
string | nullSlug of the company whose start URL the person is signing in at (max 255 characters). Omit for the platform login.
entry_app_id
UUID | nullWith 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

NameTypeDescription
access_token
stringBearer token (present on success, absent on MFA challenge)
token_type
stringAlways "bearer" on success
company_id
string (UUID) | nullActive company bound to the token, if any
mfa_required
booleanPresent and true when MFA must be completed
mfa_token
stringChallenge token to pass to MFA verify (challenge only)
attempts_left
integerRemaining MFA attempts (challenge only)
enrollment_required
booleanWhether 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
}
POST/v1/auth/refresh

Refresh 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

NameTypeDescription
company_id
string (UUID) | nullThe company in use. The place this session opens it through counts as used now. The body is optional.
touch
booleanDefault true. false when the person did not make this call themselves: nothing counts as used.

Response Fields

NameTypeDescription
access_token*
stringNew bearer token
token_type
stringAlways "bearer"
company_id
string (UUID) | nullActive 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"
}
POST/v1/auth/logout

Logout

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
POST/v1/auth/idle-sign-out

Idle 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

NameTypeDescription
sign_in_page*
string"platform" or a company id (UUID)

Response Fields

NameTypeDescription
access_token*
stringBearer token for the places the session keeps
token_type
stringAlways "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"
}
POST/v1/auth/select-active-company

Select 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

NameTypeDescription
company_id*
string (UUID)Company to activate (must be a company you belong to)
touch
booleanDefault 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

NameTypeDescription
access_token*
stringCompany-scoped bearer token
token_type
stringAlways "bearer"
company_id
string (UUID) | nullCompany bound to the token
console_access
boolean | nullWhether 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
}
GET/v1/auth/me

Get 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

NameTypeDescription
user*
objectThe authenticated user (UserResponse)
companies*
arrayCompany memberships with roles, permissions, and services
platform_permissions
array<string>Platform-level permissions
platform_sign_in
booleanWhether 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
integerIdle 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
}
PATCH/v1/auth/me

Update 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

NameTypeDescription
locale
string | nullSet 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": []
}
GET/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

NameTypeDescription
company_slug*
stringCompany slug from the start URL

Response Fields

NameTypeDescription
company_name*
stringCompany name
company_slug*
stringCompany slug
company_avatar_url
string | nullCompany icon as a temporary signed URL, or null
company_logo_url
string | nullLogo for light mode as a temporary signed URL, or null
company_logo_dark_url
string | nullLogo 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-corp

Response

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.

POST/v1/auth/verify-email

Verify Email

Confirm a user's email address using the token from the verification email.

No authentication required.

Request Body

NameTypeDescription
token*
stringVerification 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
{}
POST/v1/auth/resend-verification

Resend Verification Email

Send a fresh email-verification link to the given address.

No authentication required.

Request Body

NameTypeDescription
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
{}
POST/v1/auth/forgot-password

Forgot 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

NameTypeDescription
email*
string (email)Account email address
return_to
stringAn 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"
}
POST/v1/auth/reset-password

Reset Password

Set a new password using the token from a password-reset email.

No authentication required.

Request Body

NameTypeDescription
token*
stringReset token from the email
password*
stringNew 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
{}
POST/v1/auth/change-password

Change Password

Change the authenticated user's password by supplying the current one.

Bearer token required.

Request Body

NameTypeDescription
current_password*
stringCurrent password
new_password*
stringNew 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
{}
POST/v1/auth/change-email

Change 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

NameTypeDescription
new_email*
string (email)New email address
password*
stringCurrent 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
{}
POST/v1/auth/verify-email-change

Verify Email Change

Confirm a pending email-address change using the token from the confirmation email.

No authentication required.

Request Body

NameTypeDescription
token*
stringEmail-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.

GET/v1/auth/companies/{company_id}/me

Get 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

NameTypeDescription
company_id*
string (UUID)Company ID (Apps and agents inject the current company)

Response Fields

NameTypeDescription
principal_id*
string (UUID)The caller's company-scoped principal ID
principal_type*
stringPrincipal kind, e.g. "member", "agent", "api_key"
company_id*
string (UUID)Company the identity belongs to
company_member_id*
string (UUID) | nullMembership ID (members only)
user_id*
string (UUID) | nullUser ID (members only)
display_name*
stringUser name for members; agent or API key name otherwise
email*
string | nullUser email (members only)
teams*
arrayTeams the caller belongs to
roles*
arrayRoles 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"
    }
  ]
}
PUT/v1/auth/me/avatar

Upload User Avatar

Upload or replace the current user's avatar image (multipart/form-data).

Bearer token required.

Request Body

NameTypeDescription
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=..."
}
DELETE/v1/auth/me/avatar

Delete 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
{}
GET/v1/auth/me/identities

List My Identities

List the federated (SSO) identities linked to the current user.

Bearer token required.

Response Fields

NameTypeDescription
id*
string (UUID)Identity link ID
provider*
stringIdentity provider slug
email_at_link*
stringEmail returned by the provider when linked
last_login_at
string (date-time) | nullMost 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"
  }
]

Multi-Factor Authentication

Enroll, verify, disable, and recover TOTP-based multi-factor authentication.

GET/v1/auth/mfa/status

MFA Status

Report whether MFA is enabled for the current user and how many recovery codes remain.

Bearer token required.

Response Fields

NameTypeDescription
enabled*
booleanWhether a confirmed factor exists
company_requires_mfa
booleanWhether the active company mandates MFA
enrolled_at
string (date-time) | nullWhen the factor was enrolled
last_used_at
string (date-time) | nullWhen MFA was last used
recovery_codes_remaining
integerUnused 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
}
POST/v1/auth/mfa/setup

Begin 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

NameTypeDescription
label
string | nullOptional label for the authenticator entry (max 64 chars)
mfa_token
string | nullChallenge token, required only during forced enrollment

Response Fields

NameTypeDescription
secret*
stringTOTP shared secret
otpauth_uri*
stringotpauth:// 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"
}
POST/v1/auth/mfa/setup/verify

Verify 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

NameTypeDescription
code*
stringCurrent 6-digit TOTP code
mfa_token
string | nullChallenge token, required only during forced enrollment

Response Fields

NameTypeDescription
recovery_codes*
array<string>One-time recovery codes (stored hashed; shown once)
access_token
string | nullBearer token (populated during forced enrollment)
token_type
stringAlways "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"
}
POST/v1/auth/mfa/verify

Verify 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

NameTypeDescription
mfa_token*
stringChallenge token from /login
code
string | null6-digit TOTP code
recovery_code
string | nullA recovery code (alternative to a TOTP code)

Response Fields

NameTypeDescription
access_token*
stringBearer token
token_type
stringAlways "bearer"
company_id
string (UUID) | nullActive 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
}
POST/v1/auth/mfa/disable

Disable MFA

Disable MFA for the current user. Requires the password plus either a TOTP code or a recovery code.

Bearer token required.

Request Body

NameTypeDescription
password*
stringCurrent password
code
string | null6-digit TOTP code
recovery_code
string | nullA 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
{}
POST/v1/auth/mfa/recovery-codes/regenerate

Regenerate 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

NameTypeDescription
password*
stringCurrent password
code
string | null6-digit TOTP code
recovery_code
string | nullA recovery code

Response Fields

NameTypeDescription
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.

POST/v1/auth/companies

Create 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

NameTypeDescription
name*
stringCompany display name
slug*
stringURL-safe slug (2–255 chars, ^[a-z0-9][a-z0-9-]*$)

Response Fields

NameTypeDescription
id*
string (UUID)Company ID
name*
stringCompany name
slug*
stringCompany slug
description
string | nullDescription
avatar_url
string | nullAvatar 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"
}
GET/v1/auth/companies

List 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

NameTypeDescription
id*
string (UUID)Company ID
name*
stringCompany name
slug*
stringCompany 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"
  }
]
GET/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

NameTypeDescription
company_id*
string (UUID)Company ID

Response Fields

NameTypeDescription
id*
string (UUID)Company ID
name*
stringCompany name
slug*
stringCompany slug
member_count*
integerNumber of members
enabled_services*
array<string>Service slugs enabled for the company
require_mfa
booleanWhether 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
objectThe 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}" | nullThe 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*
booleanWhether 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"
}
DELETE/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

NameTypeDescription
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
PATCH/v1/auth/companies/{company_id}/profile

Update Company Profile

Update a company's name and/or description.

Bearer token with iam:company:settings.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID

Request Body

NameTypeDescription
name
string | nullNew name (1–255 chars)
description
string | nullNew description (max 5000)

Response Fields

NameTypeDescription
id*
string (UUID)Company ID
name*
stringUpdated name
description
string | nullUpdated 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"
}
PATCH/v1/auth/companies/{company_id}/mfa-policy

Update 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

NameTypeDescription
company_id*
string (UUID)Company ID

Request Body

NameTypeDescription
require_mfa
booleanWhether MFA is mandatory
require_mfa_for
"password" | "every_sign_in"Which sign-ins two-factor covers

Response Fields

NameTypeDescription
id*
string (UUID)Company ID
require_mfa
booleanUpdated 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"
}
PATCH/v1/auth/companies/{company_id}/sign-in-methods

Update 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

NameTypeDescription
company_id*
string (UUID)Company ID

Request Body

NameTypeDescription
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

NameTypeDescription
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": []
}
PUT/v1/auth/companies/{company_id}/avatar

Upload 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

NameTypeDescription
company_id*
string (UUID)Company ID

Query Parameters

NameTypeDescription
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

NameTypeDescription
file*
binary (multipart/form-data)Image file to upload; for a logo, a wide image with a transparent background works best

Response Fields

NameTypeDescription
avatar_url
stringkind=icon: the Icon as a temporary signed URL
logo_url
string | nullkind=logo: Logo for light mode as a temporary signed URL, or null
logo_dark_url
string | nullkind=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=..."
}
DELETE/v1/auth/companies/{company_id}/avatar

Delete 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

NameTypeDescription
company_id*
string (UUID)Company ID

Query Parameters

NameTypeDescription
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

NameTypeDescription
detail
stringkind=icon: "Avatar removed"
logo_url
string | nullkind=logo: Logo for light mode after the removal, or null
logo_dark_url
string | nullkind=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.

GET/v1/auth/companies/{company_id}/members

List Members

List a company's members (paginated).

Bearer token required.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID

Query Parameters

NameTypeDescription
page
integerPage number (min 1)Default: 1
limit
integerItems per page (1–100)Default: 50

Response Fields

NameTypeDescription
items*
arrayMember records
total*
integerTotal members
page*
integerCurrent page
limit*
integerPage 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
}
POST/v1/auth/companies/{company_id}/members

Add 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

NameTypeDescription
company_id*
string (UUID)Company ID

Request Body

NameTypeDescription
email*
string (email)Email of the user to add/invite
role
string | nullSingle role name (max 50 chars)
roles
array<string> | nullRole names to assign
service_slugs
array<string> | nullService slugs to grant on join
team_ids
array<UUID> | nullTeams 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 | nullOptional 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"
}
DELETE/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

NameTypeDescription
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
PATCH/v1/auth/companies/{company_id}/members/{user_id}/access

Update 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

NameTypeDescription
company_id*
string (UUID)Company ID
user_id*
string (UUID)Member user ID (your own only when console_access is omitted)

Request Body

NameTypeDescription
console_access
booleantrue 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 | nulltrue 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

NameTypeDescription
user_id*
string (UUID)Member user ID
company_id*
string (UUID)Company ID
console_access*
booleanThe member's console access after the update
access_portal
"default" | "platform_default" | "app:{app_id}" | nullThe member's own access portal after the update; null inherits
require_portal_sign_in
boolean | nullThe member's own sign-in requirement after the update; null inherits
effective_access_portal
"platform_default" | "app:{app_id}" | nullThe access portal that applies to the member; null is Default
effective_require_portal_sign_in*
booleanWhether 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
}
PATCH/v1/auth/companies/{company_id}/access-portal

Update 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

NameTypeDescription
company_id*
string (UUID)Company ID

Request Body

NameTypeDescription
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
booleantrue 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

NameTypeDescription
company_id*
string (UUID)Company ID
access_portal
"platform_default" | "app:{app_id}" | nullThe organization's access portal after the update
require_portal_sign_in*
booleanWhether members who inherit it must sign in at the start URL
start_url*
stringThe 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"
}
GET/v1/auth/companies/{company_id}/members/{user_id}/roles

List Member Roles

List the roles directly assigned to a company member. Agent ToolDef slug: iam.company.members.roles.list.

Bearer token required.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID
user_id*
string (UUID)Member user ID

Response Fields

NameTypeDescription
id*
string (UUID)Assignment ID
role_id*
string (UUID)Role ID
name*
stringRole name
is_system*
booleanWhether 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"
  }
]
POST/v1/auth/companies/{company_id}/members/{user_id}/roles

Assign 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

NameTypeDescription
company_id*
string (UUID)Company ID
user_id*
string (UUID)Member user ID

Request Body

NameTypeDescription
role_id*
string (UUID)Role to assign

Response Fields

NameTypeDescription
id*
string (UUID)Assignment ID
role_id*
string (UUID)Role ID
name*
stringRole name
is_system*
booleanWhether 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"
}
DELETE/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

NameTypeDescription
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
GET/v1/auth/companies/{company_id}/members/{user_id}/permissions

List Member Permissions

List the direct permission grants on a company member (paginated).

Bearer token required.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID
user_id*
string (UUID)Member user ID

Query Parameters

NameTypeDescription
page
integerPage number (min 1)Default: 1
limit
integerItems 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
}
POST/v1/auth/companies/{company_id}/members/{user_id}/permissions

Add Member Permission

Grant a direct permission to a company member.

Bearer token required.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID
user_id*
string (UUID)Member user ID

Request Body

NameTypeDescription
permission_id*
string (UUID)Permission to grant
effect
stringAllow or denyDefault: allow
resource
string | nullResource path the grant applies to
resource_id
string (UUID) | nullSpecific resource instance ID

Response Fields

NameTypeDescription
id*
string (UUID)Grant ID
permission_id*
string (UUID)Permission ID
name*
stringPermission name
resource*
stringResource the grant applies to
effect*
stringallow or deny
is_system*
booleanWhether 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"
}
DELETE/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

NameTypeDescription
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
GET/v1/auth/companies/{company_id}/members/{user_id}/services

List 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

NameTypeDescription
company_id*
string (UUID)Company ID
user_id*
string (UUID)Member user ID

Response Fields

NameTypeDescription
id*
string (UUID)Service-access grant ID
service_slug*
stringService slug
service_name*
stringService name
source
string | nullWhere 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"
  }
]
POST/v1/auth/companies/{company_id}/members/{user_id}/services

Grant Member Service

Grant a member access to a service by slug.

Bearer token required.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID
user_id*
string (UUID)Member user ID

Request Body

NameTypeDescription
service_slug*
stringService slug to grant

Response Fields

NameTypeDescription
id*
string (UUID)Service-access grant ID
service_slug*
stringService slug
service_name*
stringService 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"
}
DELETE/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

NameTypeDescription
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 Content

Roles & 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.

GET/v1/auth/companies/{company_id}/roles

List Roles

List a company's roles, including built-in system roles.

Bearer token required.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID

Response Fields

NameTypeDescription
id*
string (UUID)Role ID
name*
stringRole name
description
string | nullRole description
is_system*
booleanWhether it is a built-in role
company_id
string (UUID) | nullOwning 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
  }
]
GET/v1/auth/companies/{company_id}/roles/manageable

List 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

NameTypeDescription
company_id*
string (UUID)Company ID

Response Fields

NameTypeDescription
id*
string (UUID)Role ID
name*
stringRole name
description
string | nullRole description
is_system*
booleanWhether 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"
  }
]
POST/v1/auth/companies/{company_id}/roles

Create Role

Create a custom role in a company.

Bearer token required.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID

Request Body

NameTypeDescription
name*
stringRole name (1–50 chars)
description
string | nullRole description

Response Fields

NameTypeDescription
id*
string (UUID)Role ID
name*
stringRole name
description
string | nullRole description
is_system*
booleanAlways false for custom roles
company_id
string (UUID) | nullOwning 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"
}
PATCH/v1/auth/companies/{company_id}/roles/{role_id}

Update Role

Update a custom role's name and/or description.

Bearer token required.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID
role_id*
string (UUID)Role ID

Request Body

NameTypeDescription
name
string | nullNew name (1–50 chars)
description
string | nullNew description

Response Fields

NameTypeDescription
id*
string (UUID)Role ID
name*
stringRole name
description
string | nullRole description
is_system*
booleanWhether it is a built-in role
company_id
string (UUID) | nullOwning 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"
}
DELETE/v1/auth/companies/{company_id}/roles/{role_id}

Delete Role

Delete a custom role.

Bearer token required.

Path Parameters

NameTypeDescription
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
GET/v1/auth/companies/{company_id}/roles/{role_id}/services

List Role Services

List the services attached to a role.

Bearer token required.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID
role_id*
string (UUID)Role ID

Response Fields

NameTypeDescription
id*
string (UUID)Role-service grant ID
service_slug*
stringService slug
service_name*
stringService 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"
  }
]
POST/v1/auth/companies/{company_id}/roles/{role_id}/services

Add Role Service

Attach a service to a role so members with the role inherit its access.

Bearer token required.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID
role_id*
string (UUID)Role ID

Request Body

NameTypeDescription
service_slug*
stringService slug to attach

Response Fields

NameTypeDescription
id*
string (UUID)Role-service grant ID
service_slug*
stringService slug
service_name*
stringService 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"
}
DELETE/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

NameTypeDescription
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
GET/v1/auth/roles/{role_id}/permissions

List Role Permissions

List the permissions granted directly to a role.

Bearer token required.

Path Parameters

NameTypeDescription
role_id*
string (UUID)Role ID

Response Fields

NameTypeDescription
items*
GrantedPermission[]Direct permission grants
total*
integerTotal 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
}
POST/v1/auth/roles/{role_id}/permissions

Add Role Permission

Grant a permission to a role.

Bearer token required.

Path Parameters

NameTypeDescription
role_id*
string (UUID)Role ID

Request Body

NameTypeDescription
permission_id*
string (UUID)Permission to grant
effect
stringallow or denyDefault: allow
resource
string | nullResource path the grant applies to
resource_id
string (UUID) | nullSpecific resource instance ID

Response Fields

NameTypeDescription
id*
string (UUID)Grant ID
permission_id*
string (UUID)Permission ID
name*
stringPermission name
resource*
stringResource the grant applies to
effect*
stringallow or deny
is_system*
booleanWhether 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"
}
DELETE/v1/auth/roles/{role_id}/permissions/{pp_id}

Remove Role Permission

Revoke a permission from a role.

Bearer token required.

Path Parameters

NameTypeDescription
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 Content

API Keys

Create, list, update, and delete machine API keys and manage each key's permissions, role assignments, and service access.

POST/v1/auth/api-keys

Create 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

NameTypeDescription
company_id*
string (UUID)Owning company
name*
stringHuman-readable key name
service_slugs*
array<string>Services the key may access
expires_at
string (date-time) | nullOptional expiry timestamp

Response Fields

NameTypeDescription
id*
string (UUID)API key ID
client_id*
stringPublic client identifier (ek_...)
client_secret*
stringSecret (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..."
}
GET/v1/auth/companies/{company_id}/api-keys

List API Keys

List a company's API keys (paginated). Secrets are never returned.

Bearer token required.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID

Query Parameters

NameTypeDescription
page
integerPage number (min 1)Default: 1
limit
integerItems 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
}
PATCH/v1/auth/api-keys/{key_id}

Update API Key

Update an API key's name and/or expiry.

Bearer token required.

Path Parameters

NameTypeDescription
key_id*
string (UUID)API key ID

Request Body

NameTypeDescription
name
string | nullNew name (1–100 chars)
expires_at
string (date-time) | nullNew expiry timestamp

Response Fields

NameTypeDescription
id*
string (UUID)API key ID
name*
stringKey name
client_id
string | nullPublic client identifier
expires_at
string (date-time) | nullExpiry
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"
}
DELETE/v1/auth/api-keys/{key_id}

Delete API Key

Permanently revoke an API key.

Bearer token required.

Path Parameters

NameTypeDescription
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
GET/v1/auth/api-keys/{key_id}/permissions

List API Key Permissions

List the direct permission grants on an API key (paginated).

Bearer token required.

Path Parameters

NameTypeDescription
key_id*
string (UUID)API key ID

Query Parameters

NameTypeDescription
page
integerPage number (min 1)Default: 1
limit
integerItems 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
}
POST/v1/auth/api-keys/{key_id}/permissions

Add API Key Permission

Grant a direct permission to an API key.

Bearer token required.

Path Parameters

NameTypeDescription
key_id*
string (UUID)API key ID

Request Body

NameTypeDescription
permission_id*
string (UUID)Permission to grant
effect
stringallow or denyDefault: allow
resource
string | nullResource path the grant applies to
resource_id
string (UUID) | nullSpecific resource instance ID

Response Fields

NameTypeDescription
id*
string (UUID)Grant ID
permission_id*
string (UUID)Permission ID
name*
stringPermission name
resource*
stringResource the grant applies to
effect*
stringallow or deny
is_system*
booleanWhether 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"
}
DELETE/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

NameTypeDescription
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
GET/v1/auth/api-keys/{key_id}/roles

List API Key Roles

List the roles assigned to an API key.

Bearer token required.

Path Parameters

NameTypeDescription
key_id*
string (UUID)API key ID

Response Fields

NameTypeDescription
id*
string (UUID)Assignment ID
role_id*
string (UUID)Role ID
name*
stringRole name
is_system*
booleanWhether 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"
  }
]
POST/v1/auth/api-keys/{key_id}/roles

Assign API Key Role

Assign a role to an API key.

Bearer token required.

Path Parameters

NameTypeDescription
key_id*
string (UUID)API key ID

Request Body

NameTypeDescription
role_id*
string (UUID)Role to assign

Response Fields

NameTypeDescription
id*
string (UUID)Assignment ID
role_id*
string (UUID)Role ID
name*
stringRole name
is_system*
booleanWhether 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"
}
DELETE/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

NameTypeDescription
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
GET/v1/auth/api-keys/{key_id}/services

List API Key Services

List the services an API key has access to.

Bearer token required.

Path Parameters

NameTypeDescription
key_id*
string (UUID)API key ID

Response Fields

NameTypeDescription
id*
string (UUID)Service-access grant ID
service_slug*
stringService slug
service_name*
stringService 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"
  }
]
POST/v1/auth/api-keys/{key_id}/services

Grant API Key Service

Grant an API key access to a service by slug.

Bearer token required.

Path Parameters

NameTypeDescription
key_id*
string (UUID)API key ID

Request Body

NameTypeDescription
service_slug*
stringService slug to grant

Response Fields

NameTypeDescription
id*
string (UUID)Service-access grant ID
service_slug*
stringService slug
service_name*
stringService 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"
}
DELETE/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

NameTypeDescription
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 Content

Agent Identities

Create and manage agent principals plus their permissions, roles, service access, and the human/API-key principals linked to act as them.

POST/v1/auth/companies/{company_id}/agents

Create 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

NameTypeDescription
company_id*
string (UUID)Company ID

Request Body

NameTypeDescription
name*
stringAgent name (1–200 chars)
description
string | nullAgent description
agent_type
"service" | "personal"Agent type, fixed at creation (default service)
owner_member_id
string (UUID) | nullPersonal 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

NameTypeDescription
id*
string (UUID)Agent ID
company_id*
string (UUID)Owning company
name*
stringAgent name
description*
string | nullAgent description
is_active*
booleanWhether the agent is active
agent_type*
"service" | "personal"Agent type, fixed at creation
owner*
object | nullA personal agent's owner (member_id, principal_id, name, email, is_active); null for a service agent
is_default*
booleantrue when this personal agent is its owner's default for new conversations
show_sent_by_marker*
booleantrue 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"
}
GET/v1/auth/companies/{company_id}/agents

List Agents

List a company's agents (paginated).

Bearer token required.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID

Query Parameters

NameTypeDescription
page
integerPage number (min 1)Default: 1
limit
integerItems per page (1–100)Default: 50
grantable
booleantrue 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
}
GET/v1/auth/agents/{agent_id}

Get Agent

Retrieve a single agent by ID.

Bearer token required.

Path Parameters

NameTypeDescription
agent_id*
string (UUID)Agent ID

Response Fields

NameTypeDescription
id*
string (UUID)Agent ID
company_id*
string (UUID)Owning company
name*
stringAgent name
description*
string | nullAgent description
is_active*
booleanWhether the agent is active
agent_type*
"service" | "personal"Agent type, fixed at creation
owner*
object | nullA personal agent's owner (member_id, principal_id, name, email, is_active); null for a service agent
is_default*
booleantrue when this personal agent is its owner's default for new conversations
show_sent_by_marker*
booleantrue 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"
}
PATCH/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

NameTypeDescription
agent_id*
string (UUID)Agent ID

Request Body

NameTypeDescription
is_active
boolean | nullActivate or deactivate
is_default
boolean | nullPersonal 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 | nullPersonal 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"
}
DELETE/v1/auth/agents/{agent_id}

Delete Agent

Delete an agent identity.

Bearer token required.

Path Parameters

NameTypeDescription
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
GET/v1/auth/agents/{agent_id}/permissions

List Agent Permissions

List the direct permission grants on an agent (paginated).

Bearer token required.

Path Parameters

NameTypeDescription
agent_id*
string (UUID)Agent ID

Query Parameters

NameTypeDescription
page
integerPage number (min 1)Default: 1
limit
integerItems 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
}
POST/v1/auth/agents/{agent_id}/permissions

Add Agent Permission

Grant a direct permission to an agent.

Bearer token required.

Path Parameters

NameTypeDescription
agent_id*
string (UUID)Agent ID

Request Body

NameTypeDescription
permission_id*
string (UUID)Permission to grant
effect
stringallow or denyDefault: allow
resource
string | nullResource path the grant applies to
resource_id
string (UUID) | nullSpecific resource instance ID

Response Fields

NameTypeDescription
id*
string (UUID)Grant ID
permission_id*
string (UUID)Permission ID
name*
stringPermission name
resource*
stringResource the grant applies to
effect*
stringallow or deny
is_system*
booleanWhether 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"
}
DELETE/v1/auth/agents/{agent_id}/permissions/{pp_id}

Remove Agent Permission

Revoke a direct permission grant from an agent.

Bearer token required.

Path Parameters

NameTypeDescription
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
GET/v1/auth/agents/{agent_id}/roles

List Agent Roles

List the roles assigned to an agent.

Bearer token required.

Path Parameters

NameTypeDescription
agent_id*
string (UUID)Agent ID

Response Fields

NameTypeDescription
id*
string (UUID)Assignment ID
role_id*
string (UUID)Role ID
name*
stringRole name
is_system*
booleanWhether 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"
  }
]
POST/v1/auth/agents/{agent_id}/roles

Assign Agent Role

Assign a role to an agent.

Bearer token required.

Path Parameters

NameTypeDescription
agent_id*
string (UUID)Agent ID

Request Body

NameTypeDescription
role_id*
string (UUID)Role to assign

Response Fields

NameTypeDescription
id*
string (UUID)Assignment ID
role_id*
string (UUID)Role ID
name*
stringRole name
is_system*
booleanWhether 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"
}
DELETE/v1/auth/agents/{agent_id}/roles/{pr_id}

Remove Agent Role

Remove a role assignment from an agent.

Bearer token required.

Path Parameters

NameTypeDescription
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
GET/v1/auth/agents/{agent_id}/services

List Agent Services

List the services an agent has access to.

Bearer token required.

Path Parameters

NameTypeDescription
agent_id*
string (UUID)Agent ID

Response Fields

NameTypeDescription
id*
string (UUID)Service-access grant ID
service_slug*
stringService slug
service_name*
stringService 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"
  }
]
POST/v1/auth/agents/{agent_id}/services

Grant Agent Service

Grant an agent access to a service by slug.

Bearer token required.

Path Parameters

NameTypeDescription
agent_id*
string (UUID)Agent ID

Request Body

NameTypeDescription
service_slug*
stringService slug to grant

Response Fields

NameTypeDescription
id*
string (UUID)Service-access grant ID
service_slug*
stringService slug
service_name*
stringService 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"
}
DELETE/v1/auth/agents/{agent_id}/services/{access_id}

Revoke Agent Service

Revoke an agent's access to a service.

Bearer token required.

Path Parameters

NameTypeDescription
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
GET/v1/auth/agents/{agent_id}/principals

List Agent Principals

List the principals (members or API keys) linked to act as the agent (paginated).

Bearer token required.

Path Parameters

NameTypeDescription
agent_id*
string (UUID)Agent ID

Query Parameters

NameTypeDescription
page
integerPage number (min 1)Default: 1
limit
integerItems 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
}
POST/v1/auth/agents/{agent_id}/principals

Add Agent Principal

Authorize a member or API key to act as the agent.

Bearer token required.

Path Parameters

NameTypeDescription
agent_id*
string (UUID)Agent ID

Request Body

NameTypeDescription
principal_type*
stringPrincipal type ("member" or "api_key")
principal_id*
string (UUID)Principal to authorize

Response Fields

NameTypeDescription
id*
string (UUID)Link ID
principal_type*
stringPrincipal type
principal_id*
string (UUID)Principal ID
principal_label*
stringHuman-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"
}
DELETE/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

NameTypeDescription
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 Content

Service 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.

GET/v1/auth/services

List Services

Public catalog of global services available on the platform.

No authentication required.

Query Parameters

NameTypeDescription
include_hidden
booleanInclude hidden servicesDefault: false

Response Fields

NameTypeDescription
id*
string (UUID)Service ID
name*
stringService name
slug*
stringService slug
hidden*
booleanWhether the service is hidden
required
booleanWhether the service is mandatory
self_service
booleanWhether admins can self-enable
stage
stringLifecycle stage (e.g. ga)
curl https://platform.ergondata.ai/v1/auth/services

Response

200 OK
[
  {
    "id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
    "name": "Workflows",
    "slug": "workflows",
    "hidden": false,
    "required": false,
    "self_service": true,
    "stage": "ga"
  }
]
GET/v1/auth/services/{service_slug}/permissions

List Service Permissions

List the permissions defined by a service.

Bearer token required.

Path Parameters

NameTypeDescription
service_slug*
stringService slug

Response Fields

NameTypeDescription
id*
string (UUID)Permission ID
name*
stringPermission name
is_system*
booleanWhether it is a built-in permission
description
string | nullPermission 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"
  }
]
GET/v1/auth/services/{service_slug}/resource-types

List Service Resource Types

Return the resource-type tree and associated permissions for a service.

Bearer token required.

Path Parameters

NameTypeDescription
service_slug*
stringService 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": []
}
GET/v1/auth/companies/{company_id}/available-services

List Available Services

List services an admin can enable for the company (global non-hidden + tenant services).

Bearer token required.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID

Response Fields

NameTypeDescription
id*
string (UUID)Service ID
name*
stringService name
slug*
stringService slug
hidden*
booleanWhether 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"
  }
]
GET/v1/auth/companies/{company_id}/services

List Company Services

List the services currently enabled for a company.

Bearer token required.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID

Response Fields

NameTypeDescription
id*
string (UUID)Service ID
name*
stringService name
slug*
stringService slug
hidden*
booleanWhether 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"
  }
]
GET/v1/auth/companies/{company_id}/permissions

List 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

NameTypeDescription
company_id*
string (UUID)Company ID

Response Fields

NameTypeDescription
id*
string (UUID)Permission ID
name*
stringPermission name
is_system*
booleanWhether 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"
  }
]
GET/v1/auth/companies/{company_id}/iam-grantable-permissions

List IAM Grantable Permissions

Return the narrowed permission catalog for IAM-owned grant surfaces.

Bearer token required.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID

Response Fields

NameTypeDescription
id*
string (UUID)Permission ID
name*
stringPermission name
is_system*
booleanWhether 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
  }
]
POST/v1/auth/companies/{company_id}/company-services/{service_id}

Enable Company Service

Enable a service for a company.

Bearer token required.

Path Parameters

NameTypeDescription
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
}
DELETE/v1/auth/companies/{company_id}/company-services/{service_id}

Disable Company Service

Disable a service for a company.

Bearer token required.

Path Parameters

NameTypeDescription
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
GET/v1/auth/companies/{company_id}/feature-flags

List Feature Flags

List the feature flags resolved for a company.

Bearer token required.

Path Parameters

NameTypeDescription
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
}
PUT/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

NameTypeDescription
company_id*
string (UUID)Company ID
key*
stringFeature flag key

Request Body

NameTypeDescription
value*
boolean | string | numberNew 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
}
GET/v1/auth/companies/{company_id}/services/{service_slug}/access

List Service Access

List which principals have access to a given service in a company (paginated).

Bearer token required.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID
service_slug*
stringService slug

Query Parameters

NameTypeDescription
page
integerPage number (min 1)Default: 1
limit
integerItems 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
}
POST/v1/auth/companies/{company_id}/services/{service_slug}/access

Grant Service Access

Grant a principal access to a service. The principal is identified via query parameters.

Bearer token required.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID
service_slug*
stringService slug

Query Parameters

NameTypeDescription
principal_type*
stringPrincipal type ("member", "api_key", or "agent")
principal_id*
stringPrincipal to grant

Response Fields

NameTypeDescription
id*
string (UUID)Service-access grant ID
principal_type*
stringPrincipal type
principal_id*
string (UUID)Principal ID
principal_label*
stringHuman-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"
}
DELETE/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

NameTypeDescription
company_id*
string (UUID)Company ID
service_slug*
stringService 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
GET/v1/auth/companies/{company_id}/conversation-agents

List 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

NameTypeDescription
company_id*
string (UUID)Company ID

Query Parameters

NameTypeDescription
page
integerPage number (min 1)Default: 1
limit
integerItems 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
}
GET/v1/auth/companies/{company_id}/conversation-principals

List Conversation Principals

List principals in a company that can participate in conversations.

Bearer token required.

Path Parameters

NameTypeDescription
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.

GET/v1/auth/companies/{company_id}/grants

List 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

NameTypeDescription
company_id*
string (UUID)Company ID

Query Parameters

NameTypeDescription
page
integerPage number (min 1)Default: 1
limit
integerItems 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
}
GET/v1/auth/companies/{company_id}/grants/grouped

List 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

NameTypeDescription
company_id*
string (UUID)Company ID

Query Parameters

NameTypeDescription
page
integerPage number (min 1)Default: 1
limit
integerItems per page (1–100)Default: 25
q
string | nullSearch query (max 200 chars)
include_grants
booleanfalse 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
}
GET/v1/auth/companies/{company_id}/grants/grouped/{principal_type}/{principal_id}/grants

List 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

NameTypeDescription
company_id*
string (UUID)Company ID
principal_type*
stringmember, api_key, agent, or role
principal_id*
string (UUID)The row's principal_id (company member, API key, agent or role ID)

Query Parameters

NameTypeDescription
page
integerPage number (min 1)Default: 1
limit
integerGrants per page (1–100)Default: 50
q
string | nullSame 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
}
POST/v1/auth/companies/{company_id}/grants/batch

Create 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

NameTypeDescription
company_id*
string (UUID)Company ID

Request Body

NameTypeDescription
operations*
arrayGrouped operations whose full Cartesian expansion is at most 200 grants

Response Fields

NameTypeDescription
results*
arrayOutcomes ordered by operation, resource, then permission ID
summary*
objectcreated, 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}
}
POST/v1/auth/companies/{company_id}/roles/access/grants/batch

Create 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

NameTypeDescription
company_id*
string (UUID)Company ID

Request Body

NameTypeDescription
operations*
arrayBatchGrantOperation[]; same grouped shape as Create Org Grants Batch

Response Fields

NameTypeDescription
results*
arrayOrdered BatchGrantResult[] partial outcomes
summary*
objectcreated, 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}
}
POST/v1/auth/companies/{company_id}/teams/access/grants/batch

Create 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

NameTypeDescription
company_id*
string (UUID)Company ID

Request Body

NameTypeDescription
operations*
arrayBatchGrantOperation[]; same grouped shape as Create Org Grants Batch

Response Fields

NameTypeDescription
results*
arrayOrdered BatchGrantResult[] partial outcomes
summary*
objectcreated, 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}
}
POST/v1/auth/companies/{company_id}/api-keys/access/grants/batch

Create 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

NameTypeDescription
company_id*
string (UUID)Company ID

Request Body

NameTypeDescription
operations*
arrayBatchGrantOperation[]; same grouped shape as Create Org Grants Batch

Response Fields

NameTypeDescription
results*
arrayOrdered BatchGrantResult[] partial outcomes
summary*
objectcreated, 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}
}
POST/v1/auth/companies/{company_id}/agents/access/grants/batch

Create 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

NameTypeDescription
company_id*
string (UUID)Company ID

Request Body

NameTypeDescription
operations*
arrayBatchGrantOperation[]; same grouped shape as Create Org Grants Batch

Response Fields

NameTypeDescription
results*
arrayOrdered BatchGrantResult[] partial outcomes
summary*
objectcreated, 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}
}
POST/v1/auth/companies/{company_id}/members/access/grants/batch

Create 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

NameTypeDescription
company_id*
string (UUID)Company ID

Request Body

NameTypeDescription
operations*
arrayBatchGrantOperation[]; same grouped shape as Create Org Grants Batch

Response Fields

NameTypeDescription
results*
arrayOrdered BatchGrantResult[] partial outcomes
summary*
objectcreated, 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}
}
DELETE/v1/auth/companies/{company_id}/grants/{grant_id}

Delete Org Grant

Revoke a specific permission grant in a company.

Bearer token required.

Path Parameters

NameTypeDescription
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
GET/v1/auth/companies/{company_id}/service-access

List Org Service Access

List every service-access entitlement in a company across all principals (paginated).

Bearer token required.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID

Query Parameters

NameTypeDescription
page
integerPage number (min 1)Default: 1
limit
integerItems per page (1–100)Default: 50
q
string | nullSearch 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
}
DELETE/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

NameTypeDescription
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 Content

Invitations

Recipient-facing invitation flow plus resending pending company invitations.

GET/v1/auth/invitations/mine

List My Invitations

Return all pending, non-expired invitations addressed to the logged-in user's email.

Bearer token required.

Response Fields

NameTypeDescription
token*
stringInvitation token
company_name*
stringInviting company name
company_slug*
stringInviting company slug
inviter_name*
string | nullWho sent the invite
role
string | nullProposed 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"
  }
]
GET/v1/auth/invitations/{token}

Get Invitation

Look up invitation details by token, including whether the recipient must register first.

No authentication required.

Path Parameters

NameTypeDescription
token*
stringInvitation token

Response Fields

NameTypeDescription
id*
string (UUID)Invitation ID
email*
stringInvited email
company_name*
stringInviting company name
company_slug*
stringInviting company slug
needs_registration*
booleanWhether the recipient must register first
roles
array<string>Proposed roles
locale_hint
string | nullLocale 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"
}
POST/v1/auth/invitations/{token}/accept

Accept 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

NameTypeDescription
token*
stringInvitation 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"
}
POST/v1/auth/companies/{company_id}/invitations/{invitation_id}/resend

Resend 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

NameTypeDescription
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.

POST/v1/auth/check-permission

Check Permission

Evaluate whether the authenticated caller has a given permission on a resource.

Bearer token required.

Request Body

NameTypeDescription
company_id*
stringCompany context to evaluate in
action*
stringPermission/action to check
resource*
stringResource the action targets

Response Fields

NameTypeDescription
allowed*
booleanWhether the action is permitted
reason
string | nullExplanation 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
}
POST/v1/auth/check-permissions

Batch Check Permissions

Evaluate a single action against multiple candidate resources in one call.

Bearer token required.

Request Body

NameTypeDescription
company_id*
stringCompany context to evaluate in
action*
stringPermission/action to check
resources*
array<string>Resources to evaluate the action against

Response Fields

NameTypeDescription
results*
object<string, boolean>Map of resource → whether allowed
reason
string | nullExplanation 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
}
POST/v1/auth/check-capabilities

Check Capabilities

Evaluate multiple actions against multiple resources in one request.

Bearer token required.

Request Body

NameTypeDescription
company_id*
stringCompany context to evaluate in
actions*
array<string>Permissions/actions to check
resources*
array<string>Resources to evaluate each action against

Response Fields

NameTypeDescription
results*
object<string, object<string, boolean>>Map of resource → action → whether allowed
reason
string | nullExplanation 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
}
POST/v1/auth/check-scopes

Check 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

NameTypeDescription
company_id*
stringCompany context to evaluate in
actions*
array<string>Permissions/actions to classify
resources*
array<string>Root resources to classify each action under

Response Fields

NameTypeDescription
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 | nullExplanation 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.

GET/v1/auth/companies/{company_id}/activity

List Company Activity

List audit-log events for a company, optionally filtered by event type (paginated).

Bearer token required.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID

Query Parameters

NameTypeDescription
event_type
string | nullFilter by event type
page
integerPage number (min 1)Default: 1
limit
integerItems per page (1–100)Default: 50

Response Fields

NameTypeDescription
items*
arrayActivity events
total*
integerTotal events
page*
integerCurrent page
limit*
integerPage 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
}
GET/v1/auth/activity/{event_id}

Get Activity Event

Retrieve a single audit-log event by ID.

Bearer token required.

Path Parameters

NameTypeDescription
event_id*
stringEvent ID

Response Fields

NameTypeDescription
id*
string (UUID)Event ID
event_type*
stringEvent type
actor_label
string | nullActor display label
actor_type
string | nullActor type
data
object | nullEvent 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"
}
GET/v1/auth/event-types

List 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.

GET/v1/companies/{company_id}/ip-allowlists

List IP Allowlists

List a company's IP allowlists and their CIDR entries.

Bearer token required.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID

Response Fields

NameTypeDescription
id*
string (UUID)Allowlist ID
company_id*
string (UUID)Owning company
slug*
stringAllowlist slug
name*
stringAllowlist name
entries*
arrayCIDR 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"
  }
]
POST/v1/companies/{company_id}/ip-allowlists

Create IP Allowlist

Create an IP allowlist with one or more CIDR entries.

Bearer token required.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID

Request Body

NameTypeDescription
slug*
stringAllowlist slug (1–100 chars)
name*
stringAllowlist name (min 1 char)
entries
arrayCIDR 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"
}
PATCH/v1/ip-allowlists/{allowlist_id}

Update IP Allowlist

Update an allowlist's name and/or replace its CIDR entries.

Bearer token required.

Path Parameters

NameTypeDescription
allowlist_id*
string (UUID)Allowlist ID

Request Body

NameTypeDescription
name
string | nullNew name
entries
array | nullReplacement 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"
}
DELETE/v1/ip-allowlists/{allowlist_id}

Delete IP Allowlist

Delete an IP allowlist.

Bearer token required.

Path Parameters

NameTypeDescription
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
GET/v1/companies/{company_id}/ip-allowlist-assignments

List IP Allowlist Assignments

List which principals are bound to which IP allowlists in a company.

Bearer token required.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID

Response Fields

NameTypeDescription
principal_id*
string (UUID)Principal ID
allowlists*
arrayAllowlists 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"
      }
    ]
  }
]
PUT/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

NameTypeDescription
company_id*
string (UUID)Company ID
principal_id*
string (UUID)Principal ID

Request Body

NameTypeDescription
allowlist_ids*
array<string (UUID)>Allowlist IDs to bind (empty array clears)

Response Fields

NameTypeDescription
principal_id*
string (UUID)Principal ID
allowlists*
arrayAllowlists 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"
    }
  ]
}
DELETE/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

NameTypeDescription
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 Content

Working Hours

Define weekly working-hours schedules, assign them to principals (routing-only or platform-access enforcement), and read the caller's effective hours.

GET/v1/companies/{company_id}/working-hours

List Working Hours

List a company's working-hours configurations and their weekly slots.

Bearer token required.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID

Response Fields

NameTypeDescription
id*
string (UUID)Config ID
company_id*
string (UUID)Owning company
slug*
stringConfig slug
name*
stringConfig name
timezone*
stringIANA timezone
slots*
arrayWeekly 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"
  }
]
POST/v1/companies/{company_id}/working-hours

Create Working Hours

Create a working-hours configuration with weekly slots.

Bearer token required.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID

Request Body

NameTypeDescription
slug*
stringConfig slug (1–100 chars)
name*
stringConfig name (min 1 char)
timezone
stringIANA timezone (1–50 chars)Default: UTC
slots
arrayWeekly 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"
}
PATCH/v1/working-hours/{config_id}

Update Working Hours

Update a working-hours config's name, timezone, and/or slots.

Bearer token required.

Path Parameters

NameTypeDescription
config_id*
string (UUID)Config ID

Request Body

NameTypeDescription
name
string | nullNew name
timezone
string | nullNew IANA timezone
slots
array | nullReplacement 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"
}
DELETE/v1/working-hours/{config_id}

Delete Working Hours

Delete a working-hours configuration.

Bearer token required.

Path Parameters

NameTypeDescription
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
GET/v1/working-hours/granted

List 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" }
    ]
  }
]
GET/v1/companies/{company_id}/working-hours-assignments

List Working Hours Assignments

List which working-hours configs are assigned to which principals in a company.

Bearer token required.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID

Response Fields

NameTypeDescription
principal_id*
string (UUID)Principal ID
configs*
arrayAssigned 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": []
  }
]
PUT/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

NameTypeDescription
company_id*
string (UUID)Company ID
principal_id*
string (UUID)Principal ID

Request Body

NameTypeDescription
config_ids
array<string (UUID)> | nullConfig IDs to assign (routing-only enforcement)
assignments
array | nullPer-config assignments with enforcement mode

Response Fields

NameTypeDescription
principal_id*
string (UUID)Principal ID
configs*
arrayConfigs 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": []
}
DELETE/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

NameTypeDescription
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 Content

Status Types & Presence

Define company status types (e.g. available, busy) and set the current availability status of principals.

GET/v1/companies/{company_id}/status-types

List Status Types

List a company's principal status types.

Bearer token required.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID

Response Fields

NameTypeDescription
id*
string (UUID)Status type ID
company_id*
string (UUID)Owning company
slug*
stringStatus type slug
name*
stringStatus type name
color*
string | nullHex color
icon*
string | nullIcon name
is_available*
booleanCounts as available
is_default*
booleanDefault for new principals
position*
integerSort 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"
  }
]
POST/v1/companies/{company_id}/status-types

Create Status Type

Create a principal status type.

Bearer token required.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID

Request Body

NameTypeDescription
slug*
stringStatus type slug (1–50 chars)
name*
stringStatus type name (1–200 chars)
color
string | nullHex color (max 7 chars)
icon
string | nullIcon name (max 50 chars)
is_available
booleanWhether it counts as availableDefault: false
is_default
booleanWhether it is the defaultDefault: false
position
integerSort 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"
}
PATCH/v1/status-types/{status_type_id}

Update Status Type

Update a status type's attributes.

Bearer token required.

Path Parameters

NameTypeDescription
status_type_id*
string (UUID)Status type ID

Request Body

NameTypeDescription
name
string | nullNew name (1–200 chars)
color
string | nullNew hex color
icon
string | nullNew icon name
is_available
boolean | nullCounts as available
is_default
boolean | nullIs the default
position
integer | nullSort 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"
}
DELETE/v1/status-types/{status_type_id}

Delete Status Type

Delete a status type.

Bearer token required.

Path Parameters

NameTypeDescription
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
GET/v1/companies/{company_id}/principal-statuses

List Principal Statuses

List the current availability status of every principal in a company.

Bearer token required.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID

Response Fields

NameTypeDescription
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 | nullStatus type name
custom_message*
string | nullCustom status message
is_available
boolean | nullWhether 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"
  }
]
GET/v1/principal-statuses/me

Get 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

NameTypeDescription
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 | nullApplied status slug
is_available*
boolean | nullWhether this status permits new assignments
custom_message*
string | nullOptional 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"
}
PUT/v1/principal-statuses/me

Set 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

NameTypeDescription
status_type_id*
string (UUID)Status type to apply
custom_message
string | nullOptional custom status message

Response Fields

NameTypeDescription
id*
string (UUID)Status record ID
principal_id*
string (UUID)Principal ID
status_type_id*
string (UUID)Applied status type
custom_message*
string | nullCustom 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"
}
PUT/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

NameTypeDescription
principal_id*
string (UUID)Principal ID

Request Body

NameTypeDescription
status_type_id*
string (UUID)Status type to apply
custom_message
string | nullOptional custom status message

Response Fields

NameTypeDescription
id*
string (UUID)Status record ID
principal_id*
string (UUID)Principal ID
status_type_id*
string (UUID)Applied status type
custom_message*
string | nullCustom 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:*.

GET/v1/auth/companies/{company_id}/teams

List Teams

List all non-deleted teams in a company, each with its current member count.

Bearer token. Requires iam:company:teams:view.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID

Response Fields

NameTypeDescription
id*
string (UUID)Team ID
company_id*
string (UUID)Owning company
name*
stringTeam name
description*
string | nullOptional description
parent_team_id*
string (UUID) | nullParent team, if nested
principal_id*
string (UUID) | nullThe team's principal
member_count*
integerNumber 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"
  }
]
GET/v1/auth/companies/{company_id}/teams/manageable

List 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

NameTypeDescription
company_id*
string (UUID)Company ID

Response Fields

NameTypeDescription
id*
string (UUID)Team ID
company_id*
string (UUID)Owning company
name*
stringTeam name
description*
string | nullOptional description
parent_team_id*
string (UUID) | nullParent team, if nested
principal_id*
string (UUID) | nullThe team's principal
member_count*
integerNumber 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"
  }
]
POST/v1/auth/companies/{company_id}/teams

Create 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

NameTypeDescription
company_id*
string (UUID)Company ID

Request Body

NameTypeDescription
name*
stringTeam name
description
string | nullOptional description
parent_team_id
string (UUID) | nullParent team for nesting

Response Fields

NameTypeDescription
id*
string (UUID)New team ID
principal_id*
string (UUID) | nullThe team's principal
name*
stringTeam name
member_count*
integerMember 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"
}
PATCH/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

NameTypeDescription
team_id*
string (UUID)Team ID

Request Body

NameTypeDescription
name
string | nullNew name
description
string | nullNew description
parent_team_id
string (UUID) | nullNew parent team (null detaches)

Response Fields

NameTypeDescription
id*
string (UUID)Team ID
name*
stringUpdated name
parent_team_id*
string (UUID) | nullUpdated 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"
}
DELETE/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

NameTypeDescription
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
GET/v1/auth/teams/{team_id}/members

List Team Members

List the principals that belong to a team.

Bearer token. Requires iam:company:teams:view.

Path Parameters

NameTypeDescription
team_id*
string (UUID)Team ID

Response Fields

NameTypeDescription
id*
string (UUID)Membership row ID
member_principal_id*
string (UUID)The member principal
principal_type*
stringmember | agent | api_key | team
label*
string | nullDisplay 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"
  }
]
POST/v1/auth/teams/{team_id}/members

Add 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

NameTypeDescription
team_id*
string (UUID)Team ID

Request Body

NameTypeDescription
member_principal_id*
string (UUID)Principal to add

Response Fields

NameTypeDescription
id*
string (UUID)Membership row ID
member_principal_id*
string (UUID)Added principal
principal_type*
stringKind 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"
}
DELETE/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

NameTypeDescription
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
GET/v1/auth/teams/{team_id}/roles

List Team Roles

List roles assigned to the team principal. Members inherit these roles.

Bearer token. Requires iam:company:teams:view.

Path Parameters

NameTypeDescription
team_id*
string (UUID)Team ID

Response Fields

NameTypeDescription
id*
string (UUID)Assignment row ID
role_id*
string (UUID)Assigned role
name*
stringRole name
is_system*
booleanWhether 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"
  }
]
POST/v1/auth/teams/{team_id}/roles

Assign 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

NameTypeDescription
team_id*
string (UUID)Team ID

Request Body

NameTypeDescription
role_id*
string (UUID)Role to assign

Response Fields

NameTypeDescription
id*
string (UUID)Assignment row ID
role_id*
string (UUID)Assigned role
name*
stringRole 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"
}
DELETE/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

NameTypeDescription
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
GET/v1/auth/teams/{team_id}/permissions

List Team Permission Grants

List permission grants attached directly to the team principal.

Bearer token. Requires iam:company:teams:view.

Path Parameters

NameTypeDescription
team_id*
string (UUID)Team ID

Response Fields

NameTypeDescription
items*
GrantedPermission[]Direct permission grants
total*
integerTotal 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
}
POST/v1/auth/teams/{team_id}/permissions

Grant 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

NameTypeDescription
team_id*
string (UUID)Team ID

Request Body

NameTypeDescription
permission_id*
string (UUID)Permission to grant
resource
string | nullResource path; resolved from resource_id if omitted
resource_id
string (UUID) | nullResource id (alternative to resource)
effect
stringallow | denyDefault: allow

Response Fields

NameTypeDescription
id*
string (UUID)Grant row ID
permission_id*
string (UUID)Permission granted
resource*
stringResource path
effect*
stringallow | 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"
}
DELETE/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

NameTypeDescription
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
GET/v1/auth/teams/{team_id}/services

List 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

NameTypeDescription
team_id*
string (UUID)Team ID

Response Fields

NameTypeDescription
id*
string (UUID)Service-access row ID
service_slug*
stringService slug (e.g. workflows)
service_name*
stringHuman-readable service name
source*
string | nulldirect 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"
  }
]
POST/v1/auth/teams/{team_id}/services

Grant 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

NameTypeDescription
team_id*
string (UUID)Team ID

Request Body

NameTypeDescription
service_slug*
stringService slug to grant

Response Fields

NameTypeDescription
id*
string (UUID)Service-access row ID
service_slug*
stringGranted service
service_name*
stringService 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
}
DELETE/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

NameTypeDescription
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 Content

Connections

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.

GET/v1/auth/companies/{company_id}/connections

List Connections

List a subject's active connections plus its pending outgoing requests.

Bearer (user) token. Caller must manage the subject.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID

Query Parameters

NameTypeDescription
subject_type
stringmember | api_key | agent | team | role | automation | compute_api
subject_id
string (UUID)Subject id (with subject_type)
subject
stringSubject ERN/path (alternative to the pair)
q
stringFilter by target resource path or service
limit
integerPage size (1–200)
offset
integerPagination offsetDefault: 0

Response Fields

NameTypeDescription
connections*
arrayActive connection entries
pending_requests*
arrayOutgoing requests awaiting approval
total*
integer | nullTotal 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
}
POST/v1/auth/companies/{company_id}/connections

Connect 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

NameTypeDescription
company_id*
string (UUID)Company ID

Request Body

NameTypeDescription
subject_type
stringmember | api_key | agent | team | role | automation | compute_api
subject_id
string (UUID)Subject id (with subject_type)
subject
stringSubject ERN (alternative to the pair)
target_service*
stringService that owns the zone
target_resource*
stringZone resource path or ERN
permissions
(string | {name, resource})[] | nullPermissions 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 | nullOptional note for the approver

Response Fields

NameTypeDescription
status*
stringconnected | requested
connection*
object | nullThe connection, when connected
request*
object | nullThe 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
}
DELETE/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

NameTypeDescription
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
GET/v1/auth/companies/{company_id}/principals/resolve

Resolve 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

NameTypeDescription
company_id*
string (UUID)Company ID

Query Parameters

NameTypeDescription
type*
stringSubject type: member | api_key | agent | team | role | automation | compute_api
q
stringSearch term or exact handle
limit
integerMax results (1–25)Default: 10

Response Fields

NameTypeDescription
items*
arrayResolved 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*
stringlist | 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"
}
GET/v1/auth/companies/{company_id}/connection-policy

View 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

NameTypeDescription
company_id*
string (UUID)Company ID

Query Parameters

NameTypeDescription
resource*
stringResource path or ERN inside the company
service
stringOwning 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

NameTypeDescription
resource*
stringCanonical resource path
resource_type*
string | nullType of the deepest typed segment of the path
target_service*
string | nullService that owns the resource
open_principal_types*
arrayPrincipal types with no connection policy
declared*
arrayOne 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.

POST/v1/auth/companies/{company_id}/connection-offers

Offer 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

NameTypeDescription
company_id*
string (UUID)Company ID

Request Body

NameTypeDescription
subject_type
stringmember | api_key | agent | team | role | automation | compute_api
subject_id
string (UUID)Subject id (with subject_type)
subject
stringSubject ERN (alternative to the pair)
target_service*
stringService that owns the zone
target_resource*
stringZone resource path or ERN
permissions
(string | {name, resource})[] | nullPermissions 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 | nullOptional note for the invitee

Response Fields

NameTypeDescription
id*
string (UUID)Request ID
direction*
stringoffer
status*
stringpending
target_resource*
stringZone resource path
requested_permissions*
string[] | nullPermissions 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"
}
GET/v1/auth/companies/{company_id}/connection-requests

List Connection Requests

List connection requests and offers for a subject the caller manages.

Bearer (user) token. Caller must manage the subject.

Path Parameters

NameTypeDescription
company_id*
string (UUID)Company ID

Query Parameters

NameTypeDescription
subject_type
stringmember | api_key | agent | team | role | automation | compute_api
subject_id
string (UUID)Subject id (with subject_type)
subject
stringSubject ERN (alternative to the pair)
direction
stringrequest | offer
status
stringFilter by statusDefault: pending

Response Fields

NameTypeDescription
items*
arrayConnection 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"
    }
  ]
}
GET/v1/auth/companies/{company_id}/connection-requests/inbox

Connection 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

NameTypeDescription
company_id*
string (UUID)Company ID

Response Fields

NameTypeDescription
approvals*
arrayPending requests the caller can approve/reject
offers*
arrayPending 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": []
}
POST/v1/auth/companies/{company_id}/connection-requests/{request_id}/accept

Accept / 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

NameTypeDescription
company_id*
string (UUID)Company ID
request_id*
string (UUID)Request/offer ID

Request Body

NameTypeDescription
permissions
(string | {name, resource})[] | nullOverride 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
booleanWhether to issue grants on acceptDefault: true
reason
string | nullOptional note

Response Fields

NameTypeDescription
id*
string (UUID)Request ID
status*
stringaccepted
direction*
stringrequest | 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"
}
POST/v1/auth/companies/{company_id}/connection-requests/{request_id}/reject

Reject

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

NameTypeDescription
company_id*
string (UUID)Company ID
request_id*
string (UUID)Request/offer ID

Request Body

NameTypeDescription
reason
string | nullOptional rejection reason

Response Fields

NameTypeDescription
id*
string (UUID)Request ID
status*
stringrejected
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"
}
POST/v1/auth/companies/{company_id}/connection-requests/{request_id}/withdraw

Withdraw

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

NameTypeDescription
company_id*
string (UUID)Company ID
request_id*
string (UUID)Request/offer ID

Response Fields

NameTypeDescription
id*
string (UUID)Request ID
status*
stringwithdrawn
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.

GET/v1/auth/companies/{company_id}/roles/{role_id}/access/eligible

Role: 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

NameTypeDescription
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 }
GET/v1/auth/companies/{company_id}/roles/{role_id}/access/resource-types

Role: 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

NameTypeDescription
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 }
GET/v1/auth/companies/{company_id}/roles/{role_id}/access/grants

Role: 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

NameTypeDescription
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 }
POST/v1/auth/companies/{company_id}/roles/{role_id}/access/grants

Role: 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

NameTypeDescription
company_id*
string (UUID)Company ID
role_id*
string (UUID)Role ID

Request Body

NameTypeDescription
body*
objectGrant 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 }
DELETE/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

NameTypeDescription
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
GET/v1/auth/companies/{company_id}/roles/{role_id}/access/connection-requests

Role: 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

NameTypeDescription
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 }
POST/v1/auth/companies/{company_id}/roles/{role_id}/access/connection-requests/{request_id}/approve

Role: 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

NameTypeDescription
company_id*
string (UUID)Company ID
role_id*
string (UUID)Role ID

Request Body

NameTypeDescription
body
objectDecision 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 }
POST/v1/auth/companies/{company_id}/roles/{role_id}/access/connection-requests/{request_id}/reject

Role: 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

NameTypeDescription
company_id*
string (UUID)Company ID
role_id*
string (UUID)Role ID

Request Body

NameTypeDescription
body
objectDecision 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 }
GET/v1/auth/companies/{company_id}/roles/{role_id}/access/connections

Role: 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

NameTypeDescription
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 }
DELETE/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

NameTypeDescription
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
GET/v1/auth/companies/{company_id}/teams/{team_id}/access/connection-requests

Team: 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

NameTypeDescription
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 }
POST/v1/auth/companies/{company_id}/teams/{team_id}/access/connection-requests/{request_id}/approve

Team: 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

NameTypeDescription
company_id*
string (UUID)Company ID
team_id*
string (UUID)Team ID

Request Body

NameTypeDescription
body
objectDecision 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 }
POST/v1/auth/companies/{company_id}/teams/{team_id}/access/connection-requests/{request_id}/reject

Team: 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

NameTypeDescription
company_id*
string (UUID)Company ID
team_id*
string (UUID)Team ID

Request Body

NameTypeDescription
body
objectDecision 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 }
GET/v1/auth/companies/{company_id}/teams/{team_id}/access/connections

Team: 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

NameTypeDescription
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 }
DELETE/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

NameTypeDescription
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
GET/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/eligible

API 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

NameTypeDescription
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 }
GET/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/resource-types

API 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

NameTypeDescription
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 }
GET/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/grants

API 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

NameTypeDescription
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 }
POST/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/grants

API 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

NameTypeDescription
company_id*
string (UUID)Company ID
api_key_id*
string (UUID)API Key ID

Request Body

NameTypeDescription
body*
objectGrant 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 }
DELETE/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

NameTypeDescription
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
GET/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/connection-requests

API 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

NameTypeDescription
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 }
POST/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/connection-requests/{request_id}/approve

API 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

NameTypeDescription
company_id*
string (UUID)Company ID
api_key_id*
string (UUID)API Key ID

Request Body

NameTypeDescription
body
objectDecision 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 }
POST/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/connection-requests/{request_id}/reject

API 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

NameTypeDescription
company_id*
string (UUID)Company ID
api_key_id*
string (UUID)API Key ID

Request Body

NameTypeDescription
body
objectDecision 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 }
GET/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/connections

API 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

NameTypeDescription
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 }
DELETE/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

NameTypeDescription
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
GET/v1/auth/companies/{company_id}/agents/{agent_id}/access/eligible

Agent: 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

NameTypeDescription
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 }
GET/v1/auth/companies/{company_id}/agents/{agent_id}/access/resource-types

Agent: 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

NameTypeDescription
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 }
GET/v1/auth/companies/{company_id}/agents/{agent_id}/access/grants

Agent: 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

NameTypeDescription
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 }
POST/v1/auth/companies/{company_id}/agents/{agent_id}/access/grants

Agent: 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

NameTypeDescription
company_id*
string (UUID)Company ID
agent_id*
string (UUID)Agent ID

Request Body

NameTypeDescription
body*
objectGrant 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 }
DELETE/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

NameTypeDescription
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
GET/v1/auth/companies/{company_id}/agents/{agent_id}/access/connection-requests

Agent: 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

NameTypeDescription
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 }
POST/v1/auth/companies/{company_id}/agents/{agent_id}/access/connection-requests/{request_id}/approve

Agent: 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

NameTypeDescription
company_id*
string (UUID)Company ID
agent_id*
string (UUID)Agent ID

Request Body

NameTypeDescription
body
objectDecision 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 }
POST/v1/auth/companies/{company_id}/agents/{agent_id}/access/connection-requests/{request_id}/reject

Agent: 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

NameTypeDescription
company_id*
string (UUID)Company ID
agent_id*
string (UUID)Agent ID

Request Body

NameTypeDescription
body
objectDecision 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 }
GET/v1/auth/companies/{company_id}/agents/{agent_id}/access/connections

Agent: 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

NameTypeDescription
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 }
DELETE/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

NameTypeDescription
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
GET/v1/auth/companies/{company_id}/members/{member_id}/access/eligible

Member: 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

NameTypeDescription
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 }
GET/v1/auth/companies/{company_id}/members/{member_id}/access/resource-types

Member: 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

NameTypeDescription
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 }
GET/v1/auth/companies/{company_id}/members/{member_id}/access/grants

Member: 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

NameTypeDescription
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 }
POST/v1/auth/companies/{company_id}/members/{member_id}/access/grants

Member: 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

NameTypeDescription
company_id*
string (UUID)Company ID
member_id*
string (UUID)Member ID

Request Body

NameTypeDescription
body*
objectGrant 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 }
DELETE/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

NameTypeDescription
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
GET/v1/auth/companies/{company_id}/members/{member_id}/access/connection-requests

Member: 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

NameTypeDescription
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 }
POST/v1/auth/companies/{company_id}/members/{member_id}/access/connection-requests/{request_id}/approve

Member: 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

NameTypeDescription
company_id*
string (UUID)Company ID
member_id*
string (UUID)Member ID

Request Body

NameTypeDescription
body
objectDecision 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 }
POST/v1/auth/companies/{company_id}/members/{member_id}/access/connection-requests/{request_id}/reject

Member: 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

NameTypeDescription
company_id*
string (UUID)Company ID
member_id*
string (UUID)Member ID

Request Body

NameTypeDescription
body
objectDecision 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 }
GET/v1/auth/companies/{company_id}/members/{member_id}/access/connections

Member: 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

NameTypeDescription
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 }
DELETE/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

NameTypeDescription
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
GET/v1/auth/companies/{company_id}/teams/{team_id}/access/eligible

List 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

NameTypeDescription
company_id*
string (UUID)Company ID
team_id*
string (UUID)Instance ID (here, a team)

Response Fields

NameTypeDescription
principal_type*
stringmember | api_key | agent | team | role
principal_id*
string (UUID)Principal ID
label*
stringDisplay label
display_name*
string | nullDisplay name
avatar_url*
string | nullAvatar 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
  }
]
GET/v1/auth/companies/{company_id}/teams/{team_id}/access/resource-types

List 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

NameTypeDescription
company_id*
string (UUID)Company ID
team_id*
string (UUID)Instance ID

Response Fields

NameTypeDescription
resource_types*
arrayResource-type tree nodes
permissions*
arrayGrantable permissions with their resource type
resource_type_edges*
arrayEdges 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": []
}
GET/v1/auth/companies/{company_id}/teams/{team_id}/access/grants

List 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

NameTypeDescription
company_id*
string (UUID)Company ID
team_id*
string (UUID)Instance ID

Query Parameters

NameTypeDescription
page
integerPage number (>= 1)Default: 1
limit
integerPage size (1–500)Default: 100

Response Fields

NameTypeDescription
items*
arrayGrant entries on this instance
total*
integerTotal grants
page*
integerCurrent page
limit*
integerPage 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
}
POST/v1/auth/companies/{company_id}/teams/{team_id}/access/grants

Create 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

NameTypeDescription
company_id*
string (UUID)Company ID
team_id*
string (UUID)Instance ID

Request Body

NameTypeDescription
principal_type*
stringmember | api_key | agent | team | role | automation | workflow | worksheet
principal_id*
string (UUID)Principal to grant
permission_id
string (UUID) | nullPermission to grant (or use permission_name)
permission_name
string | nullPermission name (or use permission_id)
resource
string | nullResource path; defaults to this instance
effect
stringallow | denyDefault: allow

Response Fields

NameTypeDescription
id*
string (UUID)Grant row ID
permission_id*
string (UUID)Permission granted
resource*
stringResource path
effect*
stringallow | 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"
}
DELETE/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

NameTypeDescription
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 Content

Protocol 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.

DELETE/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
GET/v1/auth/team-principals/{principal_id}/expanded-members

Expand 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" }
GET/v1/auth/companies/{company_id}/resources

List 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" }
GET/v1/auth/companies/{company_id}/resources/summary

Summarize 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" }
GET/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" }
GET/v1/auth/companies/{company_id}/resources/{resource_id}/access

List 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" }
GET/v1/auth/companies/{company_id}/resources/{resource_id}/recoverable

Preview 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" }
GET/v1/auth/companies/{company_id}/resources/{resource_id}/access-presets

Get 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" }
POST/v1/auth/companies/{company_id}/resources/{resource_id}/recover

Recover 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" }
POST/v1/auth/companies/{company_id}/resources/{resource_id}/takeover

Take 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" }
GET/v1/auth/sso/providers

List 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" }
GET/v1/auth/sso/{provider_slug}/authorize

Start SSO Authorization

Start an interactive OIDC authorization-code flow with PKCE, state, and nonce. Optional query entry_company_slug marks the sign-in as made at that company's start URL (use it, with redirect_to=/apps/{company_slug}, from the start URL's sign-in page, or with redirect_to=/apps/{company_slug}/{app_slug} from an app address, which shows the same sign-in); the session then opens that company, as with Login. An unknown slug is ignored. With entry_company_slug, optional entry_app_id names the portal App of that company the sign-in is made in; the company's access history then records it, and an App that is not that company's is ignored. Optional redirect_to (safe relative path) and invitation_token are carried through to the callback. This credential/session route is intentionally not an agent tool.

Interactive browser session; rate limited.

curl -X GET https://platform.ergondata.ai/v1/auth/sso/{provider_slug}/authorize -H "Authorization: Bearer {token}"

Response

302
{ "detail": "See response schema" }
GET/v1/auth/sso/{provider_slug}/callback

Complete 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" }
GET/v1/auth/platform-admin/me

Get 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" }
GET/v1/auth/platform-admin/companies

List 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" }
GET/v1/auth/platform-admin/companies/{company_id}/services

List 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" }
PUT/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" }
DELETE/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
GET/v1/auth/platform-admin/companies/{company_id}/feature-flags

List 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" }
PUT/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" }
DELETE/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
GET/v1/auth/platform-admin/users

List 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" }
GET/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" }
POST/v1/auth/platform-admin/users/{user_id}/mfa/reset

Reset 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" }
GET/v1/auth/me/access-history

Get 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" }
POST/v1/auth/me/sessions/revoke-all

Revoke 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" }
PATCH/v1/auth/companies/{company_id}/security-policy

Update 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" }
GET/v1/auth/companies/{company_id}/members/{user_id}/access-history

List 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" }
POST/v1/auth/companies/{company_id}/members/{user_id}/sessions/revoke

Revoke 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" }
GET/v1/auth/platform-admin/auth-events

List 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" }
GET/v1/auth/platform-admin/users/{user_id}/access-history

Get 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" }
POST/v1/auth/platform-admin/users/{user_id}/unlock

Unlock 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" }
POST/v1/auth/platform-admin/users/{user_id}/sessions/revoke

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