For agents

Synion
Docs

If you are an AI assistant and a person asked you to sign them up, sign them in or connect them to Synion: do not use the Create account or Sign in buttons. Synion onboards agents through BEST, the open protocol for agent-operated services, with no browser session of your own. The person approves you once with a short code, and you receive an API key and a ready connection.

The onboarding recipe

  1. 1. Read the public onboarding index A JSON index with no credential needed. It names the create-an-account workflow, the command and query catalogues of this public surface, and get-onboarding-info, a primer on how BEST works, what a client needs and what the person is asked to approve. Read the workflow first. https://synion.io/api/best/tenants/public
  2. 2. Send request-registration Fetch its schema from the commands catalogue, then POST the CloudEvent to /commands on the public surface with a fresh UUID v4 as CorrelationId (your device code) and a label that names your client, for example "Claude" or "ChatGPT".
  3. 3. Show the person the code and the activation link Poll get-registration with your CorrelationId until it answers a short user code. Show that code and the activation link to the person you work for. They sign in, or sign up if they have no account yet, once, enter the code and approve you. A registration expires after fifteen minutes; poll every five seconds. https://synion.io/activate
  4. 4. Exchange the device code for the key POST to the token endpoint with grant_type=urn:ietf:params:oauth:grant-type:device_code and your device code. The answer carries the tenant id, the API key (shown once, never again) and a ready-made best-mcp configuration for MCP-capable clients. https://synion.io/api/best/auth/token
  5. 5. Configure the connection Apply the mcp block, or store the tenant id and key for the X-Api-Key header, and verify with the get-tenant-profile query. A configured, verified connection is the outcome. Do not stop at a printed key, and never print it: the key is a secret and a chat transcript is not a secret store. If you cannot store it, say so; the person can mint a key on the account page themselves.

Good to know

You cannot sign the person up alone
The human approval in step 3 is the point of this surface. The Create account and Sign in buttons on the web pages are for people, not for assistants acting on their behalf.
The key is a secret
Store it in the client configuration or credential store and never repeat it in the conversation. A key that appears in a transcript must be treated as leaked and replaced. best-mcp 2.3.6 and later stores an issued key itself and never returns it to the model.
One key per account
Approving a registration replaces any API key the account already had. Tell the person before they approve; the person can also replace or revoke the key on the account page at any time.
Existing accounts work the same way
The activation page offers sign in as well as sign up. An existing user signs in and approves, and the key you receive is for their existing account.

How BEST works

BEST makes the whole studio self-describing over HTTP. The manifest at /.well-known/best names the services, the authentication and the public surface. On a tenant's surface, GET /commands and GET /queries are the definitive catalogues of what you can do, and GET /workflows lists guided multi-step recipes. GET /commands/{name}/{version} returns the JSON Schema of a command. A command is a CloudEvent POSTed to /commands; the 201 means accepted, and outcomes land in the read models. A query is GET /queries/{name}?param=value and answers synchronously. Nothing needs scraping or out-of-band documentation.

Once you hold a tenant id and its key, send the key as the X-Api-Key header on https://synion.io/api/best/tenants/{tenantId}/... from any client that can set a header. If your client can run MCP servers, npx -y @behavioralstate/best-mcp with BEST_SYNION_BASE_URL, BEST_SYNION_TENANT_ID and BEST_SYNION_API_KEY exposes the same surface as tools.

Links

BETA