Team, roles, and invitations

Who works at the organization, what each person may see, and how new people are brought in.

There are two vocabularies here and they do different jobs.

• A role is organization-wide: Member, Admin, or Owner. It decides what somebody may do to the organization itself, its billing, and its people.
• A grant is per client company: a list of permissions on one profile. It decides what somebody may do to that client's documents, sources, reminders, and settings.

A person needs both. An Admin with no grants can manage the team and see nothing about any client's invoices. See Authentication for the full ladder and Profiles for what a client company is.

Routes

The first ten are organization-scoped and need X-Organization-Id. The three under /v1/me are not, because an invitation is addressed to a person before they belong to the organization that sent it. See Authentication.

The role ladder

Roles serialize as integers. See Conventions.

There is exactly one Owner. It is the person who created the organization or the person it was handed to, and the seat does not split. That is why a role change and a transfer are separate routes.

One rule runs through every write on this page: you may only act on a role below your own. An Admin may invite and remove Members and other Admins but may not touch the Owner, may not hand out the Owner role, and may not change their own grants. Breaking it answers 403 with member_role_not_below_caller, member_role_not_allowed, member_owner_protected, member_self_grant_change, or invitation_role_not_allowed, depending on which write asked. See Error codes.

GET /v1/members

Everybody in the organization. Admin. Answers a plain array, not a page.

memberId is the membership id, not the user id. The same person can belong to two organizations and has a different memberId in each. Address these routes with id, never with userId.

hasOrganizationWideAccess is the field to read before you read grantedProfileCount. When it is true, a grantedProfileCount of 0 does not mean the person sees nothing; it means they do not need grants. Showing "0 clients" next to an Owner is the classic bug here.

[
  {
    "id": "33333333-3333-4333-8333-333333333333",
    "userId": "44444444-4444-4444-8444-444444444444",
    "email": "ana@example.com",
    "displayName": "Ana Example",
    "avatarUrl": null,
    "avatarThumbnailUrl": null,
    "role": 1,
    "grantedProfileCount": 12,
    "hasOrganizationWideAccess": false,
    "createdAt": "2026-09-01T08:00:00Z"
  }
]

GET /v1/members/{memberId}/grants

One person's access grid. Admin.

Each entry in grants:

The permissions are a set, not a ladder. ManageDocuments does not imply View, so a grant that is meant to let somebody work on a client usually lists View alongside whatever else it lists. Grant what the job needs and read the list literally.

When hasOrganizationWideAccess is true, grants is usually empty and it does not limit anything.

PUT /v1/members/{memberId}/grants

Replaces the whole grid. Admin.

{
  "grants": [
    { "profileId": "22222222-2222-4222-8222-222222222222", "permissions": [0, 1, 3] },
    { "profileId": "55555555-5555-4555-8555-555555555555", "permissions": [0] }
  ]
}

Answers 200 with the same shape GET returns.

This is not a patch. Every client missing from the body loses its grant, and sending {"grants": []} removes all of them. To add one client, read the grid, append, and send the whole thing back. A client-side screen that sends only the row somebody just edited will silently revoke the rest.

Refusals:

An Admin may not widen their own access, which is why the first one exists. Somebody else with the authority has to do it.

PUT /v1/members/{memberId}/role

Changes a role. Owner only.

{ "role": 1 }

Answers 200 with the member. Member and Admin are the only values that go through here. Promoting somebody to Owner answers 403 member_role_not_allowed, because there is one Owner and handing the seat over is a different route that also moves the caller out of it.

Demoting the Owner answers 403 member_owner_protected. An organization is never left without one.

Grants are untouched by a role change. Promoting a Member to Admin does not widen what they see of any client; it widens what they may do to the organization.

DELETE /v1/members/{memberId}

Removes somebody from the organization. Admin. Answers 204.

Their grants go with them, and they lose the organization from their switcher immediately. Nothing they collected, confirmed, or sent is deleted or reattributed. The audit trail keeps their name against what they did.

Removing the Owner answers 403 member_owner_protected. Transfer the seat first, then remove the person.

Removing somebody at or above your own role answers 403 member_role_not_below_caller.

POST /v1/members/{memberId}/transfer-ownership

Hands the Owner seat to another member. Owner. No body.

Answers 200 with the member who is now the Owner.

The caller becomes an Admin in the same transaction. There is no moment with two Owners and no moment with none. Expect the caller's own role to have changed when the call returns, and refresh whatever you cached about it. Anything the caller could do as Owner, changing the subscription above all, they cannot do on the next request.

This is the only way the Owner seat moves. It is deliberately a separate route from a role change, because it is the one write in this area that takes something away from the person making it.

Invitations

Somebody who does not have a Syllevo account yet cannot be added; they have to be invited. An invitation is an email plus the role and grants they will get when they accept.

An invitation lives 14 days. Past that, accepting it answers 409 invitation_expired and the only fix is a resend, which puts the clock back to a full 14 days.

status and expired answer different questions. A row can be Pending and expired: true at the same time: nobody answered it and the 14 days ran out. Read expired before you show "waiting for a reply".

GET /v1/invitations

Every invitation this organization has sent, in any state. Admin. A plain array.

emailSent: false with a 201 is not a contradiction. The invitation exists and the link works; the mail relay is what did not take it. Show a resend button rather than an error, because the row is good.

POST /v1/invitations

Creates and sends one. Admin. Answers 201.

{
  "email": "mihai@example.com",
  "role": 0,
  "grants": [{ "profileId": "22222222-2222-4222-8222-222222222222", "permissions": [0, 1] }]
}

The grants ride with the invitation and are applied the moment it is accepted, so a new person lands with the right clients already visible instead of waiting for a second setup step.

Refusals:

DELETE /v1/invitations/{invitationId}

Revokes a pending invitation. Admin. Answers 204. The link stops working.

The row is not deleted, it moves to status 3. Who invited whom is part of the record.

Revoking anything that is not Pending, already accepted, declined, or revoked, answers 409 invitation_not_pending. Removing somebody who already joined is DELETE /v1/members/{memberId}, a different act.

POST /v1/invitations/{invitationId}/resend

Sends the email again. Admin. Answers 200 with the invitation.

A resend renews the clock. expiresAt moves to 14 days from now, which is what makes it the fix for an expired invitation rather than a second copy of a dead one.

Refused with 409 invitation_not_pending when it is not pending.

Invitations you hold

/v1/me/invitations is the other side: what other organizations have sent to the signed-in person. These three routes do not take X-Organization-Id. Whoever is being invited does not belong to the inviting organization yet, so there is no organization to scope to.

GET /v1/me/invitations

Every pending invitation addressed to the caller, across every organization. A plain array.

Nothing here names the email address, because the invitation was matched to the caller's account already.

POST /v1/me/invitations/{invitationId}/accept

Joins the organization. No body. Answers 200 with the new membership:

{
  "organizationId": "11111111-1111-4111-8111-111111111111",
  "organizationName": "Example Contabil SRL",
  "role": 0
}

Put that organizationId in X-Organization-Id on the next request and the rest of the API opens.

Refusals:

Accepting when the caller is already a member of that organization is not an error. The invitation is closed and the existing membership is returned unchanged, role and grants included. Clicking an old link twice does not demote anybody.

POST /v1/me/invitations/{invitationId}/decline

Says no. No body. Answers 204. The row moves to status 2 and the link stops working.

There is no undo. A declined invitation needs a new one, not a resend, because a resend only works on a pending row.