Manage organization members
Invite members, accept invitations, change roles, remove access, and revoke pending invitations through the Agent Studio API.
Manage the complete organization membership lifecycle through authenticated API requests. You can invite a person by email, accept an invitation token, change a built-in role, remove a member, and cancel an invitation that is still pending.
Before you begin
You need the organization ID, an authenticated Agent Studio session, and sufficient organization permission for the administrative action. The person accepting an invitation must use their own authenticated session.
Examples use https://agent-studio.example.com, org_example, and user_example as placeholders. Replace them with your origin and the IDs returned by your deployment. Built-in role values are OWNER, ADMIN, MEMBER, and VIEWER; send them in uppercase exactly as shown.
Manage membership
List the organization members before inviting or changing anyone.
curl 'https://agent-studio.example.com/api/organizations/org_example/members' \
-H 'Cookie: __session=<administrator-session-cookie>'The response returns success: true and a data array. Record the existing user IDs and roles so that you do not create an unnecessary invitation or change the wrong member.
Send the person's email address and the role they should receive. If you omit role, the organization service applies its default membership role.
curl -X POST 'https://agent-studio.example.com/api/organizations/org_example/members' \
-H 'Content-Type: application/json' \
-H 'Cookie: __session=<administrator-session-cookie>' \
-d '{
"email": "developer@example.com",
"role": "MEMBER"
}'A valid request returns 201, success: true, and the invitation in data. The endpoint rejects a missing email, an invalid email format, or a role outside OWNER, ADMIN, MEMBER, and VIEWER.
List pending invitations and locate the invitation you created.
curl 'https://agent-studio.example.com/api/organizations/org_example/invitations' \
-H 'Cookie: __session=<administrator-session-cookie>'The data array contains pending invitation records. Save the invitation ID if you might need to revoke it. Deliver the invitation through your approved secure channel; the API does not document an email-delivery procedure.
As the invited person, send a request with the invitation token in the path and that person's own session cookie.
curl -X POST 'https://agent-studio.example.com/api/invitations/<invitation-token>/accept' \
-H 'Cookie: __session=<invitee-session-cookie>'The response returns success: true and the new membership in data. The invitation token must be present and valid for the organization service to create the membership.
Use the member's user ID, not the membership ID, in the route. Send one of the four built-in role values.
curl -X PUT 'https://agent-studio.example.com/api/organizations/org_example/members/user_example' \
-H 'Content-Type: application/json' \
-H 'Cookie: __session=<administrator-session-cookie>' \
-d '{"role":"VIEWER"}'The response returns the updated member in data. For custom roles and granular permissions, use Configure roles and permissions rather than this built-in-role endpoint.
When a person should no longer belong to the organization, send a delete request for their user ID.
curl -X DELETE 'https://agent-studio.example.com/api/organizations/org_example/members/user_example' \
-H 'Cookie: __session=<administrator-session-cookie>'A successful removal returns { "success": true }. Recheck membership immediately, especially when access removal is time-sensitive.
If an invitation should not be accepted, use its invitation ID as the invitationId query parameter.
curl -X DELETE 'https://agent-studio.example.com/api/organizations/org_example/invitations?invitationId=inv_example' \
-H 'Cookie: __session=<administrator-session-cookie>'A successful cancellation returns { "success": true }. The invitation ID is required; the email address and token do not replace it in this route.
Verify membership
List members again after acceptance, a role change, or removal. Confirm that:
- an accepted invite creates a member entry with the intended role;
- an updated member reports the new uppercase role;
- a removed user's ID no longer appears in the member list.
After revocation, list pending invitations and confirm that the invitation ID is absent. This check distinguishes a completed server-side change from a local request failure.