MyBotBoxMyBotBox
SDKs

Authentication

API keys, token scopes, gh-style CLI login, and OAuth 2.0 app linking for the MyBotBox API, SDKs, and CLI.

Every request to the MyBotBox management and execution API is authenticated. There are three ways to authenticate, depending on who is calling:

  • Personal API keys — for your own scripts, the SDKs, and server-to-server calls.
  • The CLI — mybotbox auth login mints and stores a personal API key for you via a browser-based device flow, the same shape as gh auth login.
  • OAuth 2.0 — for third-party applications that act on a user's behalf, with consent and revocable access.

All three resolve to the same authenticated identity and are subject to the same token scopes.

Personal API keys

A personal API key authenticates as you and inherits your access. Create one from Settings → API keys in the dashboard, then send it on every request as the X-API-Key header.

curl https://app.mybotbox.com/api/workflows \
  -H "X-API-Key: $MYBOTBOX_API_KEY"
import { MyBotBoxClient } from '@yarlisai/studio-sdk'

const client = new MyBotBoxClient({ apiKey: process.env.MYBOTBOX_API_KEY })
const { data } = await client.listWorkflows()
from ystudio import MyBotBoxClient

client = MyBotBoxClient(api_key=os.environ["MYBOTBOX_API_KEY"])
workflows = client.list_workflows()

Treat an API key like a password. It is shown only once at creation. Store it in a secret manager or an environment variable — never commit it. Revoke a leaked key immediately from Settings → API keys.

Token scopes

Every key (and every OAuth grant) carries a set of scopes that bound what it can do. Read endpoints require a :read scope, mutations require :write, and running or deploying a workflow has its own scope. A request whose token lacks the required scope is rejected with 403 insufficient_scope.

ScopeGrants
workflow:readView your workflows
workflow:writeCreate and edit your workflows
workflow:executeRun your workflows
workflow:deployDeploy your workflows as APIs
project:readView your projects
project:writeCreate and edit your projects
workspace:readView your workspaces
workspace:writeManage your workspaces
account:readView your account profile
*Full access (wildcard) — everything above

Keys created before scopes existed carry the * wildcard, so they keep full access. Grant the narrowest set of scopes a token actually needs.

CLI login (browser device flow)

The CLI authenticates with a browser-based OAuth 2.0 Device Authorization Grant (RFC 8628) — you never paste a key. On approval it mints a personal API key and stores it locally.

Run the login command:

mybotbox auth login

It prints a short user code and opens your browser:

  Opening https://app.mybotbox.com/login/device in your browser…
  Enter the code: WDJB-MJHT

Sign in (if needed), confirm the requested scopes, and approve. The CLI finishes automatically:

  ✓ Logged in as you@example.com on app.mybotbox.com

Verify and use it:

mybotbox auth status
mybotbox workflow list

The minted key is stored in ~/.mybotbox/hosts.json (file mode 0600), keyed by host, so you can be logged into multiple instances at once. It is a normal personal API key — revocable from Settings → API keys.

Options and overrides

Flag / variablePurpose
--host <host>Target a non-default instance (e.g. staging-app.mybotbox.com). Default: app.mybotbox.com.
--scope "<scopes>"Space-delimited scopes to request. Default: the standard CLI set.
MYBOTBOX_TOKENUse this token instead of the stored credential (ideal for CI).
MYBOTBOX_HOSTDefault host when --host is omitted.

mybotbox auth logout removes the stored credential for a host.

In CI, skip the interactive flow entirely: set MYBOTBOX_TOKEN (a personal API key) and MYBOTBOX_HOST, and every command uses them directly.

Building your own device-flow client

The device endpoints are public so you can build your own integration:

Start the flow:

curl -X POST https://app.mybotbox.com/api/auth/device \
  -H "Content-Type: application/json" \
  -d '{ "client_id": "mybotbox-cli", "scope": "workflow:read workflow:execute" }'

Response: device_code, user_code, verification_uri, verification_uri_complete, interval, expires_in. Show the user_code and direct the user to verification_uri.

Poll the token endpoint at interval seconds until the user approves:

curl -X POST https://app.mybotbox.com/api/auth/device/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
    "device_code": "…",
    "client_id": "mybotbox-cli"
  }'

While pending, the endpoint returns authorization_pending (keep polling) or slow_down (back off). On approval it returns the minted personal API key once as access_token. expired_token and access_denied are terminal.

Connecting third-party apps (OAuth 2.0)

To let a third-party application act on a user's behalf — with a consent screen and revocable access — use the OAuth 2.0 Authorization Code flow with PKCE.

Register a client. Create an OAuth app via POST /api/oauth/clients (or the developer settings UI) with your redirect_uris and the scopes it needs. You receive a client_id (and a client_secret for confidential clients).

Authorize. Redirect the user to the consent screen:

GET https://app.mybotbox.com/oauth/authorize
  ?response_type=code
  &client_id=<client_id>
  &redirect_uri=<your_redirect_uri>
  &scope=workflow:read%20workflow:execute
  &code_challenge=<base64url-sha256>
  &code_challenge_method=S256
  &state=<csrf_token>

The user must be signed in, then approves the requested scopes. MyBotBox redirects back to your redirect_uri with a short-lived code.

Exchange the code at the token endpoint (PKCE-verified; confidential clients also send client_secret):

curl -X POST https://app.mybotbox.com/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=<code>" \
  -d "client_id=<client_id>" \
  -d "redirect_uri=<your_redirect_uri>" \
  -d "code_verifier=<pkce_verifier>"

You receive an access_token and a refresh_token. Call the API with Authorization: Bearer <access_token>.

Refresh when the access token expires — refresh tokens rotate, so store the new pair each time:

curl -X POST https://app.mybotbox.com/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=<refresh_token>" \
  -d "client_id=<client_id>"

Users see and revoke every connected application from Settings → Connected Applications; you can revoke a token programmatically via POST /api/oauth/revoke.

Public clients (mobile, SPA, CLI) must use PKCE and have no client secret. Tokens and authorization codes are stored hashed; client secrets are encrypted at rest.

See also

  • TypeScript SDK — MyBotBoxClient, execution + management methods
  • Python SDK — the same surface for Python
  • CLI — full command reference
Workflow Block YAML SchemaPython SDK
On this page

On this page

Personal API keys
Token scopes
CLI login (browser device flow)
Options and overrides
Building your own device-flow client
Connecting third-party apps (OAuth 2.0)
See also