Roles and members
Give the people and automation in your organization the right access to a ProRDP workspace: Owner, Activator or Reader, how to add them, and the workspace API.
A workspace’s owner can give other people in their organization access to it. Each person is given one of three roles, which decide what they can see and do. This page covers the roles, how to add members, the rules that keep a workspace from being locked, and how scripts and pipelines use the same roles through the workspace API.
The three roles
| Role | Intended for | Can |
|---|---|---|
| Owner | Whoever buys and runs the workspace | Everything: change the workspace’s settings, its licenses, billing and Stripe, enrollment keys, Macs, and who has which role. |
| Activator | Help-desk and IT staff who set up Macs | See the workspace, its Macs, enrollment keys and members, and add Macs to it. Can’t see billing or Stripe, and can’t change anything else. |
| Reader | Anyone who needs to see what’s licensed | See the workspace, its Macs, enrollment keys and members. Can see how many licenses it has, but nothing else about billing. |
What each role can do
| Reader | Activator | Owner | |
|---|---|---|---|
| See the workspace, its Macs and its members | ✓ | ✓ | ✓ |
| See enrollment keys (never the key itself) | ✓ | ✓ | ✓ |
| See how many licenses the workspace has | ✓ | ✓ | ✓ |
| Add a Mac with an activation code | ✓ | ✓ | |
| See the plan, price and renewal date | ✓ | ||
| Change licenses and automatic license settings | ✓ | ||
| Open the Stripe billing page | ✓ | ||
| Create and revoke enrollment keys | ✓ | ||
| Change who has which role | ✓ |
An Activator can license a Mac only when it doesn’t need a purchase: when a license is free, when the Mac is already in the workspace, or when the owners have the workspace buy licenses as Macs join. If a Mac needs a license added first, the Activator is told to ask an owner.
Which accounts can have a role
Roles depend on how the workspace was bought.
- A personal Microsoft account (an outlook.com or hotmail.com account, for example). The person who bought the workspace is its only owner, and no one else can have a role.
- A work or school account (Entra ID). The owner can give roles to the users and service principals of their own Entra tenant, and no one else’s. Colleagues sign in to the portal with their own work account and see only the workspaces they’ve been given a role in.
Groups can’t be given roles yet. Give a role to each person or service principal.
A role belongs to a specific person or service principal, identified by the account’s object ID. It counts only when that account signs in from the workspace’s own tenant. A guest user from another organization can’t use a role, even if you add their address.
Add a person
You must be an owner of a workspace bought with a work or school account.
- Sign in to the portal and open the workspace.
- Choose Members.
- Under Add a member, search for the person by name, sign-in name, email or object ID.
- Choose the right match. It’s added to the table with a role.
- Set their Role to Owner, Activator or Reader.
- Choose Save. Nothing changes until you save.
The first time you search, the portal opens a window asking you to let it look up people in your
directory. This asks for the User.ReadBasic.All permission, which users can approve for
themselves in most organizations. You don’t need an administrator. If your organization doesn’t let
users approve apps, an administrator must approve it, or you can add people by object ID instead.
The permission is yours alone, is used only to search while you’re on the Members page, and is not
stored. The portal keeps just the names of members you save.
Add a service principal
A service principal is an identity for a script, a pipeline or an app, such as your deployment tool. You give it a role so it can use the workspace API.
- In Microsoft Entra, open Enterprise applications, find the service principal, and copy its Object ID. This is not the Application (client) ID.
- In the portal, open the workspace and choose Members.
- Choose Add an Entra ID service principal.
- Paste the Object ID, give it a Name that you’ll recognize, such as
Deployment pipeline, and choose Add. - Set its Role, and choose Save.
The portal can’t look up service principals in your directory, so it can’t check the object ID. If it’s wrong, the entry simply never matches anything, so double-check it.
Change or remove a member
On the Members page, change a person’s role with the Role menu on their row, or choose Remove to take their access away. Choose Save to apply your changes, or Discard to start again.
Changes apply to the next thing the person does: roles are checked on every request, so you don’t need to wait.
Rules that protect a workspace
- Only owners can change members. Everyone else sees the list, and a note saying so.
- You can’t remove your own Owner role. Your own row has no menu or Remove button. To hand a workspace over, add the new owner, then have them remove you. So a workspace always has an owner.
- Simultaneous edits don’t clobber each other. When you save, the portal checks that nobody has saved a change since you opened the page. If somebody did, your save is refused, and you see the members as they are now. This also stops two owners from removing each other at the same time.
- A save only removes members you were shown. A member added while you had the page open isn’t dropped by accident.
- Up to 200 members per workspace.
- The original buyer is remembered. If the person who bought a workspace loses their role, the Members page still notes who bought it.
The workspace API
The workspace API lets a service principal read a workspace and manage Macs and enrollment keys from a script. It’s useful for automating a rollout, such as creating a key for each batch of Macs and adding it to your MDM. It never touches billing.
It uses the roles above: a service principal can call only what its role allows. A workspace it has no role in, or a call its role doesn’t permit, is answered as 404 Not Found.
Sign in as a service principal
Request an app-only token for ProRDP’s portal app, using the client credentials flow, with the
scope api://<portal client ID>/.default. Send it as Authorization: Bearer <token>.
Only app-only tokens are accepted. A token acting on someone’s behalf is refused, and a personal Microsoft account can’t call the API. Ask us at hello@prordp.app for the portal’s client ID.
Endpoints
Bodies are JSON with snake_case names. All paths are on https://portal.prordp.app.
| Method and path | Role needed | What it does |
|---|---|---|
GET /api/workspaces | Any | Lists the workspaces it has a role in, with each one’s id, name and role. |
GET /api/workspaces/{id} | Reader | A workspace’s id, name, role and active_macs; licenses, how many Macs may be active (null if unlimited is true); and status: trialing, active, grace or lapsed. |
GET /api/workspaces/{id}/macs | Reader | Its active Macs. |
POST /api/workspaces/{id}/macs | Activator | Adds a Mac. Body: code, the Mac’s activation code. Returns 200 with the device_id and name if the Mac joined. Otherwise returns 409 with a code saying why, such as NeedsLicense. |
GET /api/workspaces/{id}/members | Reader | Its members: id, type, role, display_name and detail. |
GET /api/workspaces/{id}/enrollment-keys | Reader | Its enrollment keys. Never the keys themselves. |
POST /api/workspaces/{id}/enrollment-keys | Owner | Creates a key. Body: name, and optionally expires_at and max_macs. Returns 200 with the key’s id and the key, shown only this once. |
DELETE /api/workspaces/{id}/enrollment-keys/{key} | Owner | Revokes a key. Returns 204. |
Adding a Mac is rate-limited per address.
Example: create an enrollment key
This creates a key that admits up to 50 Macs and has no expiry date. It assumes
$TOKEN holds the app-only token and $WORKSPACE the workspace’s id:
curl -sS -X POST "https://portal.prordp.app/api/workspaces/$WORKSPACE/enrollment-keys" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "name": "Q4 rollout", "max_macs": 50 }'
Store the key from the response in your MDM straight away; you can’t retrieve it later. To
expire the key, add "expires_at" to the body.
Auditing
What a service principal does appears in the workspace’s history under the Name you gave it when you added it, so choose names that say what each one is for.
Good practice
- Keep owners to a few people. Owners can spend money and remove each other’s access.
- Give day-to-day staff Activator, and everyone who just needs visibility Reader.
- Use a service principal for automation, not a person’s account, so a script doesn’t stop when someone leaves.
- Give each service principal the lowest role it needs. A script that only reports on Macs needs Reader.
- Remove access when people move on. A removed member loses access at once.