/v1/orgs/{orgName}/. They do what the organization’s Settings pages do: invite and remove members, change roles, read the audit log, and choose where a factory’s context comes from.
{orgName} is the organization’s name as it appears in the dashboard URL, /orgs/<orgName>/. Case does not matter.
Choose a credential
The dashboard calls these endpoints with your session, so it works on every plan. Scripts need a management API key, which needs Enterprise.
A factory’s API key (
sk_outerlayer_...) never works here. It belongs to one factory, and these endpoints act on the whole organization. See API keys for factory keys.
Create a management API key
Open the organization’s Settings → Management API keys and choose Create key. The tab shows on an Enterprise plan, to members who can view org API keys. Name the key after what will use it, and tick the permissions it needs. You can grant only permissions you hold yourself. The key is shown once, and it is not shown again. A key never does more than the member who created it can do now. Every call checks the key’s permissions against its creator’s current role. If the creator moves to a lower role, the key loses the permissions that role lacks. A key is refused with403 when its creator has left the organization, or holds a custom role. Create keys from a member with a built-in role who will stay.
Send it as a bearer token:
402. The tab no longer shows in the menu, but revoking still works. Open /orgs/<orgName>/settings/management-api-keys directly to revoke them.
Permissions
A management key carries organization permissions only. Each endpoint needs one:
The key dialog also offers
roles.insert, roles.update and roles.delete. No endpoint in this API uses them.
A signed-in member needs the same permission, from their role in the organization.
Members and roles
The built-in roles are
owner, admin, write, read and disabled.
To invite someone, send their name, email and role:
members.insert. A sent invite answers 200 with the new membership’s id:
POST /v1/orgs/{orgName}/members/invites/{inviteId}/resend.
To give someone a custom role, send its id as custom_role_id beside role, on an invite or a role change. Custom roles need a Team or Enterprise plan. A role that belongs to another organization is refused with 400 custom_role_not_found.
An invite cannot give access to individual factories. A non-empty appRoles is refused with 400 app_roles_not_supported. Set factory access from Settings → Members once the invite is sent.
Changes made through the API are recorded in the audit log. A change made with a key names the key, and a change made with a session names the person.
Audit log
The audit log needs an Enterprise plan, whichever credential calls it.
The list takes these query parameters, all optional:
The response carries
data and pagination, where pagination.totalPages tells you when to stop.
The export takes no filters. It holds at most 50,000 rows.
Context sources
A factory’s context source can be read, designated, changed and revoked at/v1/orgs/{orgName}/apps/{appId}/context-source. See Manage it through the API.
Errors
An error response carrieserror.code and error.message.
Every endpoint’s full request and response schema is in the API reference, under Org Management and Context.