Partner API

Provision your customers, sign them in, and run their workflows from your server.

Embed · Self-hosted with an Embed license

GORUNNER="https://automations.example.com"
GORUNNER_EMBED_KEY="YOUR_PARTNER_KEY"  # gre_…, from Platform › Partner keys

curl -X POST "$GORUNNER/api/embed/v1/login-codes" \
  -H "Authorization: Bearer $GORUNNER_EMBED_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user": { "id": "ada-123", "name": "Ada Lovelace" },
    "account": { "id": "acct-bakery", "name": "Bakery Ltd" },
    "role": "editor"
  }'

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "These switches don't exist: stepData.",
    "details": { "field": "turnOff", "unknown": ["stepData"] }
  }
}

The IDs are yours

Accounts, workspaces, people and managed connections are named by your own IDs: 1 to 255 bytes of UTF-8, no control characters, compared byte for byte. An ID may contain /, so URL-encode it in a path: /accounts/acct%2F42.

An email is only ever contact information: it never identifies a person or links two. A PUT creates or updates by your ID, so sending it twice leaves the same state.

Idempotency

These POSTs take an Idempotency-Key (up to 255 characters), so a retry after a dropped connection never acts twice: suspend, resume and restore an account; allow a website; install, enable and disable a workflow; cancel its waiting runs; cancel a run and run it again; disconnect an account’s or every AI app.

Keys belong to the partner key that sent them. A login code and a token take none: an unused code runs out in a minute, and a stored answer would keep a token for a day, so a retry makes a second one that you can revoke. Starting a connection sign-in and signing a person in for an AI app take none either.

Lists

Lists page with a cursor, each in the order its page states. Send limit (1 to 100, 50 by default) and, for the next page, the cursor the last page gave. nextCursor is null on the last page; a page that comes back full can carry a cursor with nothing after it, and the next page is then empty. Send a cursor back exactly as it came.

{ "data": [ … ], "pagination": { "limit": 50, "nextCursor": "…" } }

Limits

The windows are fixed minutes, shared by every server of the installation. A request one limit refuses isn’t counted by the others, so one customer over its limit uses up nothing of your key’s. One address may also send at most four times API_RATE_LIMIT a minute to each server.

Over a limit, the answer is 429 RATE_LIMITED with Retry-After. X-RateLimit-Limit and X-RateLimit-Remaining describe the tightest window, and X-RateLimit-Scope names it: key, account, person or session.

Throttle your own login-code route for each person too. Every frame that opens, and every renewal through your page, is one login code; a frame renews by itself for up to 12 hours, so most renewals never reach your server.

The record

Every call with your key leaves a row in the audit log of the account it was about, except reading an AI app sign-in request: the route, the status, the request ID, the key, and whether it was a replay. Never a body. The changes themselves, such as an account created or a role changed, leave rows of their own.

Errors

Each endpoint lists the codes it answers. For every code, see Error codes.

The frame’s own routes

Five routes take no partner key, and the SDK and the frame call them for you. Check the installation can be embedded is public. Start a session swaps a login code for a session (gri_…), which can renew itself, sign out or turn more switches off.

Every endpoint 59

By name, path or method, such as runs or POST.