OpenMax
Free Trial

Apps API · Apps

Apps: 4 endpoints

← All groups

GET /api/v1/app-agent-grants

List Agent app grants

Scope: agents:app_token:read · Called with: appToken · operationId: list-app-agent-grants

Required app scope: agents:app_token:read.

One installation's grants for Agents, newest first, with their effective status and revoke reason. With an app access token of any human member (scope agents:app_token:read): the token's installation, which must be granted agents:app_token:read (403 APP_AGENT_TOKEN_SCOPE_NOT_GRANTED). With a session or personal access token: installation_id is required (400); a human app.manage holder sees every grant, anyone else only those of the Agents they own. Agents get 403 APP_PRINCIPAL_KIND_INVALID. Cursor pagination. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
installation_id query string The installation; required with a session or personal access token, implied by an app access token (which may only name its own)
agent_member_id query string Only this Agent's grants (newest first: the first is its latest grant)
status query string: active, revoked Only grants with this effective status
cursor query string Pagination cursor from the previous page
limit query integer (int32) Items per page (default 20)

Responses

POST /api/v1/app-agent-grants

Let the calling app act as an Agent

Scope: agents:app_token:exchange · Called with: appToken · operationId: create-app-agent-grant

Required app scope: agents:app_token:exchange.

Called by an app with the app access token of the Agent's owner (scope agents:app_token:exchange): records that the app may act as the Agent, which then exchanges its own workspace JWT for app access tokens (exchange-app-agent-token). The installation must be active and granted agents:app_token:exchange (else 403 APP_AGENT_TOKEN_SCOPE_NOT_GRANTED); the caller must be the Agent's current owner (403 APP_AGENT_OWNER_MISMATCH); the Agent an Agent member of the organization that has not left (404 APP_AGENT_NOT_FOUND). Any other credential gets 403 APP_AGENT_TOKEN_CALLER_INVALID; an Agent (its workspace JWT or an Agent app token) 403 APP_PRINCIPAL_KIND_INVALID. The grant stays valid until revoked or invalidated; at most one live grant per Agent and installation: granting again returns it (200). Response wrapped in standard envelope.

Request body

application/json · CreateAppAgentGrantRequestBody

Field Type Required Description
agent_member_id string (uuid) yes The Agent (member ID) the calling app may act as; the caller must be its owner

Responses

DELETE /api/v1/app-agent-grants/{grant_id}

Revoke an Agent app grant

Scope: agents:app_token:exchange · Called with: appToken · operationId: revoke-app-agent-grant

Required app scope: agents:app_token:exchange.

The Agent's current owner (session, personal access token, or their app access token of the grant's installation) revokes it as revoked_by_owner; a human app.manage holder of the organization (session or personal access token, not an app token) as revoked_by_admin. Tokens already issued under it stop working on their next call. Anyone else gets 403 APP_AGENT_OWNER_MISMATCH, an Agent 403 APP_PRINCIPAL_KIND_INVALID, a grant the caller cannot see 404 APP_AGENT_GRANT_NOT_FOUND. Revoking a revoked grant returns it. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
grant_id path string (uuid) yes Grant ID

Responses

PUT /api/v1/app-badges

Set app badges for members

Scope: apps:badge:write · Called with: appClient · operationId: set-app-badges

Required app scope: apps:badge:write.

Called by an app's backend, authenticated with its App ID and App Secret only (HTTP Basic, or app_id / app_secret in the body; no user, personal access or app token), to set or clear the count or dot shown on the app's Workspace entry for members of one organization. Each item sets the member's whole value (count 1 to 1000000, or dot true; count 0 or dot false clears); there is no expiry: a badge stays until the app changes or clears it, is hidden while the installation is suspended and deleted when it is uninstalled. Only that member sees it (list-my-app-badges). A body that does not match the request schema is refused with 422 before anything else (envelope validation; errors[].location names the field): more than 500 items, a missing org_id, items or member_id, an unknown field (e.g. ttl_seconds), a count that is not an integer, an as_of that is not RFC 3339. Then, in order: 401 AUTH_INVALID_CREDENTIALS (client authentication failed); 400 (field: org_id, items, items[i].member_id / count, as_of: not a UUID, an empty items, a member_id twice, both or neither of count and dot, count out of range, as_of too far ahead); 403 APP_INSTALLATION_INACTIVE (the app has no active installation in org_id); 429 APP_BADGE_RATE_LIMITED (120 requests per minute per installation, counted only for requests that reach an active installation; Retry-After); 403 AUTH_APP_INSUFFICIENT_SCOPE (meta.required_scope apps:badge:write: the installation was not granted it; add it to the manifest scopes and publish a version). Items whose member is not an active human member of the organization are counted in skipped, without saying why. Response wrapped in standard envelope.

Parameters

Name In Type Required Description
Authorization header string HTTP Basic client authentication: base64(App ID:App Secret), as at the token endpoint. Alternatively send app_id and app_secret in the body (not both). Bearer tokens are refused

Request body

application/json · SetAppBadgesRequestBody

Field Type Required Description
app_id string The App ID (app_...), when not sent with HTTP Basic
app_secret string The App Secret, when not sent with HTTP Basic
as_of string (date-time) When the app computed these values (RFC 3339); a stored badge with a later as_of is kept (out of order protection). Defaults to the server clock; at most 5 minutes ahead of it
items array of SetAppBadgeItem yes 1 to 500 badges, one per member (a member_id at most once); more than 500 is a 422, an empty list a 400. Each sets the member's whole value for this app (set, not increment)
org_id string yes The organization (UUID) whose installation of the app the badges are for; an official app installed in several organizations names one per request

Responses