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 Ergon console under IAM → API Keys. Issuance is gated by Working Hours Strict Mode and IP allowlists when configured for the key's principal.

No authentication required.

Request Body

Name	Type	Description
`client_id`*	string	API key client ID
`client_secret`*	string	API key client secret

Response Fields

Name	Type	Description
`access_token`*	string	Bearer token for API calls
`token_type`*	string	Always "bearer"
`expires_in`*	integer	Token lifetime in seconds

curl -X POST https://platform.ergondata.ai/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "ek_your-client-id",
    "client_secret": "eks_your-client-secret"
  }'

Response

200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

User Authentication

Register users, sign in (with optional MFA challenge), refresh sessions, select a company context, and inspect the current principal.

POST/v1/auth/register

Register User

Create a new user account. A verification email is sent to the address.

No authentication required.

Request Body

Name	Type	Description
`email`*	string (email)	User email address
`password`*	string	Password (minimum 8 characters)
`name`*	string	Display name (minimum 1 character)

Response Fields

Name	Type	Description
`id`*	string (UUID)	User ID
`email`*	string	User email
`name`*	string	Display name
`is_active`*	boolean	Whether the account is active
`avatar_url`	string \| null	Avatar URL
`created_at`*	string (date-time)	Creation timestamp

curl -X POST https://platform.ergondata.ai/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "s3cret-passphrase",
    "name": "Jane Doe"
  }'

Response

201 Created

{
  "id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
  "email": "[email protected]",
  "name": "Jane Doe",
  "is_active": true,
  "avatar_url": null,
  "created_at": "2026-01-05T14:20:00Z"
}

POST/v1/auth/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.

No authentication required.

Request Body

Name	Type	Description
`email`*	string (email)	User email address
`password`*	string	User password

Response Fields

Name	Type	Description
`access_token`	string	Bearer token (present on success, absent on MFA challenge)
`token_type`	string	Always "bearer" on success
`company_id`	string (UUID) \| null	Active company bound to the token, if any
`mfa_required`	boolean	Present and true when MFA must be completed
`mfa_token`	string	Challenge token to pass to MFA verify (challenge only)
`attempts_left`	integer	Remaining MFA attempts (challenge only)
`enrollment_required`	boolean	Whether the user must enroll a factor first (challenge only)

curl -X POST https://platform.ergondata.ai/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "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.

Requires the refresh_token cookie.

Response Fields

Name	Type	Description
`access_token`*	string	New bearer token
`token_type`	string	Always "bearer"
`company_id`	string (UUID) \| null	Active company bound to the token, if any

curl -X POST https://platform.ergondata.ai/v1/auth/refresh \
  --cookie "refresh_token={refresh_token}"

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/select-active-company

Select Active Company

Mint a fresh access token bound to a company you belong to. The returned token carries a company_id claim so downstream services derive the active tenant from the JWT. Membership is enforced server-side (403 if you do not belong, or if outside working hours under Strict Mode).

Bearer token required.

Request Body

Name	Type	Description
`company_id`*	string (UUID)	Company to activate (must be a company you belong to)

Response Fields

Name	Type	Description
`access_token`*	string	Company-scoped bearer token
`token_type`	string	Always "bearer"
`company_id`	string (UUID) \| null	Company bound to the token

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

GET/v1/auth/me

Get Current Principal

Return the authenticated user plus every company membership (roles, permissions, and enabled services per company) and platform-level permissions.

Bearer token required.

Response Fields

Name	Type	Description
`user`*	object	The authenticated user (UserResponse)
`companies`*	array	Company memberships with roles, permissions, and services
`platform_permissions`	array<string>	Platform-level permissions

curl https://platform.ergondata.ai/v1/auth/me \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "user": {
    "id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
    "email": "[email protected]",
    "name": "Jane Doe",
    "is_active": true,
    "avatar_url": null,
    "created_at": "2026-01-05T14:20:00Z"
  },
  "companies": [
    {
      "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
      "company_name": "Acme Corp",
      "company_slug": "acme-corp",
      "roles": ["owner"],
      "permissions": ["iam:company:members:view"],
      "services": ["agents", "workflows"]
    }
  ],
  "platform_permissions": []
}

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

Name	Type	Description
`token`*	string	Verification token from the email

curl -X POST https://platform.ergondata.ai/v1/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{"token": "verify-token-abc123"}'

Response

200 OK

{}

POST/v1/auth/resend-verification

Resend Verification Email

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

No authentication required.

Request Body

Name	Type	Description
`email`*	string (email)	Email to resend verification to

curl -X POST https://platform.ergondata.ai/v1/auth/resend-verification \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Response

200 OK

{}

POST/v1/auth/forgot-password

Forgot Password

Trigger a password-reset email. Always returns 200 to avoid leaking which emails exist.

No authentication required.

Request Body

Name	Type	Description
`email`*	string (email)	Account email address

curl -X POST https://platform.ergondata.ai/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Response

200 OK

{}

POST/v1/auth/reset-password

Reset Password

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

No authentication required.

Request Body

Name	Type	Description
`token`*	string	Reset token from the email
`password`*	string	New password (minimum 8 characters)

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

Name	Type	Description
`current_password`*	string	Current password
`new_password`*	string	New password (minimum 8 characters)

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

Name	Type	Description
`new_email`*	string (email)	New email address
`password`*	string	Current password for confirmation

curl -X POST https://platform.ergondata.ai/v1/auth/change-email \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "new_email": "[email protected]",
    "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

Name	Type	Description
`token`*	string	Email-change confirmation token

curl -X POST https://platform.ergondata.ai/v1/auth/verify-email-change \
  -H "Content-Type: application/json" \
  -d '{"token": "email-change-token-abc123"}'

Response

200 OK

{}

Profile, Avatar & Identities

Manage the current user's avatar and federated (SSO) identity links.

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

Name	Type	Description
`file`*	binary (multipart/form-data)	Image file to upload

curl -X PUT https://platform.ergondata.ai/v1/auth/me/avatar \
  -H "Authorization: Bearer {token}" \
  -F "[email protected]"

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

Name	Type	Description
`id`*	string (UUID)	Identity link ID
`provider`*	string	Identity provider slug
`email_at_link`*	string	Email returned by the provider when linked
`last_login_at`	string (date-time) \| null	Most recent login via this identity
`created_at`*	string (date-time)	When the link was created

curl https://platform.ergondata.ai/v1/auth/me/identities \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "11111111-2222-3333-4444-555555555555",
    "provider": "google",
    "email_at_link": "[email protected]",
    "last_login_at": "2026-02-01T09:00:00Z",
    "created_at": "2026-01-05T14:20:00Z"
  }
]

DELETE/v1/auth/me/identities/{identity_id}

Unlink Identity

Remove a federated identity link from the current user.

Bearer token required.

Path Parameters

Name	Type	Description
`identity_id`*	string (UUID)	Identity link ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/me/identities/{identity_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

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

Name	Type	Description
`enabled`*	boolean	Whether a confirmed factor exists
`company_requires_mfa`	boolean	Whether the active company mandates MFA
`enrolled_at`	string (date-time) \| null	When the factor was enrolled
`last_used_at`	string (date-time) \| null	When MFA was last used
`recovery_codes_remaining`	integer	Unused recovery codes left

curl https://platform.ergondata.ai/v1/auth/mfa/status \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "enabled": true,
  "company_requires_mfa": false,
  "enrolled_at": "2026-01-10T08:00:00Z",
  "last_used_at": "2026-02-01T09:00:00Z",
  "recovery_codes_remaining": 8
}

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

Name	Type	Description
`label`	string \| null	Optional label for the authenticator entry (max 64 chars)
`mfa_token`	string \| null	Challenge token, required only during forced enrollment

Response Fields

Name	Type	Description
`secret`*	string	TOTP shared secret
`otpauth_uri`*	string	otpauth:// URI for QR codes

curl -X POST https://platform.ergondata.ai/v1/auth/mfa/setup \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"label": "Ergon"}'

Response

200 OK

{
  "secret": "JBSWY3DPEHPK3PXP",
  "otpauth_uri": "otpauth://totp/Ergon:[email protected]?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.

Bearer token or MFA challenge token.

Request Body

Name	Type	Description
`code`*	string	Current 6-digit TOTP code
`mfa_token`	string \| null	Challenge token, required only during forced enrollment

Response Fields

Name	Type	Description
`recovery_codes`*	array<string>	One-time recovery codes (stored hashed; shown once)
`access_token`	string \| null	Bearer token (populated during forced enrollment)
`token_type`	string	Always "bearer"

curl -X POST https://platform.ergondata.ai/v1/auth/mfa/setup/verify \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

Response

200 OK

{
  "recovery_codes": ["a1b2-c3d4", "e5f6-g7h8", "i9j0-k1l2"],
  "access_token": null,
  "token_type": "bearer"
}

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.

No authentication required (uses the MFA challenge token).

Request Body

Name	Type	Description
`mfa_token`*	string	Challenge token from /login
`code`	string \| null	6-digit TOTP code
`recovery_code`	string \| null	A recovery code (alternative to a TOTP code)

Response Fields

Name	Type	Description
`access_token`*	string	Bearer token
`token_type`	string	Always "bearer"
`company_id`	string (UUID) \| null	Active company bound to the token, if any

curl -X POST https://platform.ergondata.ai/v1/auth/mfa/verify \
  -H "Content-Type: application/json" \
  -d '{"mfa_token": "{mfa_token}", "code": "123456"}'

Response

200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "company_id": null
}

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

Name	Type	Description
`password`*	string	Current password
`code`	string \| null	6-digit TOTP code
`recovery_code`	string \| null	A recovery code

curl -X POST https://platform.ergondata.ai/v1/auth/mfa/disable \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"password": "s3cret-passphrase", "code": "123456"}'

Response

200 OK

{}

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

Name	Type	Description
`password`*	string	Current password
`code`	string \| null	6-digit TOTP code
`recovery_code`	string \| null	A recovery code

Response Fields

Name	Type	Description
`recovery_codes`*	array<string>	New one-time recovery codes (shown once)

curl -X POST https://platform.ergondata.ai/v1/auth/mfa/recovery-codes/regenerate \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"password": "s3cret-passphrase", "code": "123456"}'

Response

200 OK

{
  "recovery_codes": ["m3n4-o5p6", "q7r8-s9t0", "u1v2-w3x4"]
}

Companies

Create and manage companies, profiles, avatars, and the per-company MFA policy.

POST/v1/auth/companies

Create Company

Create a new company. The caller becomes its first member/owner.

Bearer token required.

Request Body

Name	Type	Description
`name`*	string	Company display name
`slug`*	string	URL-safe slug (2–255 chars, ^[a-z0-9][a-z0-9-]*$)

Response Fields

Name	Type	Description
`id`*	string (UUID)	Company ID
`name`*	string	Company name
`slug`*	string	Company slug
`description`	string \| null	Description
`avatar_url`	string \| null	Avatar URL
`created_at`*	string (date-time)	Creation timestamp

curl -X POST https://platform.ergondata.ai/v1/auth/companies \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp", "slug": "acme-corp"}'

Response

201 Created

{
  "id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "description": null,
  "avatar_url": null,
  "created_at": "2026-01-05T14:20:00Z"
}

GET/v1/auth/companies

List Companies

List companies the authenticated principal belongs to.

Bearer token required.

Response Fields

Name	Type	Description
`id`*	string (UUID)	Company ID
`name`*	string	Company name
`slug`*	string	Company slug
`created_at`*	string (date-time)	Creation timestamp

curl https://platform.ergondata.ai/v1/auth/companies \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "c0ffee00-cafe-babe-dead-beefcafebabe",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "description": null,
    "avatar_url": null,
    "created_at": "2026-01-05T14:20:00Z"
  }
]

GET/v1/auth/companies/{company_id}

Get Company

Retrieve company details including member count, enabled services, and MFA policy.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Company ID
`name`*	string	Company name
`slug`*	string	Company slug
`member_count`*	integer	Number of members
`enabled_services`*	array<string>	Service slugs enabled for the company
`require_mfa`	boolean	Whether MFA is mandatory
`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,
  "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 required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Company ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

PATCH/v1/auth/companies/{company_id}/profile

Update Company Profile

Update a company's name and/or description.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Request Body

Name	Type	Description
`name`	string \| null	New name (1–255 chars)
`description`	string \| null	New description (max 5000)

Response Fields

Name	Type	Description
`id`*	string (UUID)	Company ID
`name`*	string	Updated name
`description`	string \| null	Updated description

curl -X PATCH https://platform.ergondata.ai/v1/auth/companies/{company_id}/profile \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corporation", "description": "We make everything."}'

Response

200 OK

{
  "id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "name": "Acme Corporation",
  "slug": "acme-corp",
  "description": "We make everything.",
  "member_count": 12,
  "enabled_services": ["agents", "workflows"],
  "require_mfa": false,
  "created_at": "2026-01-05T14:20:00Z"
}

PATCH/v1/auth/companies/{company_id}/mfa-policy

Update MFA Policy

Toggle the per-company require_mfa flag. Members without a confirmed factor are forced into enrollment on their next sign-in.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Request Body

Name	Type	Description
`require_mfa`*	boolean	Whether MFA is mandatory

Response Fields

Name	Type	Description
`id`*	string (UUID)	Company ID
`require_mfa`	boolean	Updated MFA policy

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

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,
  "created_at": "2026-01-05T14:20:00Z"
}

PUT/v1/auth/companies/{company_id}/avatar

Upload Company Avatar

Upload or replace a company's avatar/logo image (multipart/form-data).

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Request Body

Name	Type	Description
`file`*	binary (multipart/form-data)	Image file to upload

curl -X PUT https://platform.ergondata.ai/v1/auth/companies/{company_id}/avatar \
  -H "Authorization: Bearer {token}" \
  -F "[email protected]"

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 Avatar

Remove a company's avatar/logo image.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Company ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/avatar \
  -H "Authorization: Bearer {token}"

Response

200 OK

{}

Members

Add and remove company members 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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Query Parameters

Name	Type	Description
`page`	integer	Page number (min 1)Default: `1`
`limit`	integer	Items per page (1–100)Default: `50`

Response Fields

Name	Type	Description
`items`*	array	Member records
`total`*	integer	Total members
`page`*	integer	Current page
`limit`*	integer	Page size

curl "https://platform.ergondata.ai/v1/auth/companies/{company_id}/members?page=1&limit=50" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "user_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
      "email": "[email protected]",
      "name": "Jane Doe",
      "roles": ["owner"],
      "joined_at": "2026-01-05T14:25:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50
}

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

Add Member / Invite

Invite a user by email or add an existing user. New users receive an invitation; existing users are added directly. Optionally assign roles and service access on join.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Request Body

Name	Type	Description
`email`*	string (email)	Email of the user to add/invite
`role`	string \| null	Single role name (max 50 chars)
`roles`	array<string> \| null	Role names to assign
`service_slugs`	array<string> \| null	Service slugs to grant on join
`team_ids`	array<UUID> \| null	Teams to add the invitee to on accept. The caller must be able to manage each team (iam:company:teams:manage); membership is materialized when the invitation is accepted.

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/members \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "roles": ["member"],
    "service_slugs": ["workflows"]
  }'

Response

201 Created

{
  "invitation_id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
  "email": "[email protected]",
  "status": "pending"
}

DELETE/v1/auth/companies/{company_id}/members/{user_id}

Remove Member

Remove a user from the company.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`user_id`*	string (UUID)	User to remove

curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{user_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`user_id`*	string (UUID)	Member user ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Assignment ID
`role_id`*	string (UUID)	Role ID
`name`*	string	Role name
`is_system`*	boolean	Whether it is a built-in role
`granted_at`*	string (date-time)	When assigned

curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{user_id}/roles \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809",
    "role_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "name": "member",
    "is_system": true,
    "granted_at": "2026-01-06T10:00:00Z"
  }
]

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. Agent ToolDef slug: iam.company.members.roles.assign.

Bearer token with iam:company:members:manage on the target member.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`user_id`*	string (UUID)	Member user ID

Request Body

Name	Type	Description
`role_id`*	string (UUID)	Role to assign

Response Fields

Name	Type	Description
`id`*	string (UUID)	Assignment ID
`role_id`*	string (UUID)	Role ID
`name`*	string	Role name
`is_system`*	boolean	Whether it is a built-in role
`granted_at`*	string (date-time)	When assigned

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{user_id}/roles \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"role_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"}'

Response

201 Created

{
  "id": "1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809",
  "role_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "name": "member",
  "is_system": true,
  "granted_at": "2026-01-06T10:00:00Z"
}

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. Agent ToolDef slug: iam.company.members.roles.remove.

Bearer token with iam:company:members:manage on the target member.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`user_id`*	string (UUID)	Member user ID
`pr_id`*	string (UUID)	Role-assignment ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{user_id}/roles/{pr_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`user_id`*	string (UUID)	Member user ID

Query Parameters

Name	Type	Description
`page`	integer	Page number (min 1)Default: `1`
`limit`	integer	Items per page (1–100)Default: `50`

curl "https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{user_id}/permissions?page=1&limit=50" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "2b3c4d5e-6f70-8192-a3b4-c5d6e7f80910",
      "permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0",
      "name": "iam:company:members:view",
      "resource": "*",
      "effect": "allow",
      "is_system": false,
      "granted_at": "2026-01-06T10:05:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`user_id`*	string (UUID)	Member user ID

Request Body

Name	Type	Description
`permission_id`*	string (UUID)	Permission to grant
`effect`	string	Allow or denyDefault: `allow`
`resource`	string \| null	Resource path the grant applies to
`resource_id`	string (UUID) \| null	Specific resource instance ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Grant ID
`permission_id`*	string (UUID)	Permission ID
`name`*	string	Permission name
`resource`*	string	Resource the grant applies to
`effect`*	string	allow or deny
`is_system`*	boolean	Whether it is a built-in grant
`granted_at`*	string (date-time)	When granted

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{user_id}/permissions \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0", "effect": "allow"}'

Response

201 Created

{
  "id": "2b3c4d5e-6f70-8192-a3b4-c5d6e7f80910",
  "permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0",
  "name": "iam:company:members:view",
  "resource": "*",
  "effect": "allow",
  "is_system": false,
  "granted_at": "2026-01-06T10:05:00Z"
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`user_id`*	string (UUID)	Member user ID
`pp_id`*	string (UUID)	Permission-grant ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{user_id}/permissions/{pp_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`user_id`*	string (UUID)	Member user ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Service-access grant ID
`service_slug`*	string	Service slug
`service_name`*	string	Service name
`source`	string \| null	Where the access came from: `direct` or `role:<name>`
`granted_at`*	string (date-time)	When granted

curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{user_id}/services \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "3c4d5e6f-7081-92a3-b4c5-d6e7f8091011",
    "service_slug": "workflows",
    "service_name": "Workflows",
    "source": "direct",
    "granted_at": "2026-01-06T10:10:00Z"
  }
]

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`user_id`*	string (UUID)	Member user ID

Request Body

Name	Type	Description
`service_slug`*	string	Service slug to grant

Response Fields

Name	Type	Description
`id`*	string (UUID)	Service-access grant ID
`service_slug`*	string	Service slug
`service_name`*	string	Service name
`granted_at`*	string (date-time)	When granted

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{user_id}/services \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"service_slug": "workflows"}'

Response

201 Created

{
  "id": "3c4d5e6f-7081-92a3-b4c5-d6e7f8091011",
  "service_slug": "workflows",
  "service_name": "Workflows",
  "source": "direct",
  "granted_at": "2026-01-06T10:10:00Z"
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`user_id`*	string (UUID)	Member user ID
`access_id`*	string (UUID)	Service-access grant ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{user_id}/services/{access_id} \
  -H "Authorization: Bearer {token}"

Response

204 No 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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Role ID
`name`*	string	Role name
`description`	string \| null	Role description
`is_system`*	boolean	Whether it is a built-in role
`company_id`	string (UUID) \| null	Owning company (null for global roles)

curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "name": "member",
    "description": "Standard member",
    "is_system": true,
    "company_id": null
  }
]

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

Create Role

Create a custom role in a company.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Request Body

Name	Type	Description
`name`*	string	Role name (1–50 chars)
`description`	string \| null	Role description

Response Fields

Name	Type	Description
`id`*	string (UUID)	Role ID
`name`*	string	Role name
`description`	string \| null	Role description
`is_system`*	boolean	Always false for custom roles
`company_id`	string (UUID) \| null	Owning company

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "billing-admin", "description": "Manages billing"}'

Response

201 Created

{
  "id": "5d6e7f80-9102-3343-5566-7788990011aa",
  "name": "billing-admin",
  "description": "Manages billing",
  "is_system": false,
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe"
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`role_id`*	string (UUID)	Role ID

Request Body

Name	Type	Description
`name`	string \| null	New name (1–50 chars)
`description`	string \| null	New description

Response Fields

Name	Type	Description
`id`*	string (UUID)	Role ID
`name`*	string	Role name
`description`	string \| null	Role description
`is_system`*	boolean	Whether it is a built-in role
`company_id`	string (UUID) \| null	Owning company

curl -X PATCH https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"description": "Manages billing and invoices"}'

Response

200 OK

{
  "id": "5d6e7f80-9102-3343-5566-7788990011aa",
  "name": "billing-admin",
  "description": "Manages billing and invoices",
  "is_system": false,
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe"
}

DELETE/v1/auth/companies/{company_id}/roles/{role_id}

Delete Role

Delete a custom role.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`role_id`*	string (UUID)	Role ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`role_id`*	string (UUID)	Role ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Role-service grant ID
`service_slug`*	string	Service slug
`service_name`*	string	Service name
`granted_at`*	string (date-time)	When attached

curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id}/services \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "6e7f8091-0233-4455-6677-8899aabbccdd",
    "service_slug": "workflows",
    "service_name": "Workflows",
    "source": "role",
    "granted_at": "2026-01-06T11:00:00Z"
  }
]

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`role_id`*	string (UUID)	Role ID

Request Body

Name	Type	Description
`service_slug`*	string	Service slug to attach

Response Fields

Name	Type	Description
`id`*	string (UUID)	Role-service grant ID
`service_slug`*	string	Service slug
`service_name`*	string	Service name
`granted_at`*	string (date-time)	When attached

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id}/services \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"service_slug": "workflows"}'

Response

201 Created

{
  "id": "6e7f8091-0233-4455-6677-8899aabbccdd",
  "service_slug": "workflows",
  "service_name": "Workflows",
  "source": "role",
  "granted_at": "2026-01-06T11:00:00Z"
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`role_id`*	string (UUID)	Role ID
`rs_id`*	string (UUID)	Role-service grant ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id}/services/{rs_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/v1/auth/roles/{role_id}/permissions

List Role Permissions

List the permissions granted directly to a role.

Bearer token required.

Path Parameters

Name	Type	Description
`role_id`*	string (UUID)	Role ID

Response Fields

Name	Type	Description
`items`*	GrantedPermission[]	Direct permission grants
`total`*	integer	Total direct grants

curl https://platform.ergondata.ai/v1/auth/roles/{role_id}/permissions \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "7f809102-3344-5566-7788-99aabbccddee",
      "permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0",
      "name": "iam:company:members:view",
      "resource": "*",
      "effect": "allow",
      "is_system": false,
      "granted_at": "2026-01-06T11:05:00Z"
    }
  ],
  "total": 1
}

POST/v1/auth/roles/{role_id}/permissions

Add Role Permission

Grant a permission to a role.

Bearer token required.

Path Parameters

Name	Type	Description
`role_id`*	string (UUID)	Role ID

Request Body

Name	Type	Description
`permission_id`*	string (UUID)	Permission to grant
`effect`	string	allow or denyDefault: `allow`
`resource`	string \| null	Resource path the grant applies to
`resource_id`	string (UUID) \| null	Specific resource instance ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Grant ID
`permission_id`*	string (UUID)	Permission ID
`name`*	string	Permission name
`resource`*	string	Resource the grant applies to
`effect`*	string	allow or deny
`is_system`*	boolean	Whether it is a built-in grant
`granted_at`*	string (date-time)	When granted

curl -X POST https://platform.ergondata.ai/v1/auth/roles/{role_id}/permissions \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0", "effect": "allow"}'

Response

201 Created

{
  "id": "7f809102-3344-5566-7788-99aabbccddee",
  "permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0",
  "name": "iam:company:members:view",
  "resource": "*",
  "effect": "allow",
  "is_system": false,
  "granted_at": "2026-01-06T11:05:00Z"
}

DELETE/v1/auth/roles/{role_id}/permissions/{pp_id}

Remove Role Permission

Revoke a permission from a role.

Bearer token required.

Path Parameters

Name	Type	Description
`role_id`*	string (UUID)	Role ID
`pp_id`*	string (UUID)	Permission-grant ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/roles/{role_id}/permissions/{pp_id} \
  -H "Authorization: Bearer {token}"

Response

204 No 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

Name	Type	Description
`company_id`*	string (UUID)	Owning company
`name`*	string	Human-readable key name
`service_slugs`*	array<string>	Services the key may access
`expires_at`	string (date-time) \| null	Optional expiry timestamp

Response Fields

Name	Type	Description
`id`*	string (UUID)	API key ID
`client_id`*	string	Public client identifier (ek_...)
`client_secret`*	string	Secret (eks_...), shown once at creation

curl -X POST https://platform.ergondata.ai/v1/auth/api-keys \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
    "name": "CI pipeline",
    "service_slugs": ["workflows"]
  }'

Response

201 Created

{
  "id": "a1a2a3a4-b5b6-c7c8-d9d0-e1e2e3e4e5e6",
  "client_id": "ek_live_8f2c1d...",
  "client_secret": "eks_live_a9b8c7..."
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Query Parameters

Name	Type	Description
`page`	integer	Page number (min 1)Default: `1`
`limit`	integer	Items per page (1–100)Default: `50`

curl "https://platform.ergondata.ai/v1/auth/companies/{company_id}/api-keys?page=1&limit=50" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "a1a2a3a4-b5b6-c7c8-d9d0-e1e2e3e4e5e6",
      "name": "CI pipeline",
      "client_id": "ek_live_8f2c1d...",
      "expires_at": null,
      "services": ["workflows"],
      "created_at": "2026-01-07T09:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50
}

PATCH/v1/auth/api-keys/{key_id}

Update API Key

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

Bearer token required.

Path Parameters

Name	Type	Description
`key_id`*	string (UUID)	API key ID

Request Body

Name	Type	Description
`name`	string \| null	New name (1–100 chars)
`expires_at`	string (date-time) \| null	New expiry timestamp

Response Fields

Name	Type	Description
`id`*	string (UUID)	API key ID
`name`*	string	Key name
`client_id`	string \| null	Public client identifier
`expires_at`	string (date-time) \| null	Expiry
`services`*	array<string>	Services the key may access
`created_at`*	string (date-time)	Creation timestamp

curl -X PATCH https://platform.ergondata.ai/v1/auth/api-keys/{key_id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI pipeline (prod)"}'

Response

200 OK

{
  "id": "a1a2a3a4-b5b6-c7c8-d9d0-e1e2e3e4e5e6",
  "name": "CI pipeline (prod)",
  "client_id": "ek_live_8f2c1d...",
  "expires_at": null,
  "services": ["workflows"],
  "created_at": "2026-01-07T09:00:00Z"
}

DELETE/v1/auth/api-keys/{key_id}

Delete API Key

Permanently revoke an API key.

Bearer token required.

Path Parameters

Name	Type	Description
`key_id`*	string (UUID)	API key ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/api-keys/{key_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

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

Name	Type	Description
`key_id`*	string (UUID)	API key ID

Query Parameters

Name	Type	Description
`page`	integer	Page number (min 1)Default: `1`
`limit`	integer	Items per page (1–100)Default: `50`

curl "https://platform.ergondata.ai/v1/auth/api-keys/{key_id}/permissions?page=1&limit=50" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "b2b3b4b5-c6c7-d8d9-e0e1-f2f3f4f5f6f7",
      "permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0",
      "name": "workflows: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

Name	Type	Description
`key_id`*	string (UUID)	API key ID

Request Body

Name	Type	Description
`permission_id`*	string (UUID)	Permission to grant
`effect`	string	allow or denyDefault: `allow`
`resource`	string \| null	Resource path the grant applies to
`resource_id`	string (UUID) \| null	Specific resource instance ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Grant ID
`permission_id`*	string (UUID)	Permission ID
`name`*	string	Permission name
`resource`*	string	Resource the grant applies to
`effect`*	string	allow or deny
`is_system`*	boolean	Whether it is a built-in grant
`granted_at`*	string (date-time)	When granted

curl -X POST https://platform.ergondata.ai/v1/auth/api-keys/{key_id}/permissions \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0", "effect": "allow"}'

Response

201 Created

{
  "id": "b2b3b4b5-c6c7-d8d9-e0e1-f2f3f4f5f6f7",
  "permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0",
  "name": "workflows: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

Name	Type	Description
`key_id`*	string (UUID)	API key ID
`pp_id`*	string (UUID)	Permission-grant ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/api-keys/{key_id}/permissions/{pp_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

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

Name	Type	Description
`key_id`*	string (UUID)	API key ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Assignment ID
`role_id`*	string (UUID)	Role ID
`name`*	string	Role name
`is_system`*	boolean	Whether it is a built-in role
`granted_at`*	string (date-time)	When assigned

curl https://platform.ergondata.ai/v1/auth/api-keys/{key_id}/roles \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "c3c4c5c6-d7d8-e9e0-f1f2-031415161718",
    "role_id": "5d6e7f80-9102-3343-5566-7788990011aa",
    "name": "billing-admin",
    "is_system": false,
    "granted_at": "2026-01-07T09:15:00Z"
  }
]

POST/v1/auth/api-keys/{key_id}/roles

Assign API Key Role

Assign a role to an API key.

Bearer token required.

Path Parameters

Name	Type	Description
`key_id`*	string (UUID)	API key ID

Request Body

Name	Type	Description
`role_id`*	string (UUID)	Role to assign

Response Fields

Name	Type	Description
`id`*	string (UUID)	Assignment ID
`role_id`*	string (UUID)	Role ID
`name`*	string	Role name
`is_system`*	boolean	Whether it is a built-in role
`granted_at`*	string (date-time)	When assigned

curl -X POST https://platform.ergondata.ai/v1/auth/api-keys/{key_id}/roles \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"role_id": "5d6e7f80-9102-3343-5566-7788990011aa"}'

Response

201 Created

{
  "id": "c3c4c5c6-d7d8-e9e0-f1f2-031415161718",
  "role_id": "5d6e7f80-9102-3343-5566-7788990011aa",
  "name": "billing-admin",
  "is_system": false,
  "granted_at": "2026-01-07T09:15:00Z"
}

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

Name	Type	Description
`key_id`*	string (UUID)	API key ID
`pr_id`*	string (UUID)	Role-assignment ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/api-keys/{key_id}/roles/{pr_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

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

Name	Type	Description
`key_id`*	string (UUID)	API key ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Service-access grant ID
`service_slug`*	string	Service slug
`service_name`*	string	Service name
`granted_at`*	string (date-time)	When granted

curl https://platform.ergondata.ai/v1/auth/api-keys/{key_id}/services \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "d4d5d6d7-e8e9-f0f1-0203-1a2b3c4d5e6f",
    "service_slug": "workflows",
    "service_name": "Workflows",
    "source": "direct",
    "granted_at": "2026-01-07T09:20:00Z"
  }
]

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

Name	Type	Description
`key_id`*	string (UUID)	API key ID

Request Body

Name	Type	Description
`service_slug`*	string	Service slug to grant

Response Fields

Name	Type	Description
`id`*	string (UUID)	Service-access grant ID
`service_slug`*	string	Service slug
`service_name`*	string	Service name
`granted_at`*	string (date-time)	When granted

curl -X POST https://platform.ergondata.ai/v1/auth/api-keys/{key_id}/services \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"service_slug": "workflows"}'

Response

201 Created

{
  "id": "d4d5d6d7-e8e9-f0f1-0203-1a2b3c4d5e6f",
  "service_slug": "workflows",
  "service_name": "Workflows",
  "source": "direct",
  "granted_at": "2026-01-07T09:20:00Z"
}

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

Name	Type	Description
`key_id`*	string (UUID)	API key ID
`access_id`*	string (UUID)	Service-access grant ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/api-keys/{key_id}/services/{access_id} \
  -H "Authorization: Bearer {token}"

Response

204 No 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.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Request Body

Name	Type	Description
`name`*	string	Agent name (1–200 chars)
`description`	string \| null	Agent description

Response Fields

Name	Type	Description
`id`*	string (UUID)	Agent ID
`company_id`*	string (UUID)	Owning company
`name`*	string	Agent name
`description`*	string \| null	Agent description
`is_active`*	boolean	Whether the agent is active
`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,
  "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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Query Parameters

Name	Type	Description
`page`	integer	Page number (min 1)Default: `1`
`limit`	integer	Items per page (1–100)Default: `50`

curl "https://platform.ergondata.ai/v1/auth/companies/{company_id}/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,
      "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

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Agent ID
`company_id`*	string (UUID)	Owning company
`name`*	string	Agent name
`description`*	string \| null	Agent description
`is_active`*	boolean	Whether the agent is active
`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,
  "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

Update an agent's name, description, or active state.

Bearer token required.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

Request Body

Name	Type	Description
`name`	string \| null	New name (1–200 chars)
`description`	string \| null	New description
`is_active`	boolean \| null	Activate or deactivate

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

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/agents/{agent_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/v1/auth/agents/{agent_id}/permissions

List Agent Permissions

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

Bearer token required.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

Query Parameters

Name	Type	Description
`page`	integer	Page number (min 1)Default: `1`
`limit`	integer	Items per page (1–100)Default: `50`

curl "https://platform.ergondata.ai/v1/auth/agents/{agent_id}/permissions?page=1&limit=50" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "bf20c030-d040-e050-f060-a070b080c090",
      "permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0",
      "name": "workflows: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

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

Request Body

Name	Type	Description
`permission_id`*	string (UUID)	Permission to grant
`effect`	string	allow or denyDefault: `allow`
`resource`	string \| null	Resource path the grant applies to
`resource_id`	string (UUID) \| null	Specific resource instance ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Grant ID
`permission_id`*	string (UUID)	Permission ID
`name`*	string	Permission name
`resource`*	string	Resource the grant applies to
`effect`*	string	allow or deny
`is_system`*	boolean	Whether it is a built-in grant
`granted_at`*	string (date-time)	When granted

curl -X POST https://platform.ergondata.ai/v1/auth/agents/{agent_id}/permissions \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0", "effect": "allow"}'

Response

201 Created

{
  "id": "bf20c030-d040-e050-f060-a070b080c090",
  "permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0",
  "name": "workflows: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

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID
`pp_id`*	string (UUID)	Permission-grant ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/agents/{agent_id}/permissions/{pp_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/v1/auth/agents/{agent_id}/roles

List Agent Roles

List the roles assigned to an agent.

Bearer token required.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Assignment ID
`role_id`*	string (UUID)	Role ID
`name`*	string	Role name
`is_system`*	boolean	Whether it is a built-in role
`granted_at`*	string (date-time)	When assigned

curl https://platform.ergondata.ai/v1/auth/agents/{agent_id}/roles \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "c030d040-e050-f060-a070-b080c090d0a0",
    "role_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "name": "member",
    "is_system": true,
    "granted_at": "2026-01-08T12:10:00Z"
  }
]

POST/v1/auth/agents/{agent_id}/roles

Assign Agent Role

Assign a role to an agent.

Bearer token required.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

Request Body

Name	Type	Description
`role_id`*	string (UUID)	Role to assign

Response Fields

Name	Type	Description
`id`*	string (UUID)	Assignment ID
`role_id`*	string (UUID)	Role ID
`name`*	string	Role name
`is_system`*	boolean	Whether it is a built-in role
`granted_at`*	string (date-time)	When assigned

curl -X POST https://platform.ergondata.ai/v1/auth/agents/{agent_id}/roles \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"role_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"}'

Response

201 Created

{
  "id": "c030d040-e050-f060-a070-b080c090d0a0",
  "role_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "name": "member",
  "is_system": true,
  "granted_at": "2026-01-08T12:10:00Z"
}

DELETE/v1/auth/agents/{agent_id}/roles/{pr_id}

Remove Agent Role

Remove a role assignment from an agent.

Bearer token required.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID
`pr_id`*	string (UUID)	Role-assignment ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/agents/{agent_id}/roles/{pr_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/v1/auth/agents/{agent_id}/services

List Agent Services

List the services an agent has access to.

Bearer token required.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Service-access grant ID
`service_slug`*	string	Service slug
`service_name`*	string	Service name
`granted_at`*	string (date-time)	When granted

curl https://platform.ergondata.ai/v1/auth/agents/{agent_id}/services \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "d040e050-f060-a070-b080-c090d0a0e0b0",
    "service_slug": "workflows",
    "service_name": "Workflows",
    "source": "direct",
    "granted_at": "2026-01-08T12:15:00Z"
  }
]

POST/v1/auth/agents/{agent_id}/services

Grant Agent Service

Grant an agent access to a service by slug.

Bearer token required.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

Request Body

Name	Type	Description
`service_slug`*	string	Service slug to grant

Response Fields

Name	Type	Description
`id`*	string (UUID)	Service-access grant ID
`service_slug`*	string	Service slug
`service_name`*	string	Service name
`granted_at`*	string (date-time)	When granted

curl -X POST https://platform.ergondata.ai/v1/auth/agents/{agent_id}/services \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"service_slug": "workflows"}'

Response

201 Created

{
  "id": "d040e050-f060-a070-b080-c090d0a0e0b0",
  "service_slug": "workflows",
  "service_name": "Workflows",
  "source": "direct",
  "granted_at": "2026-01-08T12:15:00Z"
}

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

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID
`access_id`*	string (UUID)	Service-access grant ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/agents/{agent_id}/services/{access_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

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

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

Query Parameters

Name	Type	Description
`page`	integer	Page number (min 1)Default: `1`
`limit`	integer	Items per page (1–100)Default: `50`

curl "https://platform.ergondata.ai/v1/auth/agents/{agent_id}/principals?page=1&limit=50" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "e050f060-a070-b080-c090-d0a0e0b0f0c0",
      "principal_type": "member",
      "principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
      "principal_label": "Jane Doe",
      "granted_at": "2026-01-08T12:20:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50
}

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

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

Request Body

Name	Type	Description
`principal_type`*	string	Principal type ("member" or "api_key")
`principal_id`*	string (UUID)	Principal to authorize

Response Fields

Name	Type	Description
`id`*	string (UUID)	Link ID
`principal_type`*	string	Principal type
`principal_id`*	string (UUID)	Principal ID
`principal_label`*	string	Human-readable label
`granted_at`*	string (date-time)	When linked

curl -X POST https://platform.ergondata.ai/v1/auth/agents/{agent_id}/principals \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "principal_type": "member",
    "principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc"
  }'

Response

201 Created

{
  "id": "e050f060-a070-b080-c090-d0a0e0b0f0c0",
  "principal_type": "member",
  "principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
  "principal_label": "Jane Doe",
  "granted_at": "2026-01-08T12:20:00Z"
}

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

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID
`ap_id`*	string (UUID)	Agent-principal link ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/agents/{agent_id}/principals/{ap_id} \
  -H "Authorization: Bearer {token}"

Response

204 No 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

Name	Type	Description
`include_hidden`	boolean	Include hidden servicesDefault: `false`

Response Fields

Name	Type	Description
`id`*	string (UUID)	Service ID
`name`*	string	Service name
`slug`*	string	Service slug
`hidden`*	boolean	Whether the service is hidden
`required`	boolean	Whether the service is mandatory
`self_service`	boolean	Whether admins can self-enable
`stage`	string	Lifecycle stage (e.g. ga)

curl https://platform.ergondata.ai/v1/auth/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

Name	Type	Description
`service_slug`*	string	Service slug

Response Fields

Name	Type	Description
`id`*	string (UUID)	Permission ID
`name`*	string	Permission name
`is_system`*	boolean	Whether it is a built-in permission
`description`	string \| null	Permission description

curl https://platform.ergondata.ai/v1/auth/services/{service_slug}/permissions \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0",
    "name": "workflows: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

Name	Type	Description
`service_slug`*	string	Service slug

curl https://platform.ergondata.ai/v1/auth/services/{service_slug}/resource-types \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "resource_types": [
    {"id": "rt-1", "name": "Workflow", "slug": "workflow", "parent_id": null}
  ],
  "resource_type_edges": [],
  "permissions": []
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Service ID
`name`*	string	Service name
`slug`*	string	Service slug
`hidden`*	boolean	Whether the service is hidden

curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/available-services \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
    "name": "Workflows",
    "slug": "workflows",
    "hidden": false,
    "required": false,
    "self_service": true,
    "stage": "ga"
  }
]

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

List Company Services

List the services currently enabled for a company.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Service ID
`name`*	string	Service name
`slug`*	string	Service slug
`hidden`*	boolean	Whether the service is hidden

curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/services \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
    "name": "Workflows",
    "slug": "workflows",
    "hidden": false,
    "required": false,
    "self_service": true,
    "stage": "ga"
  }
]

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Permission ID
`name`*	string	Permission name
`is_system`*	boolean	Whether it is a built-in permission

curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/permissions \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0",
    "name": "workflows: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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Permission ID
`name`*	string	Permission name
`is_system`*	boolean	Whether it is a built-in permission

curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/iam-grantable-permissions \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0",
    "name": "iam:company:members:view",
    "is_system": true
  }
]

POST/v1/auth/companies/{company_id}/company-services/{service_id}

Enable Company Service

Enable a service for a company.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`service_id`*	string (UUID)	Service ID

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/company-services/{service_id} \
  -H "Authorization: Bearer {token}"

Response

201 Created

{
  "service_id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "service_slug": "workflows",
  "enabled": true
}

DELETE/v1/auth/companies/{company_id}/company-services/{service_id}

Disable Company Service

Disable a service for a company.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`service_id`*	string (UUID)	Service ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/company-services/{service_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/v1/auth/companies/{company_id}/feature-flags

List Feature Flags

List the feature flags resolved for a company.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Company ID

curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/feature-flags \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "beta_dashboard": true,
  "new_editor": false
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`key`*	string	Feature flag key

Request Body

Name	Type	Description
`value`*	boolean \| string \| number	New flag value

curl -X PUT https://platform.ergondata.ai/v1/auth/companies/{company_id}/feature-flags/{key} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"value": true}'

Response

200 OK

{
  "key": "beta_dashboard",
  "value": true
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`service_slug`*	string	Service slug

Query Parameters

Name	Type	Description
`page`	integer	Page number (min 1)Default: `1`
`limit`	integer	Items per page (1–100)Default: `50`

curl "https://platform.ergondata.ai/v1/auth/companies/{company_id}/services/{service_slug}/access?page=1&limit=50" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "f060a070-b080-c090-d0a0-e0b0f0c0a0b0",
      "principal_type": "member",
      "principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
      "principal_label": "Jane Doe",
      "granted_at": "2026-01-09T08:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`service_slug`*	string	Service slug

Query Parameters

Name	Type	Description
`principal_type`*	string	Principal type ("member", "api_key", or "agent")
`principal_id`*	string	Principal to grant

Response Fields

Name	Type	Description
`id`*	string (UUID)	Service-access grant ID
`principal_type`*	string	Principal type
`principal_id`*	string (UUID)	Principal ID
`principal_label`*	string	Human-readable label
`granted_at`*	string (date-time)	When granted

curl -X POST "https://platform.ergondata.ai/v1/auth/companies/{company_id}/services/{service_slug}/access?principal_type=member&principal_id={principal_id}" \
  -H "Authorization: Bearer {token}"

Response

201 Created

{
  "id": "f060a070-b080-c090-d0a0-e0b0f0c0a0b0",
  "principal_type": "member",
  "principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
  "principal_label": "Jane Doe",
  "granted_at": "2026-01-09T08:00:00Z"
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`service_slug`*	string	Service slug
`access_id`*	string (UUID)	Service-access grant ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/services/{service_slug}/access/{access_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/v1/auth/companies/{company_id}/conversation-agents

List Conversation Agents

List agents in a company that are available to participate in conversations (paginated).

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Query Parameters

Name	Type	Description
`page`	integer	Page number (min 1)Default: `1`
`limit`	integer	Items per page (1–100)Default: `50`

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/conversation-principals \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
      "principal_type": "member",
      "label": "Jane Doe"
    }
  ]
}

Grants & Service Access

Review and revoke a company's effective permission grants and service-access entitlements.

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

List Org Grants

List every permission grant in a company across all principals (paginated).

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Query Parameters

Name	Type	Description
`page`	integer	Page number (min 1)Default: `1`
`limit`	integer	Items per page (1–100)Default: `50`

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: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, with optional search.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Query Parameters

Name	Type	Description
`page`	integer	Page number (min 1)Default: `1`
`limit`	integer	Items per page (1–100)Default: `25`
`q`	string \| null	Search query (max 200 chars)

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:items:create", "resource": "*", "effect": "allow"}
      ]
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 25
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Request Body

Name	Type	Description
`operations`*	array	Grouped operations whose full Cartesian expansion is at most 200 grants

Response Fields

Name	Type	Description
`results`*	array	Outcomes ordered by operation, resource, then permission ID
`summary`*	object	created, already_exists, and failed counts

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/grants/batch \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [{
      "client_ref": "onboarding",
      "principal_type": "member",
      "principal_id": "{member_principal_id}",
      "resources": ["org/{company_id}"],
      "permission_ids": ["{members_view_permission_id}", "{services_view_permission_id}"],
      "effect": "allow"
    }]
  }'

Response

200 OK

{
  "results": [{
    "index": 0,
    "client_ref": "onboarding",
    "status": "created",
    "principal_type": "member",
    "principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
    "permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0",
    "resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe",
    "effect": "allow",
    "grant": {
      "id": "a0b0c0d0-e0f0-1020-3040-5060708090a0",
      "permission_id": "8d9e0f10-2030-4050-6070-8090a0b0c0d0",
      "name": "iam:company:members:view",
      "resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe",
      "effect": "allow",
      "is_system": false,
      "granted_at": "2026-07-15T16:30:00Z"
    },
    "error_status": null,
    "error_detail": null,
    "side_effect_error_status": null,
    "side_effect_error_detail": null
  }],
  "summary": {"created": 1, "already_exists": 0, "failed": 0}
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Request Body

Name	Type	Description
`operations`*	array	BatchGrantOperation[]; same grouped shape as Create Org Grants Batch

Response Fields

Name	Type	Description
`results`*	array	Ordered BatchGrantResult[] partial outcomes
`summary`*	object	created, already_exists, and failed counts

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/access/grants/batch \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"operations":[{"principal_type":"member","principal_id":"{principal_id}","resources":["org/{company_id}/role/{resource_id}"],"permission_ids":["{permission_id}"]}]}'

Response

200 OK

{
  "results": [{"index": 0, "status": "created", "client_ref": null}],
  "summary": {"created": 1, "already_exists": 0, "failed": 0}
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Request Body

Name	Type	Description
`operations`*	array	BatchGrantOperation[]; same grouped shape as Create Org Grants Batch

Response Fields

Name	Type	Description
`results`*	array	Ordered BatchGrantResult[] partial outcomes
`summary`*	object	created, already_exists, and failed counts

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/teams/access/grants/batch \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"operations":[{"principal_type":"member","principal_id":"{principal_id}","resources":["org/{company_id}/team/{resource_id}"],"permission_ids":["{permission_id}"]}]}'

Response

200 OK

{
  "results": [{"index": 0, "status": "created", "client_ref": null}],
  "summary": {"created": 1, "already_exists": 0, "failed": 0}
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Request Body

Name	Type	Description
`operations`*	array	BatchGrantOperation[]; same grouped shape as Create Org Grants Batch

Response Fields

Name	Type	Description
`results`*	array	Ordered BatchGrantResult[] partial outcomes
`summary`*	object	created, already_exists, and failed counts

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/api-keys/access/grants/batch \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"operations":[{"principal_type":"member","principal_id":"{principal_id}","resources":["org/{company_id}/api-key/{resource_id}"],"permission_ids":["{permission_id}"]}]}'

Response

200 OK

{
  "results": [{"index": 0, "status": "created", "client_ref": null}],
  "summary": {"created": 1, "already_exists": 0, "failed": 0}
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Request Body

Name	Type	Description
`operations`*	array	BatchGrantOperation[]; same grouped shape as Create Org Grants Batch

Response Fields

Name	Type	Description
`results`*	array	Ordered BatchGrantResult[] partial outcomes
`summary`*	object	created, already_exists, and failed counts

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/agents/access/grants/batch \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"operations":[{"principal_type":"member","principal_id":"{principal_id}","resources":["org/{company_id}/agent/{resource_id}"],"permission_ids":["{permission_id}"]}]}'

Response

200 OK

{
  "results": [{"index": 0, "status": "created", "client_ref": null}],
  "summary": {"created": 1, "already_exists": 0, "failed": 0}
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Request Body

Name	Type	Description
`operations`*	array	BatchGrantOperation[]; same grouped shape as Create Org Grants Batch

Response Fields

Name	Type	Description
`results`*	array	Ordered BatchGrantResult[] partial outcomes
`summary`*	object	created, already_exists, and failed counts

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/access/grants/batch \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"operations":[{"principal_type":"member","principal_id":"{principal_id}","resources":["org/{company_id}/member/{resource_id}"],"permission_ids":["{permission_id}"]}]}'

Response

200 OK

{
  "results": [{"index": 0, "status": "created", "client_ref": null}],
  "summary": {"created": 1, "already_exists": 0, "failed": 0}
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`grant_id`*	string (UUID)	Grant ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/grants/{grant_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Query Parameters

Name	Type	Description
`page`	integer	Page number (min 1)Default: `1`
`limit`	integer	Items per page (1–100)Default: `50`
`q`	string \| null	Search query (max 200 chars)

curl "https://platform.ergondata.ai/v1/auth/companies/{company_id}/service-access?page=1&limit=50" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "b0c0d0e0-f010-2030-4050-60708090a0b0",
      "principal_type": "member",
      "principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
      "service_slug": "workflows",
      "granted_at": "2026-01-09T09:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`access_id`*	string (UUID)	Service-access grant ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/service-access/{access_id} \
  -H "Authorization: Bearer {token}"

Response

204 No 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

Name	Type	Description
`token`*	string	Invitation token
`company_name`*	string	Inviting company name
`company_slug`*	string	Inviting company slug
`inviter_name`*	string \| null	Who sent the invite
`role`	string \| null	Proposed single role
`roles`	array<string>	Proposed roles
`expires_at`*	string (date-time)	Expiry timestamp

curl https://platform.ergondata.ai/v1/auth/invitations/mine \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "token": "inv-token-abc123",
    "company_name": "Acme Corp",
    "company_slug": "acme-corp",
    "inviter_name": "Jane Doe",
    "role": "member",
    "roles": ["member"],
    "service_slugs": ["workflows"],
    "expires_at": "2026-02-01T00:00:00Z"
  }
]

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

Name	Type	Description
`token`*	string	Invitation token

Response Fields

Name	Type	Description
`id`*	string (UUID)	Invitation ID
`email`*	string	Invited email
`company_name`*	string	Inviting company name
`company_slug`*	string	Inviting company slug
`needs_registration`*	boolean	Whether the recipient must register first
`roles`	array<string>	Proposed roles

curl https://platform.ergondata.ai/v1/auth/invitations/{token}

Response

200 OK

{
  "id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
  "email": "[email protected]",
  "company_name": "Acme Corp",
  "company_slug": "acme-corp",
  "needs_registration": true,
  "role": "member",
  "roles": ["member"],
  "service_slugs": ["workflows"]
}

POST/v1/auth/invitations/{token}/accept

Accept Invitation

Accept an invitation and join the company as the authenticated user.

Bearer token required.

Path Parameters

Name	Type	Description
`token`*	string	Invitation token

curl -X POST https://platform.ergondata.ai/v1/auth/invitations/{token}/accept \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "status": "accepted"
}

POST/v1/auth/companies/{company_id}/invitations/{invitation_id}/resend

Resend Invitation

Resend the invitation email with a fresh token and extended expiry.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`invitation_id`*	string (UUID)	Invitation ID

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/invitations/{invitation_id}/resend \
  -H "Authorization: Bearer {token}"

Response

200 OK

{}

Permission Checks

Evaluate whether the authenticated caller is authorized for an action.

POST/v1/auth/check-permission

Check Permission

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

Bearer token required.

Request Body

Name	Type	Description
`company_id`*	string	Company context to evaluate in
`action`*	string	Permission/action to check
`resource`*	string	Resource the action targets

Response Fields

Name	Type	Description
`allowed`*	boolean	Whether the action is permitted
`reason`	string \| null	Explanation when denied

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

Name	Type	Description
`company_id`*	string	Company context to evaluate in
`action`*	string	Permission/action to check
`resources`*	array<string>	Resources to evaluate the action against

Response Fields

Name	Type	Description
`results`*	object<string, boolean>	Map of resource → whether allowed
`reason`	string \| null	Explanation when denied

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:items:update",
    "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

Name	Type	Description
`company_id`*	string	Company context to evaluate in
`actions`*	array<string>	Permissions/actions to check
`resources`*	array<string>	Resources to evaluate each action against

Response Fields

Name	Type	Description
`results`*	object<string, object<string, boolean>>	Map of resource → action → whether allowed
`reason`	string \| null	Explanation when all checks are denied

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
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Query Parameters

Name	Type	Description
`event_type`	string \| null	Filter by event type
`page`	integer	Page number (min 1)Default: `1`
`limit`	integer	Items per page (1–100)Default: `50`

Response Fields

Name	Type	Description
`items`*	array	Activity events
`total`*	integer	Total events
`page`*	integer	Current page
`limit`*	integer	Page size

curl "https://platform.ergondata.ai/v1/auth/companies/{company_id}/activity?page=1&limit=50" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "11112222-3333-4444-5555-666677778888",
      "event_type": "member.added",
      "actor_label": "Jane Doe",
      "actor_type": "member",
      "data": {"user_id": "b10f8a92-3c4d-5e6f-7890-123456789abc"},
      "created_at": "2026-01-09T10:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50
}

GET/v1/auth/activity/{event_id}

Get Activity Event

Retrieve a single audit-log event by ID.

Bearer token required.

Path Parameters

Name	Type	Description
`event_id`*	string	Event ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Event ID
`event_type`*	string	Event type
`actor_label`	string \| null	Actor display label
`actor_type`	string \| null	Actor type
`data`	object \| null	Event payload
`created_at`*	string (date-time)	When it occurred

curl https://platform.ergondata.ai/v1/auth/activity/{event_id} \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "id": "11112222-3333-4444-5555-666677778888",
  "event_type": "member.added",
  "actor_label": "Jane Doe",
  "actor_type": "member",
  "correlation_id": null,
  "data": {"user_id": "b10f8a92-3c4d-5e6f-7890-123456789abc"},
  "created_at": "2026-01-09T10:00:00Z"
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Allowlist ID
`company_id`*	string (UUID)	Owning company
`slug`*	string	Allowlist slug
`name`*	string	Allowlist name
`entries`*	array	CIDR entries
`created_at`*	string (date-time)	Creation timestamp

curl https://platform.ergondata.ai/v1/companies/{company_id}/ip-allowlists \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "1c2d3e4f-5061-7283-94a5-b6c7d8e9f0a1",
    "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
    "slug": "office",
    "name": "Office network",
    "entries": [
      {"id": "e1e2e3e4-0506-0708-090a-0b0c0d0e0f10", "cidr": "203.0.113.0/24", "label": "HQ"}
    ],
    "created_at": "2026-01-10T08:00:00Z"
  }
]

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Request Body

Name	Type	Description
`slug`*	string	Allowlist slug (1–100 chars)
`name`*	string	Allowlist name (min 1 char)
`entries`	array	CIDR entries

curl -X POST https://platform.ergondata.ai/v1/companies/{company_id}/ip-allowlists \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "office",
    "name": "Office network",
    "entries": [{"cidr": "203.0.113.0/24", "label": "HQ"}]
  }'

Response

201 Created

{
  "id": "1c2d3e4f-5061-7283-94a5-b6c7d8e9f0a1",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "slug": "office",
  "name": "Office network",
  "entries": [
    {"id": "e1e2e3e4-0506-0708-090a-0b0c0d0e0f10", "cidr": "203.0.113.0/24", "label": "HQ"}
  ],
  "created_at": "2026-01-10T08:00:00Z"
}

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

Name	Type	Description
`allowlist_id`*	string (UUID)	Allowlist ID

Request Body

Name	Type	Description
`name`	string \| null	New name
`entries`	array \| null	Replacement CIDR entries

curl -X PATCH https://platform.ergondata.ai/v1/ip-allowlists/{allowlist_id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Office network (updated)"}'

Response

200 OK

{
  "id": "1c2d3e4f-5061-7283-94a5-b6c7d8e9f0a1",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "slug": "office",
  "name": "Office network (updated)",
  "entries": [
    {"id": "e1e2e3e4-0506-0708-090a-0b0c0d0e0f10", "cidr": "203.0.113.0/24", "label": "HQ"}
  ],
  "created_at": "2026-01-10T08:00:00Z"
}

DELETE/v1/ip-allowlists/{allowlist_id}

Delete IP Allowlist

Delete an IP allowlist.

Bearer token required.

Path Parameters

Name	Type	Description
`allowlist_id`*	string (UUID)	Allowlist ID

curl -X DELETE https://platform.ergondata.ai/v1/ip-allowlists/{allowlist_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Response Fields

Name	Type	Description
`principal_id`*	string (UUID)	Principal ID
`allowlists`*	array	Allowlists bound to the principal

curl https://platform.ergondata.ai/v1/companies/{company_id}/ip-allowlist-assignments \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
    "allowlists": [
      {
        "id": "1c2d3e4f-5061-7283-94a5-b6c7d8e9f0a1",
        "slug": "office",
        "name": "Office network",
        "entries": [],
        "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
        "created_at": "2026-01-10T08:00:00Z"
      }
    ]
  }
]

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`principal_id`*	string (UUID)	Principal ID

Request Body

Name	Type	Description
`allowlist_ids`*	array<string (UUID)>	Allowlist IDs to bind (empty array clears)

Response Fields

Name	Type	Description
`principal_id`*	string (UUID)	Principal ID
`allowlists`*	array	Allowlists now bound

curl -X PUT https://platform.ergondata.ai/v1/companies/{company_id}/ip-allowlist-assignments/{principal_id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"allowlist_ids": ["1c2d3e4f-5061-7283-94a5-b6c7d8e9f0a1"]}'

Response

200 OK

{
  "principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
  "allowlists": [
    {
      "id": "1c2d3e4f-5061-7283-94a5-b6c7d8e9f0a1",
      "slug": "office",
      "name": "Office network",
      "entries": [],
      "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
      "created_at": "2026-01-10T08:00:00Z"
    }
  ]
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`principal_id`*	string (UUID)	Principal ID

curl -X DELETE https://platform.ergondata.ai/v1/companies/{company_id}/ip-allowlist-assignments/{principal_id} \
  -H "Authorization: Bearer {token}"

Response

204 No 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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Config ID
`company_id`*	string (UUID)	Owning company
`slug`*	string	Config slug
`name`*	string	Config name
`timezone`*	string	IANA timezone
`slots`*	array	Weekly time slots
`created_at`*	string (date-time)	Creation timestamp

curl https://platform.ergondata.ai/v1/companies/{company_id}/working-hours \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "2d3e4f50-6172-8394-a5b6-c7d8e9f0a1b2",
    "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
    "slug": "business-hours",
    "name": "Business Hours",
    "timezone": "America/Sao_Paulo",
    "slots": [
      {"id": "5a5b5c5d-0102-0304-0506-0708090a0b0c", "day_of_week": 0, "start_time": "09:00", "end_time": "17:00"}
    ],
    "created_at": "2026-01-10T09:00:00Z"
  }
]

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

Create Working Hours

Create a working-hours configuration with weekly slots.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Request Body

Name	Type	Description
`slug`*	string	Config slug (1–100 chars)
`name`*	string	Config name (min 1 char)
`timezone`	string	IANA timezone (1–50 chars)Default: `UTC`
`slots`	array	Weekly time slots

curl -X POST https://platform.ergondata.ai/v1/companies/{company_id}/working-hours \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "business-hours",
    "name": "Business Hours",
    "timezone": "America/Sao_Paulo",
    "slots": [{"day_of_week": 0, "start_time": "09:00", "end_time": "17:00"}]
  }'

Response

201 Created

{
  "id": "2d3e4f50-6172-8394-a5b6-c7d8e9f0a1b2",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "slug": "business-hours",
  "name": "Business Hours",
  "timezone": "America/Sao_Paulo",
  "slots": [
    {"id": "5a5b5c5d-0102-0304-0506-0708090a0b0c", "day_of_week": 0, "start_time": "09:00", "end_time": "17:00"}
  ],
  "created_at": "2026-01-10T09:00:00Z"
}

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

Name	Type	Description
`config_id`*	string (UUID)	Config ID

Request Body

Name	Type	Description
`name`	string \| null	New name
`timezone`	string \| null	New IANA timezone
`slots`	array \| null	Replacement weekly slots

curl -X PATCH https://platform.ergondata.ai/v1/working-hours/{config_id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Extended Hours"}'

Response

200 OK

{
  "id": "2d3e4f50-6172-8394-a5b6-c7d8e9f0a1b2",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "slug": "business-hours",
  "name": "Extended Hours",
  "timezone": "America/Sao_Paulo",
  "slots": [
    {"id": "5a5b5c5d-0102-0304-0506-0708090a0b0c", "day_of_week": 0, "start_time": "09:00", "end_time": "17:00"}
  ],
  "created_at": "2026-01-10T09:00:00Z"
}

DELETE/v1/working-hours/{config_id}

Delete Working Hours

Delete a working-hours configuration.

Bearer token required.

Path Parameters

Name	Type	Description
`config_id`*	string (UUID)	Config ID

curl -X DELETE https://platform.ergondata.ai/v1/working-hours/{config_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/v1/working-hours/granted

List Granted Working Hours

Return the working-hours configs available to the caller's company for phase binding. Company is derived from the bearer token.

Bearer token required.

curl https://platform.ergondata.ai/v1/working-hours/granted \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "configs": [
    {
      "id": "2d3e4f50-6172-8394-a5b6-c7d8e9f0a1b2",
      "slug": "business-hours",
      "name": "Business Hours",
      "timezone": "America/Sao_Paulo"
    }
  ]
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Response Fields

Name	Type	Description
`principal_id`*	string (UUID)	Principal ID
`configs`*	array	Assigned configs with enforcement mode
`warnings`	array<string>	Assignment warnings

curl https://platform.ergondata.ai/v1/companies/{company_id}/working-hours-assignments \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
    "configs": [
      {
        "id": "2d3e4f50-6172-8394-a5b6-c7d8e9f0a1b2",
        "slug": "business-hours",
        "name": "Business Hours",
        "enforcement_mode": "platform_access"
      }
    ],
    "warnings": []
  }
]

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`principal_id`*	string (UUID)	Principal ID

Request Body

Name	Type	Description
`config_ids`	array<string (UUID)> \| null	Config IDs to assign (routing-only enforcement)
`assignments`	array \| null	Per-config assignments with enforcement mode

Response Fields

Name	Type	Description
`principal_id`*	string (UUID)	Principal ID
`configs`*	array	Configs now assigned
`warnings`	array<string>	Assignment warnings

curl -X PUT https://platform.ergondata.ai/v1/companies/{company_id}/working-hours-assignments/{principal_id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "assignments": [
      {"config_id": "2d3e4f50-6172-8394-a5b6-c7d8e9f0a1b2", "enforcement_mode": "platform_access"}
    ]
  }'

Response

200 OK

{
  "principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
  "configs": [
    {
      "id": "2d3e4f50-6172-8394-a5b6-c7d8e9f0a1b2",
      "slug": "business-hours",
      "name": "Business Hours",
      "enforcement_mode": "platform_access"
    }
  ],
  "warnings": []
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`principal_id`*	string (UUID)	Principal ID

curl -X DELETE https://platform.ergondata.ai/v1/companies/{company_id}/working-hours-assignments/{principal_id} \
  -H "Authorization: Bearer {token}"

Response

204 No 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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Status type ID
`company_id`*	string (UUID)	Owning company
`slug`*	string	Status type slug
`name`*	string	Status type name
`color`*	string \| null	Hex color
`icon`*	string \| null	Icon name
`is_available`*	boolean	Counts as available
`is_default`*	boolean	Default for new principals
`position`*	integer	Sort order
`created_at`*	string (date-time)	Creation timestamp

curl https://platform.ergondata.ai/v1/companies/{company_id}/status-types \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "3e4f5061-7283-94a5-b6c7-d8e9f0a1b2c3",
    "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
    "slug": "available",
    "name": "Available",
    "color": "#22c55e",
    "icon": "circle",
    "is_available": true,
    "is_default": true,
    "position": 0,
    "created_at": "2026-01-11T08:00:00Z"
  }
]

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

Create Status Type

Create a principal status type.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Request Body

Name	Type	Description
`slug`*	string	Status type slug (1–50 chars)
`name`*	string	Status type name (1–200 chars)
`color`	string \| null	Hex color (max 7 chars)
`icon`	string \| null	Icon name (max 50 chars)
`is_available`	boolean	Whether it counts as availableDefault: `false`
`is_default`	boolean	Whether it is the defaultDefault: `false`
`position`	integer	Sort orderDefault: `0`

curl -X POST https://platform.ergondata.ai/v1/companies/{company_id}/status-types \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"slug": "busy", "name": "Busy", "color": "#ef4444", "is_available": false}'

Response

201 Created

{
  "id": "4f506172-8394-a5b6-c7d8-e9f0a1b2c3d4",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "slug": "busy",
  "name": "Busy",
  "color": "#ef4444",
  "icon": null,
  "is_available": false,
  "is_default": false,
  "position": 0,
  "created_at": "2026-01-11T08:05:00Z"
}

PATCH/v1/status-types/{status_type_id}

Update Status Type

Update a status type's attributes.

Bearer token required.

Path Parameters

Name	Type	Description
`status_type_id`*	string (UUID)	Status type ID

Request Body

Name	Type	Description
`name`	string \| null	New name (1–200 chars)
`color`	string \| null	New hex color
`icon`	string \| null	New icon name
`is_available`	boolean \| null	Counts as available
`is_default`	boolean \| null	Is the default
`position`	integer \| null	Sort order

curl -X PATCH https://platform.ergondata.ai/v1/status-types/{status_type_id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "In a meeting"}'

Response

200 OK

{
  "id": "4f506172-8394-a5b6-c7d8-e9f0a1b2c3d4",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "slug": "busy",
  "name": "In a meeting",
  "color": "#ef4444",
  "icon": null,
  "is_available": false,
  "is_default": false,
  "position": 0,
  "created_at": "2026-01-11T08:05:00Z"
}

DELETE/v1/status-types/{status_type_id}

Delete Status Type

Delete a status type.

Bearer token required.

Path Parameters

Name	Type	Description
`status_type_id`*	string (UUID)	Status type ID

curl -X DELETE https://platform.ergondata.ai/v1/status-types/{status_type_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Status record ID
`company_id`*	string (UUID)	Company ID
`principal_id`*	string (UUID)	Principal ID
`status_type_id`*	string (UUID)	Current status type
`status_type_name`	string \| null	Status type name
`custom_message`*	string \| null	Custom status message
`is_available`	boolean \| null	Whether available
`updated_at`*	string (date-time)	Last updated

curl https://platform.ergondata.ai/v1/companies/{company_id}/principal-statuses \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "50617283-94a5-b6c7-d8e9-f0a1b2c3d4e5",
    "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
    "principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
    "status_type_id": "3e4f5061-7283-94a5-b6c7-d8e9f0a1b2c3",
    "status_type_name": "Available",
    "status_type_color": "#22c55e",
    "custom_message": null,
    "is_available": true,
    "updated_at": "2026-01-11T09:00:00Z"
  }
]

PUT/v1/principal-statuses/me

Set My Status

Set the authenticated principal's current availability status.

Bearer token required.

Request Body

Name	Type	Description
`status_type_id`*	string (UUID)	Status type to apply
`custom_message`	string \| null	Optional custom status message

Response Fields

Name	Type	Description
`id`*	string (UUID)	Status record ID
`principal_id`*	string (UUID)	Principal ID
`status_type_id`*	string (UUID)	Applied status type
`custom_message`*	string \| null	Custom message
`updated_at`*	string (date-time)	Last updated

curl -X PUT https://platform.ergondata.ai/v1/principal-statuses/me \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "status_type_id": "4f506172-8394-a5b6-c7d8-e9f0a1b2c3d4",
    "custom_message": "Back at 2pm"
  }'

Response

200 OK

{
  "id": "50617283-94a5-b6c7-d8e9-f0a1b2c3d4e5",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
  "status_type_id": "4f506172-8394-a5b6-c7d8-e9f0a1b2c3d4",
  "status_type_name": "Busy",
  "custom_message": "Back at 2pm",
  "is_available": false,
  "updated_at": "2026-01-11T09:10:00Z"
}

PUT/v1/principal-statuses/{principal_id}

Set Principal Status

Set another principal's current availability status (requires permission).

Bearer token required.

Path Parameters

Name	Type	Description
`principal_id`*	string (UUID)	Principal ID

Request Body

Name	Type	Description
`status_type_id`*	string (UUID)	Status type to apply
`custom_message`	string \| null	Optional custom status message

Response Fields

Name	Type	Description
`id`*	string (UUID)	Status record ID
`principal_id`*	string (UUID)	Principal ID
`status_type_id`*	string (UUID)	Applied status type
`custom_message`*	string \| null	Custom message
`updated_at`*	string (date-time)	Last updated

curl -X PUT https://platform.ergondata.ai/v1/principal-statuses/{principal_id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"status_type_id": "4f506172-8394-a5b6-c7d8-e9f0a1b2c3d4"}'

Response

200 OK

{
  "id": "50617283-94a5-b6c7-d8e9-f0a1b2c3d4e5",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
  "status_type_id": "4f506172-8394-a5b6-c7d8-e9f0a1b2c3d4",
  "status_type_name": "Busy",
  "custom_message": null,
  "is_available": false,
  "updated_at": "2026-01-11T09:15:00Z"
}

Teams

Teams are first-class principals that group members (and, optionally, nested teams). A team has no credentials of its own, but it holds roles, permission grants, service access, and zone connections directly — and its members inherit all of them through the subject graph. Prefer permission → role → team → members over per-member grants so onboarding is a single assignment. Team management is gated by the iam:company:teams:* permissions; granting and revoking on a team principal additionally use iam:company:grants:*.

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Team ID
`company_id`*	string (UUID)	Owning company
`name`*	string	Team name
`description`*	string \| null	Optional description
`parent_team_id`*	string (UUID) \| null	Parent team, if nested
`principal_id`*	string (UUID) \| null	The team's principal
`member_count`*	integer	Number of members
`created_at`*	string (date-time)	Creation timestamp

curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/teams \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "7ea11000-0000-4000-8000-000000000001",
    "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
    "name": "Billing",
    "description": "Finance & billing operators",
    "parent_team_id": null,
    "principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
    "member_count": 4,
    "created_at": "2026-01-10T12:00:00Z"
  }
]

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Team ID
`company_id`*	string (UUID)	Owning company
`name`*	string	Team name
`description`*	string \| null	Optional description
`parent_team_id`*	string (UUID) \| null	Parent team, if nested
`principal_id`*	string (UUID) \| null	The team's principal
`member_count`*	integer	Number of members
`created_at`*	string (date-time)	Creation timestamp

curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/teams/manageable \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "7ea11000-0000-4000-8000-000000000001",
    "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
    "name": "Billing",
    "description": "Finance & billing operators",
    "parent_team_id": null,
    "principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
    "member_count": 4,
    "created_at": "2026-01-10T12:00:00Z"
  }
]

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Request Body

Name	Type	Description
`name`*	string	Team name
`description`	string \| null	Optional description
`parent_team_id`	string (UUID) \| null	Parent team for nesting

Response Fields

Name	Type	Description
`id`*	string (UUID)	New team ID
`principal_id`*	string (UUID) \| null	The team's principal
`name`*	string	Team name
`member_count`*	integer	Member count (0 at creation)

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/teams \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Billing", "description": "Finance & billing operators"}'

Response

201 Created

{
  "id": "7ea11000-0000-4000-8000-000000000001",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "name": "Billing",
  "description": "Finance & billing operators",
  "parent_team_id": null,
  "principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
  "member_count": 0,
  "created_at": "2026-01-10T12:00:00Z"
}

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

Name	Type	Description
`team_id`*	string (UUID)	Team ID

Request Body

Name	Type	Description
`name`	string \| null	New name
`description`	string \| null	New description
`parent_team_id`	string (UUID) \| null	New parent team (null detaches)

Response Fields

Name	Type	Description
`id`*	string (UUID)	Team ID
`name`*	string	Updated name
`parent_team_id`*	string (UUID) \| null	Updated parent

curl -X PATCH https://platform.ergondata.ai/v1/auth/teams/{team_id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Billing & Collections"}'

Response

200 OK

{
  "id": "7ea11000-0000-4000-8000-000000000001",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "name": "Billing & Collections",
  "description": "Finance & billing operators",
  "parent_team_id": null,
  "principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
  "member_count": 4,
  "created_at": "2026-01-10T12:00:00Z"
}

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

Name	Type	Description
`team_id`*	string (UUID)	Team ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/teams/{team_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

// 204 No Content

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

Name	Type	Description
`team_id`*	string (UUID)	Team ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Membership row ID
`member_principal_id`*	string (UUID)	The member principal
`principal_type`*	string	member \| agent \| api_key \| team
`label`*	string \| null	Display label
`created_at`*	string (date-time)	When added

curl https://platform.ergondata.ai/v1/auth/teams/{team_id}/members \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "11111111-0000-4000-8000-000000000001",
    "member_principal_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "principal_type": "member",
    "label": "[email protected]",
    "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

Name	Type	Description
`team_id`*	string (UUID)	Team ID

Request Body

Name	Type	Description
`member_principal_id`*	string (UUID)	Principal to add

Response Fields

Name	Type	Description
`id`*	string (UUID)	Membership row ID
`member_principal_id`*	string (UUID)	Added principal
`principal_type`*	string	Kind of principal added

curl -X POST https://platform.ergondata.ai/v1/auth/teams/{team_id}/members \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"member_principal_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"}'

Response

201 Created

{
  "id": "11111111-0000-4000-8000-000000000001",
  "member_principal_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "principal_type": "member",
  "label": "[email protected]",
  "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

Name	Type	Description
`team_id`*	string (UUID)	Team ID
`tm_id`*	string (UUID)	Membership row ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/teams/{team_id}/members/{tm_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

// 204 No Content

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

Name	Type	Description
`team_id`*	string (UUID)	Team ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Assignment row ID
`role_id`*	string (UUID)	Assigned role
`name`*	string	Role name
`is_system`*	boolean	Whether it's a built-in role
`granted_at`*	string (date-time)	When assigned

curl https://platform.ergondata.ai/v1/auth/teams/{team_id}/roles \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "22222222-0000-4000-8000-000000000001",
    "role_id": "33333333-0000-4000-8000-000000000001",
    "name": "workflow-operator",
    "is_system": false,
    "granted_at": "2026-01-10T12:06:00Z"
  }
]

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

Name	Type	Description
`team_id`*	string (UUID)	Team ID

Request Body

Name	Type	Description
`role_id`*	string (UUID)	Role to assign

Response Fields

Name	Type	Description
`id`*	string (UUID)	Assignment row ID
`role_id`*	string (UUID)	Assigned role
`name`*	string	Role name

curl -X POST https://platform.ergondata.ai/v1/auth/teams/{team_id}/roles \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"role_id": "33333333-0000-4000-8000-000000000001"}'

Response

201 Created

{
  "id": "22222222-0000-4000-8000-000000000001",
  "role_id": "33333333-0000-4000-8000-000000000001",
  "name": "workflow-operator",
  "is_system": false,
  "granted_at": "2026-01-10T12:06:00Z"
}

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

Name	Type	Description
`team_id`*	string (UUID)	Team ID
`pr_id`*	string (UUID)	Role-assignment row ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/teams/{team_id}/roles/{pr_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

// 204 No Content

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

Name	Type	Description
`team_id`*	string (UUID)	Team ID

Response Fields

Name	Type	Description
`items`*	GrantedPermission[]	Direct permission grants
`total`*	integer	Total direct grants

curl https://platform.ergondata.ai/v1/auth/teams/{team_id}/permissions \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "44444444-0000-4000-8000-000000000001",
      "permission_id": "55555555-0000-4000-8000-000000000001",
      "name": "workflows:workflows:view",
      "resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/folder/f1/workflow/w1",
      "effect": "allow",
      "is_system": false,
      "granted_at": "2026-01-10T12:07:00Z"
    }
  ],
  "total": 1
}

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

Name	Type	Description
`team_id`*	string (UUID)	Team ID

Request Body

Name	Type	Description
`permission_id`*	string (UUID)	Permission to grant
`resource`	string \| null	Resource path; resolved from resource_id if omitted
`resource_id`	string (UUID) \| null	Resource id (alternative to resource)
`effect`	string	allow \| denyDefault: `allow`

Response Fields

Name	Type	Description
`id`*	string (UUID)	Grant row ID
`permission_id`*	string (UUID)	Permission granted
`resource`*	string	Resource path
`effect`*	string	allow \| deny

curl -X POST https://platform.ergondata.ai/v1/auth/teams/{team_id}/permissions \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "permission_id": "55555555-0000-4000-8000-000000000001",
    "resource": "org/{company_id}/folder/{folder_id}/workflow/{workflow_id}",
    "effect": "allow"
  }'

Response

201 Created

{
  "id": "44444444-0000-4000-8000-000000000001",
  "permission_id": "55555555-0000-4000-8000-000000000001",
  "name": "workflows:workflows:view",
  "resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/folder/f1/workflow/w1",
  "effect": "allow",
  "is_system": false,
  "granted_at": "2026-01-10T12:07:00Z"
}

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

Name	Type	Description
`team_id`*	string (UUID)	Team ID
`pp_id`*	string (UUID)	Grant row ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/teams/{team_id}/permissions/{pp_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

// 204 No Content

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

Name	Type	Description
`team_id`*	string (UUID)	Team ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Service-access row ID
`service_slug`*	string	Service slug (e.g. workflows)
`service_name`*	string	Human-readable service name
`source`*	string \| null	direct or the role it was inherited from
`granted_at`*	string (date-time)	When granted

curl https://platform.ergondata.ai/v1/auth/teams/{team_id}/services \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "66666666-0000-4000-8000-000000000001",
    "service_slug": "workflows",
    "service_name": "Workflows",
    "granted_at": "2026-01-10T12:08:00Z",
    "source": "direct"
  }
]

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

Name	Type	Description
`team_id`*	string (UUID)	Team ID

Request Body

Name	Type	Description
`service_slug`*	string	Service slug to grant

Response Fields

Name	Type	Description
`id`*	string (UUID)	Service-access row ID
`service_slug`*	string	Granted service
`service_name`*	string	Service name

curl -X POST https://platform.ergondata.ai/v1/auth/teams/{team_id}/services \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"service_slug": "workflows"}'

Response

201 Created

{
  "id": "66666666-0000-4000-8000-000000000001",
  "service_slug": "workflows",
  "service_name": "Workflows",
  "granted_at": "2026-01-10T12:08:00Z",
  "source": null
}

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

Name	Type	Description
`team_id`*	string (UUID)	Team ID
`access_id`*	string (UUID)	Service-access row ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/teams/{team_id}/services/{access_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

// 204 No 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. 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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Query Parameters

Name	Type	Description
`subject_type`	string	member \| api_key \| agent \| team \| role
`subject_id`	string (UUID)	Subject id (with subject_type)
`subject`	string	Subject ERN/path (alternative to the pair)
`q`	string	Filter by target resource path or service
`limit`	integer	Page size (1–200)
`offset`	integer	Pagination offsetDefault: `0`

Response Fields

Name	Type	Description
`connections`*	array	Active connection entries
`pending_requests`*	array	Outgoing requests awaiting approval
`total`*	integer \| null	Total active connections ignoring paging

curl "https://platform.ergondata.ai/v1/auth/companies/{company_id}/connections?subject_type=team&subject_id={team_id}" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "connections": [
    {
      "id": "c1c1c1c1-0000-4000-8000-000000000001",
      "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
      "principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
      "role_id": null,
      "target_service": "workflows",
      "target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/folder/f1/workflow/w1",
      "target_ern": "ern:workflows:org/c0ffee00-cafe-babe-dead-beefcafebabe/folder/f1/workflow/w1",
      "label": "Invoices",
      "created_at": "2026-01-10T12:10:00Z"
    }
  ],
  "pending_requests": [],
  "total": 1
}

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.

Bearer token (user or machine principal). Caller must manage the subject. Available to agents as the iam.company.connections.request tool.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Request Body

Name	Type	Description
`subject_type`	string	member \| api_key \| agent \| team \| role
`subject_id`	string (UUID)	Subject id (with subject_type)
`subject`	string	Subject ERN (alternative to the pair)
`target_service`*	string	Service that owns the zone
`target_resource`*	string	Zone resource path or ERN
`permissions`	(string \| {name, resource})[] \| null	Permissions to grant on connect (or record as requested). Each entry is a bare permission name (granted at the zone root) or a {name, resource} object scoping the grant to a sub-resource within the target zone.
`message`	string \| null	Optional note for the approver

Response Fields

Name	Type	Description
`status`*	string	connected \| requested
`connection`*	object \| null	The connection, when connected
`request`*	object \| null	The pending request, when requested

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/connections \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_type": "team",
    "subject_id": "{team_id}",
    "target_service": "workflows",
    "target_resource": "org/{company_id}/folder/{folder_id}/workflow/{workflow_id}",
    "permissions": ["workflows:workflows:view"]
  }'

Response

200 OK

{
  "status": "connected",
  "connection": {
    "id": "c1c1c1c1-0000-4000-8000-000000000001",
    "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
    "principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
    "role_id": null,
    "target_service": "workflows",
    "target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/folder/f1/workflow/w1",
    "target_ern": "ern:workflows:org/c0ffee00-cafe-babe-dead-beefcafebabe/folder/f1/workflow/w1",
    "label": "Invoices",
    "created_at": "2026-01-10T12:10:00Z"
  },
  "request": null
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`connection_id`*	string (UUID)	Connection ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/connections/{connection_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

// 204 No Content

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Query Parameters

Name	Type	Description
`type`*	string	Subject type: member \| api_key \| agent \| team \| role
`q`	string	Search term or exact handle
`limit`	integer	Max results (1–25)Default: `10`

Response Fields

Name	Type	Description
`items`*	array	Resolved principals. Each item: subject_type, subject_id, ern, label, source, plus optional email (members) and avatar_url (presigned; members/agents that have one) for the picker preview.
`tier`*	string	list \| handle \| id

curl "https://platform.ergondata.ai/v1/auth/companies/{company_id}/principals/resolve?type=team&q=bill" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "subject_type": "team",
      "subject_id": "7ea11000-0000-4000-8000-000000000001",
      "ern": "ern:iam:org/c0ffee00-cafe-babe-dead-beefcafebabe/team/7ea11000-0000-4000-8000-000000000001",
      "label": "Billing",
      "email": null,
      "avatar_url": null,
      "source": "list"
    }
  ],
  "tier": "list"
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Request Body

Name	Type	Description
`subject_type`	string	member \| api_key \| agent \| team \| role
`subject_id`	string (UUID)	Subject id (with subject_type)
`subject`	string	Subject ERN (alternative to the pair)
`target_service`*	string	Service that owns the zone
`target_resource`*	string	Zone resource path or ERN
`permissions`	(string \| {name, resource})[] \| null	Permissions to grant on acceptance. Each entry is a bare permission name (granted at the zone root) or a {name, resource} object scoping the grant to a sub-resource within the target zone. The resource must be the target itself or a descendant of it.
`message`	string \| null	Optional note for the invitee

Response Fields

Name	Type	Description
`id`*	string (UUID)	Request ID
`direction`*	string	offer
`status`*	string	pending
`target_resource`*	string	Zone resource path
`requested_permissions`*	string[] \| null	Permissions to grant on accept

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/connection-offers \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_type": "agent",
    "subject_id": "{agent_id}",
    "target_service": "buckets",
    "target_resource": "org/{company_id}/bucket/{bucket_id}",
    "permissions": ["buckets:files:view"]
  }'

Response

201 Created

{
  "id": "d1d1d1d1-0000-4000-8000-000000000001",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "principal_id": "a9e27000-0000-4000-8000-000000000001",
  "role_id": null,
  "direction": "offer",
  "target_service": "buckets",
  "target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/bucket/b1",
  "target_ern": "ern:buckets:org/c0ffee00-cafe-babe-dead-beefcafebabe/bucket/b1",
  "requested_permissions": ["buckets:files:view"],
  "message": null,
  "status": "pending",
  "created_at": "2026-01-10T12:12:00Z"
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Query Parameters

Name	Type	Description
`subject_type`	string	member \| api_key \| agent \| team \| role
`subject_id`	string (UUID)	Subject id (with subject_type)
`subject`	string	Subject ERN (alternative to the pair)
`direction`	string	request \| offer
`status`	string	Filter by statusDefault: `pending`

Response Fields

Name	Type	Description
`items`*	array	Connection request/offer entries

curl "https://platform.ergondata.ai/v1/auth/companies/{company_id}/connection-requests?subject_type=team&subject_id={team_id}" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "d1d1d1d1-0000-4000-8000-000000000001",
      "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
      "principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
      "role_id": null,
      "direction": "request",
      "target_service": "workflows",
      "target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/folder/f1/workflow/w1",
      "target_ern": "ern:workflows:org/c0ffee00-cafe-babe-dead-beefcafebabe/folder/f1/workflow/w1",
      "requested_permissions": ["workflows:workflows:view"],
      "message": "Need read access for the billing dashboard",
      "status": "pending",
      "created_at": "2026-01-10T12:12:00Z"
    }
  ]
}

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

Bearer (user) token. Company member.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Company ID

Response Fields

Name	Type	Description
`approvals`*	array	Pending requests the caller can approve/reject
`offers`*	array	Pending offers the caller can accept/reject

curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/connection-requests/inbox \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "approvals": [
    {
      "id": "d1d1d1d1-0000-4000-8000-000000000001",
      "direction": "request",
      "target_service": "workflows",
      "target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/folder/f1/workflow/w1",
      "requested_permissions": ["workflows:workflows:view"],
      "status": "pending",
      "created_at": "2026-01-10T12:12:00Z"
    }
  ],
  "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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`request_id`*	string (UUID)	Request/offer ID

Request Body

Name	Type	Description
`permissions`	(string \| {name, resource})[] \| null	Override the permission set granted on accept. Bare names or {name, resource} objects (scoped to a descendant of the target), mirroring the offer body. When omitted, the request/offer's stored permissions are used.
`grant`	boolean	Whether to issue grants on acceptDefault: `true`
`reason`	string \| null	Optional note

Response Fields

Name	Type	Description
`id`*	string (UUID)	Request ID
`status`*	string	accepted
`direction`*	string	request \| offer

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/connection-requests/{request_id}/accept \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"grant": true}'

Response

200 OK

{
  "id": "d1d1d1d1-0000-4000-8000-000000000001",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "principal_id": "b10f8a92-3c4d-5e6f-7890-123456789abc",
  "role_id": null,
  "direction": "request",
  "target_service": "workflows",
  "target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/folder/f1/workflow/w1",
  "target_ern": "ern:workflows:org/c0ffee00-cafe-babe-dead-beefcafebabe/folder/f1/workflow/w1",
  "requested_permissions": ["workflows:workflows:view"],
  "message": null,
  "status": "accepted",
  "created_at": "2026-01-10T12:12:00Z"
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`request_id`*	string (UUID)	Request/offer ID

Request Body

Name	Type	Description
`reason`	string \| null	Optional rejection reason

Response Fields

Name	Type	Description
`id`*	string (UUID)	Request ID
`status`*	string	rejected

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/connection-requests/{request_id}/reject \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Not needed"}'

Response

200 OK

{
  "id": "d1d1d1d1-0000-4000-8000-000000000001",
  "direction": "request",
  "status": "rejected",
  "target_service": "workflows",
  "target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/folder/f1/workflow/w1",
  "requested_permissions": ["workflows:workflows:view"],
  "created_at": "2026-01-10T12:12:00Z"
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`request_id`*	string (UUID)	Request/offer ID

Response Fields

Name	Type	Description
`id`*	string (UUID)	Request ID
`status`*	string	withdrawn

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/connection-requests/{request_id}/withdraw \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "id": "d1d1d1d1-0000-4000-8000-000000000001",
  "direction": "offer",
  "status": "withdrawn",
  "target_service": "buckets",
  "target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/bucket/b1",
  "requested_permissions": ["buckets:files:view"],
  "created_at": "2026-01-10T12:12:00Z"
}

Per-Instance Access

Every IAM governance instance — a role, team, API key, agent, or member — has its own Access panel for granting access to that one resource. Each route is gated by the matching iam:company:<resource>:manage permission on that concrete instance and only exposes the grantable verbs for that resource (view, manage, delete/remove). These routes accept user, API key, or agent bearer tokens. Exact agent ToolDef slugs by zone: Role: iam.company.roles.access.eligible.list, iam.company.roles.access.resource_types.list, iam.company.roles.access.grants.list, iam.company.roles.access.grants.create, iam.company.roles.access.grants.batch_create, iam.company.roles.access.grants.delete, iam.company.roles.access.connection_requests.list, iam.company.roles.access.connection_requests.approve, iam.company.roles.access.connection_requests.reject, iam.company.roles.access.connections.list, iam.company.roles.access.connections.revoke; Team: iam.company.teams.access.eligible.list, iam.company.teams.access.resource_types.list, iam.company.teams.access.grants.list, iam.company.teams.access.grants.create, iam.company.teams.access.grants.batch_create, iam.company.teams.access.grants.delete, iam.company.teams.access.connection_requests.list, iam.company.teams.access.connection_requests.approve, iam.company.teams.access.connection_requests.reject, iam.company.teams.access.connections.list, iam.company.teams.access.connections.revoke; API Key: iam.company.api_keys.access.eligible.list, iam.company.api_keys.access.resource_types.list, iam.company.api_keys.access.grants.list, iam.company.api_keys.access.grants.create, iam.company.api_keys.access.grants.batch_create, iam.company.api_keys.access.grants.delete, iam.company.api_keys.access.connection_requests.list, iam.company.api_keys.access.connection_requests.approve, iam.company.api_keys.access.connection_requests.reject, iam.company.api_keys.access.connections.list, iam.company.api_keys.access.connections.revoke; Agent: iam.company.agents.access.eligible.list, iam.company.agents.access.resource_types.list, iam.company.agents.access.grants.list, iam.company.agents.access.grants.create, iam.company.agents.access.grants.batch_create, iam.company.agents.access.grants.delete, iam.company.agents.access.connection_requests.list, iam.company.agents.access.connection_requests.approve, iam.company.agents.access.connection_requests.reject, iam.company.agents.access.connections.list, iam.company.agents.access.connections.revoke; Member: iam.company.members.access.eligible.list, iam.company.members.access.resource_types.list, iam.company.members.access.grants.list, iam.company.members.access.grants.create, iam.company.members.access.grants.batch_create, iam.company.members.access.grants.delete, iam.company.members.access.connection_requests.list, iam.company.members.access.connection_requests.approve, iam.company.members.access.connection_requests.reject, iam.company.members.access.connections.list, iam.company.members.access.connections.revoke.

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`role_id`*	string (UUID)	Role ID

curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id}/access/eligible -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`role_id`*	string (UUID)	Role ID

curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id}/access/resource-types -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`role_id`*	string (UUID)	Role ID

curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id}/access/grants -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`role_id`*	string (UUID)	Role ID

Request Body

Name	Type	Description
`body`*	object	Grant subject, permission ID, resource, and effect

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id}/access/grants -H "Authorization: Bearer {token}"

Response

201 Created

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`role_id`*	string (UUID)	Role ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id}/access/grants/{grant_id} -H "Authorization: Bearer {token}"

Response

204 No Content

// 204 No Content

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`role_id`*	string (UUID)	Role ID

curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id}/access/connection-requests -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`role_id`*	string (UUID)	Role ID

Request Body

Name	Type	Description
`body`	object	Decision options, requested permissions, or rejection reason

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id}/access/connection-requests/{request_id}/approve -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`role_id`*	string (UUID)	Role ID

Request Body

Name	Type	Description
`body`	object	Decision options, requested permissions, or rejection reason

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id}/access/connection-requests/{request_id}/reject -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`role_id`*	string (UUID)	Role ID

curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id}/access/connections -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`role_id`*	string (UUID)	Role ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/roles/{role_id}/access/connections/{connection_id} -H "Authorization: Bearer {token}"

Response

204 No Content

// 204 No Content

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`team_id`*	string (UUID)	Team ID

curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/teams/{team_id}/access/connection-requests -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`team_id`*	string (UUID)	Team ID

Request Body

Name	Type	Description
`body`	object	Decision options, requested permissions, or rejection reason

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/teams/{team_id}/access/connection-requests/{request_id}/approve -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`team_id`*	string (UUID)	Team ID

Request Body

Name	Type	Description
`body`	object	Decision options, requested permissions, or rejection reason

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/teams/{team_id}/access/connection-requests/{request_id}/reject -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`team_id`*	string (UUID)	Team ID

curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/teams/{team_id}/access/connections -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`team_id`*	string (UUID)	Team ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/teams/{team_id}/access/connections/{connection_id} -H "Authorization: Bearer {token}"

Response

204 No Content

// 204 No Content

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`api_key_id`*	string (UUID)	API Key ID

curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/eligible -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`api_key_id`*	string (UUID)	API Key ID

curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/resource-types -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`api_key_id`*	string (UUID)	API Key ID

curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/grants -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`api_key_id`*	string (UUID)	API Key ID

Request Body

Name	Type	Description
`body`*	object	Grant subject, permission ID, resource, and effect

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/grants -H "Authorization: Bearer {token}"

Response

201 Created

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`api_key_id`*	string (UUID)	API Key ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/grants/{grant_id} -H "Authorization: Bearer {token}"

Response

204 No Content

// 204 No Content

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`api_key_id`*	string (UUID)	API Key ID

curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/connection-requests -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`api_key_id`*	string (UUID)	API Key ID

Request Body

Name	Type	Description
`body`	object	Decision options, requested permissions, or rejection reason

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/connection-requests/{request_id}/approve -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`api_key_id`*	string (UUID)	API Key ID

Request Body

Name	Type	Description
`body`	object	Decision options, requested permissions, or rejection reason

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/connection-requests/{request_id}/reject -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`api_key_id`*	string (UUID)	API Key ID

curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/connections -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`api_key_id`*	string (UUID)	API Key ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/api-keys/{api_key_id}/access/connections/{connection_id} -H "Authorization: Bearer {token}"

Response

204 No Content

// 204 No Content

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`agent_id`*	string (UUID)	Agent ID

curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/agents/{agent_id}/access/eligible -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

GET/v1/auth/companies/{company_id}/agents/{agent_id}/access/resource-types

Agent: List Grantable Resource Types

Bearer token with iam:company:agents:manage on the concrete agent instance.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`agent_id`*	string (UUID)	Agent ID

curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/agents/{agent_id}/access/resource-types -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`agent_id`*	string (UUID)	Agent ID

curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/agents/{agent_id}/access/grants -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`agent_id`*	string (UUID)	Agent ID

Request Body

Name	Type	Description
`body`*	object	Grant subject, permission ID, resource, and effect

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/agents/{agent_id}/access/grants -H "Authorization: Bearer {token}"

Response

201 Created

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`agent_id`*	string (UUID)	Agent ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/agents/{agent_id}/access/grants/{grant_id} -H "Authorization: Bearer {token}"

Response

204 No Content

// 204 No Content

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`agent_id`*	string (UUID)	Agent ID

curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/agents/{agent_id}/access/connection-requests -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`agent_id`*	string (UUID)	Agent ID

Request Body

Name	Type	Description
`body`	object	Decision options, requested permissions, or rejection reason

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/agents/{agent_id}/access/connection-requests/{request_id}/approve -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`agent_id`*	string (UUID)	Agent ID

Request Body

Name	Type	Description
`body`	object	Decision options, requested permissions, or rejection reason

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/agents/{agent_id}/access/connection-requests/{request_id}/reject -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`agent_id`*	string (UUID)	Agent ID

curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/agents/{agent_id}/access/connections -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`agent_id`*	string (UUID)	Agent ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/agents/{agent_id}/access/connections/{connection_id} -H "Authorization: Bearer {token}"

Response

204 No Content

// 204 No Content

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`member_id`*	string (UUID)	Member ID

curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{member_id}/access/eligible -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`member_id`*	string (UUID)	Member ID

curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{member_id}/access/resource-types -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`member_id`*	string (UUID)	Member ID

curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{member_id}/access/grants -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`member_id`*	string (UUID)	Member ID

Request Body

Name	Type	Description
`body`*	object	Grant subject, permission ID, resource, and effect

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{member_id}/access/grants -H "Authorization: Bearer {token}"

Response

201 Created

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`member_id`*	string (UUID)	Member ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{member_id}/access/grants/{grant_id} -H "Authorization: Bearer {token}"

Response

204 No Content

// 204 No Content

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`member_id`*	string (UUID)	Member ID

curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{member_id}/access/connection-requests -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`member_id`*	string (UUID)	Member ID

Request Body

Name	Type	Description
`body`	object	Decision options, requested permissions, or rejection reason

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{member_id}/access/connection-requests/{request_id}/approve -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`member_id`*	string (UUID)	Member ID

Request Body

Name	Type	Description
`body`	object	Decision options, requested permissions, or rejection reason

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{member_id}/access/connection-requests/{request_id}/reject -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`member_id`*	string (UUID)	Member ID

curl -X GET https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{member_id}/access/connections -H "Authorization: Bearer {token}"

Response

200 OK

{ "items": [], "total": 0 }

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`member_id`*	string (UUID)	Member ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/members/{member_id}/access/connections/{connection_id} -H "Authorization: Bearer {token}"

Response

204 No Content

// 204 No Content

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`team_id`*	string (UUID)	Instance ID (here, a team)

Response Fields

Name	Type	Description
`principal_type`*	string	member \| api_key \| agent \| team \| role
`principal_id`*	string (UUID)	Principal ID
`label`*	string	Display label
`display_name`*	string \| null	Display name
`avatar_url`*	string \| null	Avatar URL

curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/teams/{team_id}/access/eligible \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "principal_type": "member",
    "principal_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "label": "[email protected]",
    "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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`team_id`*	string (UUID)	Instance ID

Response Fields

Name	Type	Description
`resource_types`*	array	Resource-type tree nodes
`permissions`*	array	Grantable permissions with their resource type
`resource_type_edges`*	array	Edges between resource types

curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/teams/{team_id}/access/resource-types \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "resource_types": [
    { "id": "rt-team", "name": "Team", "slug": "team", "parent_id": null, "children": [] }
  ],
  "permissions": [
    { "id": "55555555-0000-4000-8000-000000000010", "name": "iam:company:teams:view" },
    { "id": "55555555-0000-4000-8000-000000000011", "name": "iam:company:teams:manage" }
  ],
  "resource_type_edges": []
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`team_id`*	string (UUID)	Instance ID

Query Parameters

Name	Type	Description
`page`	integer	Page number (>= 1)Default: `1`
`limit`	integer	Page size (1–500)Default: `100`

Response Fields

Name	Type	Description
`items`*	array	Grant entries on this instance
`total`*	integer	Total grants
`page`*	integer	Current page
`limit`*	integer	Page size

curl https://platform.ergondata.ai/v1/auth/companies/{company_id}/teams/{team_id}/access/grants \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "44444444-0000-4000-8000-000000000020",
      "principal_type": "member",
      "principal_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "principal_label": "[email protected]",
      "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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`team_id`*	string (UUID)	Instance ID

Request Body

Name	Type	Description
`principal_type`*	string	member \| api_key \| agent \| team \| role \| automation \| workflow \| worksheet
`principal_id`*	string (UUID)	Principal to grant
`permission_id`	string (UUID) \| null	Permission to grant (or use permission_name)
`permission_name`	string \| null	Permission name (or use permission_id)
`resource`	string \| null	Resource path; defaults to this instance
`effect`	string	allow \| denyDefault: `allow`

Response Fields

Name	Type	Description
`id`*	string (UUID)	Grant row ID
`permission_id`*	string (UUID)	Permission granted
`resource`*	string	Resource path
`effect`*	string	allow \| deny

curl -X POST https://platform.ergondata.ai/v1/auth/companies/{company_id}/teams/{team_id}/access/grants \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "principal_type": "member",
    "principal_id": "{member_id}",
    "permission_name": "iam:company:teams:view",
    "effect": "allow"
  }'

Response

201 Created

{
  "id": "44444444-0000-4000-8000-000000000020",
  "permission_id": "55555555-0000-4000-8000-000000000010",
  "name": "iam:company:teams:view",
  "resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/team/7ea11000-0000-4000-8000-000000000001",
  "effect": "allow",
  "is_system": false,
  "granted_at": "2026-01-10T12:14:00Z"
}

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

Name	Type	Description
`company_id`*	string (UUID)	Company ID
`team_id`*	string (UUID)	Instance ID
`grant_id`*	string (UUID)	Grant row ID

curl -X DELETE https://platform.ergondata.ai/v1/auth/companies/{company_id}/teams/{team_id}/access/grants/{grant_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

// 204 No 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. 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/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. This credential/session route is intentionally not an agent tool.

Interactive browser session; rate limited to 20 requests per minute.

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. This provider callback is intentionally not an agent tool.

OIDC provider callback; rate limited to 5 requests per minute.

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

Response

302

{ "detail": "See response schema" }

POST/v1/auth/sso/{provider_slug}/link

Link SSO Provider

Start an authenticated interactive flow to link an OIDC identity to the current user. This session operation is intentionally not an agent tool.

Authenticated user bearer token.

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

Response

200 OK

{ "detail": "See response schema" }

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

IAM API

Authentication

Create Access Token

Request Body

Response Fields

Response

User Authentication

Register User

Request Body

Response Fields

Response

Login

Request Body

Response Fields

Response

Refresh Session

Response Fields

Response

Logout

Response

Select Active Company

Request Body

Response Fields

Response

Get Current Principal

Response Fields

Response

Account & Verification

Verify Email

Request Body

Response

Resend Verification Email

Request Body

Response

Forgot Password

Request Body

Response

Reset Password

Request Body

Response

Change Password

Request Body

Response

Change Email

Request Body

Response

Verify Email Change

Request Body

Response

Profile, Avatar & Identities

Upload User Avatar

Request Body

Response

Delete User Avatar

Response

List My Identities

Response Fields

Response

Unlink Identity

Path Parameters

Response

Multi-Factor Authentication

MFA Status

Response Fields

Response

Begin MFA Setup

Request Body

Response Fields

Response

Verify MFA Setup

Request Body

Response Fields

Response

Verify MFA Challenge

Request Body

Response Fields

Response

Disable MFA

Request Body

Response