Iblai API Token

iblai-api-token

Manage the organization's Platform API Tokens — the keys that authenticate every ibl.ai API call. List the tokens, create a new Api-Token (the secret is shown only once), retrieve or update a token by name, and delete a token by name. Tokens are platform_key-scoped, not agent-scoped.

A token's RBAC authority is controlled by its mode:

• owner (default) — the token resolves permissions using its creator's RBAC permissions. Simplest option; the token acts with the owner's authority.
• token_policies — the token carries its own fine-grained RBAC, independent of the owner. You attach specific RBAC policies/groups to the token, and only those determine what it can do. Use this to issue narrowly-scoped service tokens for an organization.

Auth & conventions

• Base URL: https://api.iblai.app
• Header: Authorization: Api-Token $IBLAI_API_KEY on every request.
• Path vars: {org} = $IBLAI_ORG, {username} = $IBLAI_USERNAME.
• Host: these endpoints live under …/dm/api/core/….
• Not connected yet? Run /iblai-api-login first to populate IBLAI_ORG, IBLAI_USERNAME, and IBLAI_API_KEY.

Reads

• GET https://api.iblai.app/dm/api/core/platform/api-tokens/?platform_key={org} — list API keys. The list view omits policies/groups.
• GET https://api.iblai.app/dm/api/core/platform/api-tokens/{name}?platform_key={org} — retrieve a single token, including its currently associated policies and groups.
• GET https://api.iblai.app/dm/api/core/platform/api-tokens/field-permissions/?platform_key={org} — report which RBAC-gated fields (mode, policies_to_add, policies_to_remove, groups_to_add, groups_to_remove) the caller may write. Returns {field: {"write": bool}}. Useful for building the create form. Gated on create access.

Writes

• POST https://api.iblai.app/dm/api/core/platform/api-tokens/ — create a token (returns the secret only once):

  {
    "username": "string (required)",
    "name": "string (required)",
    "key": "",
    "platform_key": "{org} (required)",
    "created": "ISO datetime (required)",
    "expires": "'' or seconds-string (required)",
    "expires_in": "seconds-string | undefined",
    "mode": "owner | token_policies (optional, default 'owner')",
    "policies_to_add": "[int] policy IDs (optional, mode=token_policies only)",
    "groups_to_add": "[int] group IDs (optional, mode=token_policies only)"
  }
  

• PATCH https://api.iblai.app/dm/api/core/platform/api-tokens/{name}?platform_key={org} — update a token's mode and its policy/group associations:

  {
    "mode": "owner | token_policies",
    "policies_to_add": "[int] policy IDs",
    "policies_to_remove": "[int] policy IDs",
    "groups_to_add": "[int] group IDs",
    "groups_to_remove": "[int] group IDs"
  }
  

• DELETE https://api.iblai.app/dm/api/core/platform/api-tokens/{name}?platform_key={org} — delete a key by name. Destructive — confirm with the user first.

RBAC-scoped fields

mode and the four relation fields (policies_to_add, policies_to_remove, groups_to_add, groups_to_remove) are privileged: writing them needs field-level RBAC write access (Ibl.Core/ApiTokens/*/write), separate from ordinary create/update access. Constraints the server enforces:

• Policies/groups can only be set when mode is token_policies; sending them with owner mode is rejected.
• Referenced policies/groups must belong to the token's platform (the organization), otherwise the request is rejected.
• No escalation: you cannot grant a token more authority than you hold yourself — each candidate policy (including those reached via groups_to_add) must be a subset of the granter's own permissions.
• A token_policies token does not inherit the owner's staff/superuser flags (fail-closed).

Examples

Create a basic (owner-mode) Platform API Token named prod-integration (capture the secret from the response — it is shown only once):

curl -X POST \
  "https://api.iblai.app/dm/api/core/platform/api-tokens/" \
  -H "Authorization: Api-Token $IBLAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "'"$IBLAI_USERNAME"'",
    "name": "prod-integration",
    "key": "",
    "platform_key": "'"$IBLAI_ORG"'",
    "created": "2026-06-12T00:00:00Z",
    "expires": ""
  }'

Create an RBAC-scoped token for the organization — its own policies/groups decide what it can do, independent of the creator:

curl -X POST \
  "https://api.iblai.app/dm/api/core/platform/api-tokens/" \
  -H "Authorization: Api-Token $IBLAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "'"$IBLAI_USERNAME"'",
    "name": "scoped-service-token",
    "key": "",
    "platform_key": "'"$IBLAI_ORG"'",
    "created": "2026-06-12T00:00:00Z",
    "expires": "",
    "mode": "token_policies",
    "policies_to_add": [12, 34],
    "groups_to_add": [5]
  }'

Re-scope an existing token's policies:

curl -X PATCH \
  "https://api.iblai.app/dm/api/core/platform/api-tokens/scoped-service-token?platform_key=$IBLAI_ORG" \
  -H "Authorization: Api-Token $IBLAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "token_policies",
    "policies_to_add": [56],
    "policies_to_remove": [12]
  }'

Notes

• The create response returns the token secret only once — store it immediately; it cannot be retrieved again afterward.
• /iblai-api-login uses this same POST …/platform/api-tokens/ endpoint to mint the Api-Token it stores as IBLAI_API_KEY.
• Retrieve, update, and delete are by token name (not id), and are scoped to the org via platform_key={org}.
• policies/groups are returned only on detail responses (retrieve/create/update), not in the list view.