Make a token
This page needs your own installation with an Embed license.
POST/
Makes an API token for one of an account’s workspaces, for your automation or for the customer.
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
/.
Body
Send access or scopes, not both: a token never gets rights by default.
nameRequired · stringUp to 100 characters, to recognise it later.
accessOptional · stringread,runorbuild, each including the one before. Narrowed by the account’s switches.workspaceIdOptional · stringYour workspace ID. Left out: the default workspace.
surfacesOptional · array of strings["api"](the default), or withmcpfor AI apps, which needs the MCP switch.expiresInDaysOptional · integer7 to 365. The default is 90.
What are the rarely used parameters?
scopesOptional · array of stringsExact permissions instead, such as
workflow:readandrun:read.turnOffOptional · array of stringsSwitches turned off for this token alone.
What it may do
No more than an editor of the account, and never in another account. It is checked on every request: it stops while the Tokens switch is off, only reads while the account is suspended, and is revoked when the account is deleted or the partner key that made it is revoked. Rotating that key doesn’t stop it.
With mcp, AI apps use it at /mcp/tools, and /mcp/build while MCP building is on. It takes no Idempotency-Key, so a stored answer never keeps the token: a retry makes a second one. See Tokens and AI apps.
Responses
- 201Created
Made.
rawis the token,grt_and 40 hex characters, shown this once. A field isn’t valid, or neither
accessnorscopeswas sent.- 403
FEATURE_OFFThe Tokens switch is off for this account, or
surfaceshasmcpwhile the MCP switch is off (details.switch). - 403
FORBIDDENThe partner key that sent it can no longer make tokens.
- 404
NOT_FOUNDNo such account, or no such workspace in it.
The account is deleted. Restore it first, within 30 days.
- 409
TOKEN_LIMITThe workspace already has 25 tokens that work. Revoke one first.
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"
URL="$GORUNNER/api/embed/v1/accounts/$ACCOUNT_ID/"
URL="${URL}tokens"
curl -X POST "$URL" \
-H "Authorization: Bearer $GORUNNER_EMBED_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Nightly sync",
"access": "run",
"expiresInDays": 90
}'const GORUNNER = "https://automations.example.com";
const KEY = process.env.GORUNNER_EMBED_KEY; // gre_…
const ACCOUNT_ID = encodeURIComponent("acct-bakery");
const res = await fetch(
`${GORUNNER}/api/embed/v1/accounts/` +
`${ACCOUNT_ID}/tokens`,
{
method: "POST",
headers: {
Authorization: `Bearer ${KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "Nightly sync",
access: "run",
expiresInDays: 90,
}),
},
);
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="")
res = requests.post(
f"{GORUNNER}/api/embed/v1/accounts/"
f"{ACCOUNT_ID}/tokens",
headers={"Authorization": f"Bearer {KEY}"},
json={
"name": "Nightly sync",
"access": "run",
"expiresInDays": 90,
},
)
data = res.json()["data"]Response · 201 Created
{
"data": {
"token": {
"id": "6e9a1c3f-8b2d-4a57-9e0c-3f7b5d1a8c42",
"name": "Nightly sync",
"prefix": "grt_3f9a1c2b",
"access": "run",
"scopes": [
"workflow:read",
"connection:read",
"run:read",
"workflow:run",
"run:manage"
],
"surfaces": [
"api"
],
"workspaceId": null,
"createdBy": {
"kind": "partner"
},
"createdAt": "2026-10-25T09:00:00Z",
"expiresAt": "2027-01-23T09:00:00Z",
"lastUsedAt": null,
"expiring": false,
"turnedOff": []
},
"raw": "grt_3f9a1c2b…"
}
}Every field
Body: any.
name and one of access or scopes are required; send access or scopes, not both. Neither is 400 VALIDATION_ERROR with details.field access: a token is given what it can do on purpose, never by default.
The body takes one of 2 forms.
Response · 201 Created
dataobjecttokenobjectAn API token made in an embed: on the Tokens page by an editor, or by your server. Never the token itself.
idUUIDnamestringprefixstringThe token’s first characters (
grt_and 8 more), to tell tokens apart.accessstringThe widest level its scopes reach: read; run (also start, cancel and re-run runs); build (also create and change workflows and connections).
custom: it was made withscopesthat are not exactly one of those levels.One of
read,run,build,custom.scopesarray of stringssurfacesarray of stringsWhere it works:
api(the App API) andmcp(AI apps, over MCP).One of
api,mcp.workspaceIdstring or nullThe partner’s id of its workspace; null for the account’s default workspace.
createdByobjectkindstringOne of
person,partner.idstringThe partner’s user id of the editor who made it (kind person).
namestringcreatedAttimeexpiresAttimelastUsedAttime or nullexpiringbooleanIt stops within seven days.
turnedOffarray of stringsSwitches turned off for this token alone.
rawstringThe token,
grt_and 40 hex characters. Shown once.