Organization Members
Who belongs to an organization, what each may do, and who is invited to join it. An invitation is held by an email address until the person it names accepts it under /v1/me, declines it, has it withdrawn, or lets it expire, and holds a seat meanwhile. Only the owner grants, revokes or removes admin, and only the owner hands ownership on, and only signed in to Mountaya's web application: under a key these acts are a 403 whoever the session names. Every operation here needs a session token beside the key.
Somebody who has joined an organization, with the role they hold in it. An invitation that has not been accepted is not a member: it is an OrganizationInvitation, listed by getOrganizationInvitations.
user_idstring (uuid)
Identifier of the member's account. It is what names them on patchOrganizationMember and deleteOrganizationMember, and the user_id a session token is minted for when a page acts as them.
emailstring (email)
The member's account address. Absent for a member whose account cannot be resolved at that moment, who is listed without it.
namestring
The member's display name, present when the member has set one and their account can be resolved. Unbounded, unlike the name of a resource this API mints: it belongs to the person's account, and no operation here writes it.
rolestring
One of: owner, admin, contributor, viewer
What the member may do in this organization.
joined_atstring (date-time)
When the member joined: when the invitation was accepted, or when the organization was created for its owner.
An invitation to join an organization, held by an email address until the person it names accepts or declines it, somebody withdraws it, or it expires. It holds a seat from the moment it is made until then.
idstring (uuid)
Identifier of the invitation. It is what getOrganizationInvitation and deleteOrganizationInvitation take, and what the invited person accepts or declines under /v1/me/invitations.
emailstring (email)
The address invited, as stored: trimmed and lowercased.
rolestring
One of: admin, contributor, viewer
The role the person holds once they accept. owner is not among the values: it is never granted by invitation.
invited_byobject
The member who made the invitation.
created_atstring (date-time)
When the invitation was made.
expires_atstring (date-time)
When the invitation lapses unanswered, thirty days after it was made. An expired invitation frees its seat and is listed nowhere, and the address may be invited again.
/v1/organizations/{organization_id}/membersReturns everybody who has joined the organization, with the role each holds and when they joined. An invitation still waiting for an answer is not a member and is never listed here: getOrganizationInvitations lists those, and an invited person appears here once they accept. A member whose account cannot be resolved at that moment is listed without name and email.
- A session token minted for
apiwithout a user is asked for no member role on this read; one minted forstudio-embeddedwithout a user is the401a key alone gets. One that names a user is answered only while that user is a member of the organization, in any role, and is a 403 otherwise. - The writes beside it act as the user the session token names:
patchOrganizationMemberchanges a member's role, anddeleteOrganizationMemberremoves a member or lets one leave. The owner's own acts, granting, taking away or removingadmin, an admin leaving and handing the organization to another member, are made only by the owner, signed in to Mountaya's web application. - The listing pages by cursor.
rolenarrows it to the members holding one role, andsortorders it byjoined_at, oldest first unless asked otherwise. Followextensions.metadata.pagination.next_cursoruntil it readsnull, which is the end of the listing.
Path parameters
organization_idstring (uuid)
in path
Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.
Query parameters
cursorstring
in query
Where the page starts: the next_cursor the previous page reported at extensions.metadata.pagination, sent back unchanged. Omitted, the listing starts at its first item.
limitinteger (int32)
in query
default: 50
How many items one page holds, between 1 and 100; 50 when omitted, on every listing that pages. extensions.metadata.pagination.limit reports the size the page was served at. A page shorter than limit is not how the end is told: the end is a next_cursor of null. The page is cut after authorization, so it never widens what a caller can read.
rolestring
in query
One of: owner, admin, contributor, viewer
List only the members holding this role. Omitted, every member is listed. owner names the one owner.
sortstring
in query
default: joined_at
One of: joined_at, -joined_at
The order of the listing: joined_at, the earliest to join first, which is the default, or -joined_at, the latest first. Members who joined at the same instant are ordered by user_id, so the order is total and a page never repeats or skips one of them.
Response 200
One page of the members who have joined, in the order sort asks for. extensions.metadata.pagination.next_cursor asks for the next page, and is next_cursor: null on the last one.
extensionsobject
The envelope's second half, everything the answer carries that is not the answer itself. Here that is metadata.pagination alone: the limit this page was served at and the cursor of the next page, null on the last.
dataarray of OrganizationMember
Errors 400, 401, 403, 404, 429, 500, 504. See Errors.
/v1/organizations/{organization_id}/members/{user_id}Changes what one member may do in the organization. The role is the whole of what a membership carries that a caller can change; the member keeps their joined_at, and the new role governs every request they make from the next one.
- Owner or admin only (403 otherwise).
- Under a key,
adminis neither granted nor taken away: granting it, and changing the role of a member who holds it, an admin's own role included, is a 403 whoever asks. The owner's session under a key is answered as an admin's, because a session token names whoever the holder of a secret key chose, so these acts are made only by the owner, signed in to Mountaya's web application. A key moves members betweencontributorandviewer. - The owner's role cannot be changed, the owner's own request included: it is a 409. Ownership moves only in Mountaya's web application, where the owner hands it to another member and becomes an admin.
owneris not a value this takes, so asking for it is a 400. - A
user_idnaming nobody who has joined the organization is a 404, whether or not an account carries it, and whether or not an invitation to that person is waiting. An invitation's role is not changed here: withdraw it withdeleteOrganizationInvitationand invite again. - Sending the role the member already holds changes nothing and answers the member as they stand.
- A change of role changes nothing about seats: a member holds one seat whatever their role, so no role costs more than another and no change is refused for the organization's seats.
Webhook events organization.member.updated, recorded by the task organization.member.update.
Path parameters
organization_idstring (uuid)
in path
Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.
user_idstring (uuid)
in path
Identifier of the member the operation acts on, the user_id a member listing carries. Naming the user the session token names is how a member acts on their own membership. An identifier naming nobody who has joined the organization is answered as each operation says, alike whether or not an account carries it, so no status tells a caller which user identifiers exist.
Headers
Idempotency-Keystring
in header
A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.
Body
The role the member holds after the change.
rolestring
in body
One of: admin, contributor, viewer
The role the member holds after the change. owner is not among the values: it is never granted here.
Response 200
The member after the change, holding the role sent.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataOrganizationMember
Somebody who has joined an organization, with the role they hold in it. An invitation that has not been accepted is not a member: it is an OrganizationInvitation, listed by getOrganizationInvitations.
Errors 400, 401, 403, 404, 409, 413, 429, 500, 504. See Errors.
/v1/organizations/{organization_id}/members/{user_id}Removes one member from the organization. What they created stays with the organization, and their seat is freed. A member naming themself in the path is leaving.
- Removing somebody else takes the owner or admin role. Under a key, removing a member who holds
adminis a 403 whoever asks: the owner's session under a key is answered as an admin's, and only the owner removes an admin, signed in to Mountaya's web application. - Leaving is open to contributors and viewers. Under a key, an admin naming themself is a 403, and so is the owner, answered as an admin there: an admin leaves only from Mountaya's web application, since a session token names whoever the holder of a secret key chose.
- The owner cannot be removed, and cannot leave from Mountaya's web application either: either is a 409. The owner hands the organization to another member there first; the former owner is then an admin, who leaves or is removed there.
- Removing is an act on a membership rather than on a resource: for an owner or admin, a
user_idnaming nobody who has joined the organization answers 200 and changes nothing, whether or not an account carries it, so a removal sent again, or racing another, is not an error. An invitation is not a membership and is not withdrawn here:deleteOrganizationInvitationwithdraws it. - A member who has left holds no role, so a leave sent again is refused with 403 unless it carries the first request's
Idempotency-Key, which answers it with the first one's 200. - The removed member's session tokens act as nobody in the organization from their next request: every operation asking a role refuses them, and every read, every tile and the Data API serve them published content only, as the key alone is served.
- Removing a member, or a member leaving, also ends every MCP connector that person authorized through Mountaya's OAuth consent, whichever organization's key it was bound to, when they joined the organization themself, signed in to Mountaya's web application: by creating it or by accepting its invitation there. The consents are ended for the person, not for this organization. A connector bound to this organization's key stops within a minute; one bound to another organization they still belong to keeps working until its access token expires and, once the consents are ended, cannot renew it, so they authorize it again. The removal is answered
200once the membership is removed: ending the consents never fails that answer, waits on the provider for at most five seconds, and is retried until it is done. A connector the person authorizes again before it is done, for another organization or for this one once invited back, is ended with the rest, and they authorize it once more. - A membership accepted under a publishable key, with a session token naming the person, ends none of their consents when it is removed: the organization made it without a session of the person's own, so its removal leaves their connectors to their other organizations alone. A connector bound to this organization's key still stops within a minute, since it is refused while the person is not a member. How the membership was accepted decides, whoever removes it and whichever credential the removal is sent under. A membership accepted before this release counts as accepted in Mountaya's web application, however it was accepted.
Webhook events organization.member.deleted, recorded by the tasks organization.member.delete, organization.member.leave.
Path parameters
organization_idstring (uuid)
in path
Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.
user_idstring (uuid)
in path
Identifier of the member the operation acts on, the user_id a member listing carries. Naming the user the session token names is how a member acts on their own membership. An identifier naming nobody who has joined the organization is answered as each operation says, alike whether or not an account carries it, so no status tells a caller which user identifiers exist.
Headers
Idempotency-Keystring
in header
A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.
Response 200
The member is removed, or has left, or had not joined. data is null; read getOrganizationMembers for who is left.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataany | null
Always null: this operation answers with no payload.
Errors 400, 401, 403, 404, 409, 429, 500, 504. See Errors.
/v1/organizations/{organization_id}/invitationsReturns the invitations to the organization still waiting for an answer: the address each names, the role accepting grants, who made it, and when it lapses. An invitation leaves this listing when the person accepts it, and is then a member getOrganizationMembers lists, when they decline it, when it is withdrawn, or when it expires thirty days after it was made. Every invitation listed holds a seat.
- It names addresses and never accounts: whether an account carries an address is not part of the answer.
- A session token minted for
apiwithout a user is asked for no member role on this read; one minted forstudio-embeddedwithout a user is the401a key alone gets. One that names a user is answered only while that user is a member of the organization, in any role, and is a 403 otherwise. Inviting and withdrawing take the owner or admin role. - The listing pages by cursor.
rolenarrows it to the invitations granting one role, andsortorders it bycreated_at, newest first unless asked otherwise. Followextensions.metadata.pagination.next_cursoruntil it readsnull, which is the end of the listing.
Path parameters
organization_idstring (uuid)
in path
Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.
Query parameters
cursorstring
in query
Where the page starts: the next_cursor the previous page reported at extensions.metadata.pagination, sent back unchanged. Omitted, the listing starts at its first item.
limitinteger (int32)
in query
default: 50
How many items one page holds, between 1 and 100; 50 when omitted, on every listing that pages. extensions.metadata.pagination.limit reports the size the page was served at. A page shorter than limit is not how the end is told: the end is a next_cursor of null. The page is cut after authorization, so it never widens what a caller can read.
rolestring
in query
One of: admin, contributor, viewer
List only the invitations granting this role on acceptance. Omitted, every pending invitation is listed.
sortstring
in query
default: -created_at
One of: -created_at, created_at
The order of the listing: -created_at, the newest invitation first, which is the default, or created_at, the oldest first. Invitations made at the same instant are ordered by id, so the order is total and a page never repeats or skips one of them.
Response 200
One page of the invitations waiting for an answer, in the order sort asks for. extensions.metadata.pagination.next_cursor asks for the next page, and is next_cursor: null on the last one.
extensionsobject
The envelope's second half, everything the answer carries that is not the answer itself. Here that is metadata.pagination alone: the limit this page was served at and the cursor of the next page, null on the last.
dataarray of OrganizationInvitation
Errors 400, 401, 403, 404, 429, 500, 504. See Errors.
/v1/organizations/{organization_id}/invitationsInvites one address, with the role the person holds once they accept. A client inviting several people sends one request for each. Nothing is sent to the address: telling the person is the caller's to do. The person finds the invitation through getMyInvitations once their account has verified the address, under a session token postSession mints for them before they have joined, and answers it with postMyInvitationAccept or deleteMyInvitation.
- Owner or admin only (403 otherwise). Under a key, inviting as
adminis a 403 whoever asks, the owner included, whose session under a key is answered as an admin's: only the owner invites an admin, signed in to Mountaya's web application. - Any well-formed address is accepted, stored trimmed and lowercased, and answered alike whether or not an account carries it, so this cannot be used to learn which addresses have accounts. An address no account carries waits for the person to sign up and verify it.
- An address that already belongs to a member, or that already has an invitation waiting for an answer, is a 409 naming which, so a second request for one address never makes a second invitation. To change the role of a waiting invitation, withdraw it with
deleteOrganizationInvitationand invite again. owneris never granted by invitation, so asking for it is a 400.- Every invitation holds a seat from the moment it is made, and seats count the organization's members and its unexpired invitations together. One that would take that count past the seats the organization's agreement allows is a 429 coded
LIMIT_REACHED, whoseextensions.metadata.limitreadsseats; an agreement that names no seat limit allows any number. Invitations sent at the same moment cannot both take the last seat. It clears when a member is removed or leaves, an invitation is declined, withdrawn or lapses, or the organization's agreement allows more seats. - At most 500 invitations wait at once in an organization: one more is a 429 coded
LIMIT_REACHED, whoseextensions.metadata.limitreadspending-invitations, and which no agreement raises, so it clears only as invitations are answered, withdrawn or lapse. - Neither ceiling carries
Retry-After, since no wait lifts it, andextensions.metadatacarries how many it allows,allowed, and how many are held,used. Nothing is invited. The seats are asked before the invitations waiting, and both after every other refusal, so a request refused with a400, a409, or a403for the caller's role is answered that way whatever is left of either. - An invitation lapses thirty days after it is made if nobody answers it, which frees its seat and lets the address be invited again.
- Invitations are limited to 30 per minute for the user the session token names, and to 200 per day for the organization; past either limit the answer is a
429carryingRetry-After. An invitation counts toward the organization's day only once the user is known to be one of its owners or admins and the request is well formed: one refused with a400, or with the403of a role that may not send it, never spends it, so nobody outside the organization can use up its day.
Webhook events organization.invitation.created, organization.invitation.expired, recorded by the task organization.invitation.create.
Path parameters
organization_idstring (uuid)
in path
Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.
Headers
Idempotency-Keystring
in header
A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.
Body
The address to invite and the role it grants on acceptance.
emailstring (email)
in body
The address to invite, any well-formed address, stored trimmed and lowercased. It need not belong to an account: the invitation waits for the person to sign up and verify it. Nothing is sent to it by this operation. Whether an account carries it never changes the answer.
rolestring
in body
One of: admin, contributor, viewer
The role the person holds once they accept. owner is not among the values: it is never granted by invitation. Only the owner invites as admin, signed in to Mountaya's web application: under a key, admin is a 403 whoever asks.
Response 201
The invitation as made, waiting for an answer and holding a seat. Location names it, /v1/organizations/{organization_id}/invitations/{invitation_id}.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataOrganizationInvitation
An invitation to join an organization, held by an email address until the person it names accepts or declines it, somebody withdraws it, or it expires. It holds a seat from the moment it is made until then.
Errors 400, 401, 403, 404, 409, 413, 429, 500, 504. See Errors.
/v1/organizations/{organization_id}/invitations/{invitation_id}Returns one invitation to the organization that is still waiting for an answer: the address it names, the role accepting grants, who made it, and when it lapses. Once the person accepts or declines it, or it is withdrawn or lapses, it is gone and its identifier is a 404; a person who accepted is a member getOrganizationMembers lists.
- A session token minted for
apiwithout a user is asked for no member role on this read; one minted forstudio-embeddedwithout a user is the401a key alone gets. One that names a user is answered only while that user is a member of the organization, in any role, and is a 403 otherwise.
Path parameters
organization_idstring (uuid)
in path
Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.
invitation_idstring (uuid)
in path
Identifier of the invitation, the id an OrganizationInvitation or a UserInvitation carries. One that names no invitation this caller may see, an expired one included, is answered as each operation says: a read or an acceptance answers it 404, and a withdrawal or a decline, which leave it gone either way, answer 200.
Response 200
The invitation, still waiting for an answer and holding a seat.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataOrganizationInvitation
An invitation to join an organization, held by an email address until the person it names accepts or declines it, somebody withdraws it, or it expires. It holds a seat from the moment it is made until then.
Errors 400, 401, 403, 404, 429, 500, 504. See Errors.
/v1/organizations/{organization_id}/invitations/{invitation_id}Withdraws an invitation still waiting for an answer, which frees its seat. The person it names cannot accept it afterwards, and the address may be invited again.
- Owner or admin only (403 otherwise), whatever role the invitation grants: withdrawing grants nothing.
- Withdrawing is an act on the invitation's state rather than on a resource, so an invitation already gone answers 200 and changes nothing: one already declined, withdrawn or lapsed, and an identifier naming no invitation of this organization at all. A withdrawal sent again, or racing the person's own answer, is therefore not an error.
- An invitation already accepted is gone as well: the person is a member, and
deleteOrganizationMemberremoves them.
Webhook events organization.invitation.revoked, organization.invitation.expired, recorded by the task organization.invitation.revoke.
Path parameters
organization_idstring (uuid)
in path
Identifier of the organization the operation acts on. A publishable key reaches only its own organization: any other identifier is a 403, whether or not it exists, so the parameter cannot be used to probe which organization ids exist.
invitation_idstring (uuid)
in path
Identifier of the invitation, the id an OrganizationInvitation or a UserInvitation carries. One that names no invitation this caller may see, an expired one included, is answered as each operation says: a read or an acceptance answers it 404, and a withdrawal or a decline, which leave it gone either way, answer 200.
Headers
Idempotency-Keystring
in header
A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.
Response 200
The invitation is withdrawn, or was already gone. data is null.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataany | null
Always null: this operation answers with no payload.
Errors 400, 401, 403, 404, 409, 429, 500, 504. See Errors.