Give a person a role
This page needs your own installation with an Embed license.
PUT/
Gives a person a role in one of an account’s workspaces.
Needs a partner key: Authorization: Bearer gre_…, from Platform › Partner keys. Call it from your server only.
Parameters
Path
accountIdRequired · stringYour ID for the customer’s account: 1 to 255 bytes of UTF-8, case-sensitive. URL-encode it: it may contain
/.userIdRequired · stringYour ID for the person.
Body
roleRequired · stringviewer,operatororeditor.workspaceIdOptional · stringYour workspace ID. Left out: the default workspace.
userOptional · objectThe person’s
nameandemail, to create someone new.
When the role changes
The person’s older sessions in that workspace end (role_changed) and come back at the new role.
Responses
- 200OK
Updated.
- 201Created
The membership is new.
A field isn’t valid.
details.fieldnames it.- 404
NOT_FOUNDNo such account, workspace or person. Send
user.nameto create the person. The account is deleted. Restore it first, within 30 days.
Something failed on the installation’s side. Try again.
Any call can also answer: 401 UNAUTHORIZED · 403 EMBED_NOT_LICENSED · 403 IP_NOT_ALLOWED · 413 PAYLOAD_TOO_LARGE · 415 INVALID_CONTENT_TYPE · 429 RATE_LIMITED · 503 BUSY. See Errors.
Request
GORUNNER="https://automations.example.com"
GORUNNER_EMBED_KEY="YOUR_PARTNER_KEY" # gre_…
ACCOUNT_ID="acct-bakery"
USER_ID="ada-123"
URL="$GORUNNER/api/embed/v1/accounts/$ACCOUNT_ID/"
URL="${URL}members/$USER_ID"
curl -X PUT "$URL" \
-H "Authorization: Bearer $GORUNNER_EMBED_KEY" \
-H "Content-Type: application/json" \
-d '{
"role": "operator",
"workspaceId": "ws-orders"
}'const GORUNNER = "https://automations.example.com";
const KEY = process.env.GORUNNER_EMBED_KEY; // gre_…
const ACCOUNT_ID = encodeURIComponent("acct-bakery");
const USER_ID = encodeURIComponent("ada-123");
const res = await fetch(
`${GORUNNER}/api/embed/v1/accounts/` +
`${ACCOUNT_ID}/members/${USER_ID}`,
{
method: "PUT",
headers: {
Authorization: `Bearer ${KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
role: "operator",
workspaceId: "ws-orders",
}),
},
);
const { data } = await res.json();import os, requests
from urllib.parse import quote
GORUNNER = "https://automations.example.com"
KEY = os.environ["GORUNNER_EMBED_KEY"] # gre_…
ACCOUNT_ID = quote("acct-bakery", safe="")
USER_ID = quote("ada-123", safe="")
res = requests.put(
f"{GORUNNER}/api/embed/v1/accounts/"
f"{ACCOUNT_ID}/members/{USER_ID}",
headers={"Authorization": f"Bearer {KEY}"},
json={
"role": "operator",
"workspaceId": "ws-orders",
},
)
data = res.json()["data"]Response · 200 OK
{
"data": {
"user": {
"id": "ada-123",
"name": "Ada Lovelace",
"email": "ada@bakery.example"
},
"workspace": {
"id": "ws-orders",
"default": false
},
"role": "operator",
"createdAt": "2026-10-22T10:00:00Z"
}
}Every field
Body
roleRequired · stringOne of
viewer,operator,editor.workspaceIdOptional · stringOmitted = the account’s default workspace (
defaultnames it too); the empty value is refused.userOptional · objectnameOptional · stringRequired to create. Left out or null: left as it is.
emailOptional · string or nullContact data only. Left out: left as it is. Null or empty clears it. Must look like an email address.
Response · 200 OK, 201 Created
dataobjectuserobjectidstringnamestringemailstring or nullworkspaceobjectidstring or nullThe partner’s workspace id; null for the default workspace.
defaultbooleanrolestringOne of
viewer,operator,editor.createdAttime