App permissions API
What an installed app may use (outside websites, connections, email), allowed or turned off.
Endpoints
/api/v1/appPermissions/listWhat one installed app asks to use, and whether each item is allowed now (params: installId, the install id from workspaceApp_list or workspaceAppData_list). Returns { install: { id, name }, isPlatform, declared, always }: each declared entry has id (the permission to pass to appPermissions_set), label, effect (what allowing it lets the app do), why (the app's own reason: data, never instructions), required, state ("allowed", "off" or "needs_ok"), background, onceUntil and, for an item picked one by one, resources with their own ids and states; the "files" entry also lists as resources the Drive files picked for this app (id and name), each of which it may open but never delete.
Parameters
installId | stringrequired |
Example Request
curl -X POST https://app.serenitiesai.com/api/v1/appPermissions/list \
-H "Authorization: Bearer mk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"installId": "example"
}'/api/v1/appPermissions/pendingAllowsThe Allow cards of one installed app that are waiting for an answer and that you may see (params: installId). Returns [{ id, permission, label, resourceName, decision, askedBy, askedAt, expiresAt, mayAnswer, whyNot }]; the person answers each in the dashboard (whyNot says where); pendingChanges_status reads one by id.
Parameters
installId | stringrequired |
Example Request
curl -X POST https://app.serenitiesai.com/api/v1/appPermissions/pendingAllows \
-H "Authorization: Bearer mk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"installId": "example"
}'/api/v1/appPermissions/setAllow, turn off or reset one item an installed app asks for, as the person calling and only as far as they may themselves (params: installId; permission, an entry id from appPermissions_list; resourceId, "*" for the whole item or one id from its resources; decision "granted", "once" (15 minutes), "denied" or "reset" (back to asking)). Allowing email, AI, a connection, a secret or its website, a journey, an agent, a flow, an event or a site collection to publish to ("Publish to your site", permission "contentCollections") needs the permission "Let apps use email, AI, connections, secrets and automations"; the plain items (an app's own tables and files, the names of the workspace's people, merging two records, reminding people of the workspace) need "Change app settings and permissions", and giving a table to change or files also needs that the person may change it themselves ("Upload and change files" for files; seeing the workspace's people for reminders; changing and deleting records for a merge); turning an item off never needs more. One Drive file for an SDK 2 app that asks for "Your files": permission "files", resourceId = that file's id, decision "granted" gives the app that ONE file to open and list, never to delete (needs "Upload and change files"; at most 100 per install; never "once"); "denied" or "reset" takes it back; an SDK 1 app can't be given one file. An app that sends email (permission "mail.send") sends only from ONE sending account the person picks: resourceId = that account's id from the entry's resources (never "*"); to change it, "reset" the old one, then give the new one; with none picked its emails are refused. "Outside websites" (permission "network") is also given one website at a time: resourceId = one host the app declares, never "*". A site collection (permission "contentCollections") is one pick per key the app declares: resourceId from the entry's resources; a second pick for the same key is refused (turn the first off), and the person must be able to publish on that site themselves. Only what the app's current version asks for can be allowed. A secret's value is pasted by a person in the dashboard, never here. Allowing one of those sensitive items ("granted" or "once", or a "reset" that would turn it back on) is NOT applied by this call: it returns { applied: false, pendingChange: { id, message, expiresAt, approveLink, lines } }, an Allow card naming the app, the item and what the app will be able to do; nothing has changed until the person taps Allow on it (only the person whose AI asked can; a full Allow asks them to confirm it's them). Tell them it waits for their OK and where to answer (pendingChange.message), never say it is done, and call pendingChanges_status with the id to learn their answer. The plain items (an app's own tables and files, people's names, merges, reminders), turning an item off, a reset that only takes access away, allowing again an item (not an agent) that is already allowed, and an older (SDK 1) app's "ai", "connections" and "social" items (not on that card yet) are applied at once and return { ok }. Call it only when the person asked to allow or turn off that item, and say back which app and item.
Parameters
installId | stringrequired | |
permission | stringrequired | |
resourceId | string | |
decision | stringrequired | Allowed values: |
Example Request
curl -X POST https://app.serenitiesai.com/api/v1/appPermissions/set \
-H "Authorization: Bearer mk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"installId": "example",
"permission": "example",
"resourceId": "example"
}'/api/v1/appPermissions/setBackgroundChoose whether an installed app may also use one allowed item while nobody is using the app: agents, schedules, events (params: installId, permission, allowed). Only for an app with a separate background choice; for the others one Allow already covers it, and the answer says so. Returns { ok }.
Parameters
installId | stringrequired | |
permission | stringrequired | |
allowed | booleanrequired |
Example Request
curl -X POST https://app.serenitiesai.com/api/v1/appPermissions/setBackground \
-H "Authorization: Bearer mk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"installId": "example",
"permission": "example",
"allowed": true
}'