Roles and permissions
Who may do what in an organization and on a deal, and what that means for a key.
A key acts as its owner, so what a key may do is what its owner's roles allow. There are two places a person holds a role: their registered organization, and each deal they are on.
In an organization
An organization's team has admins and members. Admins run the team; members work on its deals.
| What | Admin | Member |
|---|---|---|
| Invite, remove, make admin or member; approve requests to join | ✓ | – |
| Email domains, the organization's name, deleting it | ✓ | – |
| See the firm's deals and who sits in them; add and remove colleagues; make a colleague the deal's lead | ✓ | – |
| See and revoke the team's API keys | ✓ | – |
| Make, rotate and revoke their own API keys | ✓ | ✓ |
| Use the request list library: read a list, start a deal from it, add it to a deal | ✓ | ✓ |
| Add to the library — a new list, items, categories — and edit it in place | ✓ | ✓ |
| Remove items or categories, archive or delete a list | ✓ | – |
On a deal
A deal has two sides: the side that runs the request list (usually the Financial Sponsor, the side that created the deal) and the other side, which answers. Everyone on a deal holds one of four roles.
- Super admin — exactly one per deal, on the side that runs the list: the deal's creator, until they hand the deal over to a deal admin. Runs the deal.
- Deal admin — named by the super admin, only from the deal's own firm (the firm the deal was created from). Manages people and firms on both sides and files requests.
- Editor — works the requests. On the side that runs the list, an editor proposes new requests for an admin to file.
- Viewer — reads everything their side reads, replies on one request at a time, and exports.
The other side has no admins: who is on it, and what each person may do, is the running side's call.
| What | Super admin | Deal admin | Editor | Viewer |
|---|---|---|---|---|
| The deal's settings: name, codename, the target's name, time zone, colour | ✓ | – | – | – |
| Categories: add, rename, remove | ✓ | – | – | – |
| Archive, restore or delete the deal | ✓ | – | – | – |
| Name deal admins; hand the deal over | ✓ | – | – | – |
| Firms on either side: add, rename, role, default access, remove an empty one | ✓ | ✓ | – | – |
| People on either side: add, remove, set editor or viewer | ✓ | ✓ | – | – |
| Approve or decline proposed requests; import what an editor submitted | ✓ | ✓ | – | – |
| Delete requests | ✓ | ✓ | – | – |
| Raise requests — one by hand, an import, a library list | at once | at once | as a proposal | – |
| Edit a request; assign it and set its due date; move its status; bulk edits | ✓ | ✓ | ✓ | – |
| Post on a request: answers, questions, references, internal notes | ✓ | ✓ | ✓ | one request at a time |
| Read everything the side reads; export; snapshots | ✓ | ✓ | ✓ | ✓ |
The management rows belong to the side that runs the list. On the other side an editor moves the status and posts; a viewer reads, replies on one request at a time, and exports. An import that would create a category is the super admin's to commit; a deal admin commits one once every heading lands on a category the deal already has.
What this means for the API
GET /deals/{id}says what you are on the deal:me.accessisadmin,editororviewer, andme.is_super_adminsays whether you run it. Each person listed under/deals/{id}/peoplecarries the same two fields.- Creating a request (
POST /deals/{id}/requests) files it at once and is the admins'. An editor's key is refused with403 proposal_required: editors propose requests for an admin to file, withPOST /deals/{id}/proposals; the admins list, approve and decline them under the same path. See Proposals. - Editing, assigning and moving status follow the table above: editing is the running side's admins' and editors'; the status, anyone's on the deal but a viewer.
- Answering (
POST …/messages) is open to everyone on the deal, a viewer included. - A read-only key can do none of the writes, whatever its owner's role.
is_project_admin is kept on the same shapes for a while, with the same value as
is_super_admin; use the new name.