Sign-in, people and keys
Signing in to the console, connecting a cradle, the first owner, inviting people, roles, and API keys with scopes.
Cradle has two kinds of access. People sign in to the console without a key: with their site account or with an e-mail code, and their rights come from their role in the organization of the cradle. Programs (bots, integrations, the CLI) call with an API key and scopes. A key is never typed into the console.
1. Sign in to the site
Open https://opencradle.ai/en/console. Enter your e-mail, press Send code,
type the code from the e-mail and press Sign in. The Continue with Google
button is not available on every site.
How to check. The console opens: on the left "Teams", "Cradles", "Security", "Settings".
If it did not work.
- "You are on the waiting list" — the site administrator opens access to the console; the e-mail will come to your address.
- "Too many requests. Wait a minute." — wait and request the code again.
- "Code expired or missing. Request a new code." and "Invalid code." — request a new code with Send again.
2. Connect a cradle
Open Cradles.
- A server on this very computer: the This computer card → Connect.
- A server behind the SSH tunnel of a GPU server: the GPU server card → Connect (Keys and models).
- Any other server: Add cradle → in the "New cradle" window fill in Name and URL (for example
http://<host>:31416), press Test, then Add server.
A cradle that trusts the site (all of them do by default) lets you in without a second sign-in. Publish an address outside your computer over HTTPS — see Remote server.
How to check. The cradle card says "online", and the "TEAM → CRADLE" table below lists its teams.
If it did not work.
- "unreachable" — there is no server at that address or the network blocks it: check
curl <URL>/api/v1/health. - "Sign-in needed" — the cradle did not accept the site's token; press Sign in and follow step 4.
- "You are not in any organization on this cradle" — nobody added you; steps 3 and 5.
3. The first owner
A cradle with no members at all goes to the first person with a valid token who
comes from this same machine (an SSH tunnel to a GPU server counts too). That
person becomes the owner of the organization default. Pressing Connect on
the This computer card is enough for that.
For a server you reach over the network this does not happen — you get a 403
not_a_member. The operator with an admin:* key (for example, the installer's
key) creates the owner in one of two ways:
A service environment variable — the owner is created at every server start:
CRADLE_BOOTSTRAP_OWNER=you@example.comOr a command:
cradle members add --org default --email you@example.com --role ownerA new organization instead of default: cradle members create-org <slug> --owner <e-mail> [--name <name>] [--plan free|pro]. The list of organizations is
cradle members orgs.
How to check.
cradle members list --org defaultThe table has your e-mail with the role owner.
If it did not work. error: organization not found — wrong organization
slug: look at cradle members orgs. If members already exist there will be no
automatic owner: add people with the command above.
4. Signing in to the cradle with a code
It is needed when the cradle does not trust the site (in a closed contour the
trust is switched off with CRADLE_CONSOLE_ISSUER=off) or when you were added
with cradle members add. The card says "Sign-in needed": press Sign in,
enter the E-mail, press Get a code, enter "Code from the e-mail — 6
digits" and press Sign in.
The code is 6 digits, lives 10 minutes and allows 5 attempts. If the cradle has
no mail configured (settings.smtp in app-state.json: host, port, secure,
user, password, from), there is no e-mail, and the operator fetches the code:
cradle users code you@example.comThe same code is printed to the server log as the line [auth] login code for <e-mail>: <code>.
Only a person who has been created can get a code: cradle users add <e-mail>
or cradle members add ….
How to check. The cradle card says "online", the teams open.
If it did not work.
- "The code did not match or has expired." — request a new one (Another e-mail, then Get a code again).
- "The account is disabled by the operator." —
cradle users enable <e-mail>. - "You are in no organization of this cradle. Ask its owner to add you" — step 5.
- "The cradle did not answer." — check the address and the server.
5. Invite people
The operator with an admin:* key (<subject> in the last command comes from the
SUBJECT column of the list):
cradle members add --org default --email colleague@example.com --role member
cradle members list --org default
cradle members remove --org default --subject <subject>The person then adds the cradle in the console and signs in with a code (step 4).
To close access temporarily use cradle users disable <e-mail> (sessions are
revoked); cradle users enable <e-mail> brings it back; the list of people is
cradle users list.
The role sets a person's rights:
| Role | What it can do |
|---|---|
member | the working set of the console: messages, agents (read, change, run), knowledge bases, tickets (read, approve), conversations, models, reading teams, channels and settings |
admin | all of that plus managing the organization: teams, channels, risk rules, budgets, settings; adds and removes only members |
owner | everything admin can; changes roles and removes admins; the last owner cannot be removed |
The console has no members screen: manage them with the cradle members …
commands above.
How to check. cradle members list --org default shows the person with the
right role.
If it did not work. The person sees a 403 not_a_member — they are not in
the organization or they sign in to another cradle; check the e-mail in the list.
6. API keys and scopes
A bot, an integration, a script or an MCP client needs a key. The operator with
an admin:* key issues it. A key is bound to one team — by its id (not its slug):
cradle teams list --json
cradle keys create --name "site-bot" --scopes messages:read,messages:write --team <team-id>In the teams list --json answer the team you need has an id field — put it
into --team.
Without --team the command answers error: team not found: personal. The key is
printed once (plaintext), the server keeps only the hash. An optional expiry is
--expires-at <Unix milliseconds>. The list is cradle keys list, revoking is
cradle keys revoke <id> (the full id is in cradle keys list --json).
A key can only hold these scopes:
| Scope | What it opens |
|---|---|
messages:write | send a message to the HTTP API: POST /api/v1/messages; MCP cradle_submit_issue |
messages:read | collect replies GET /api/v1/messages/:chatId, GET /api/v1/admin/health, the event stream GET /api/v1/events |
agents:read, agents:write, agents:execute | read agents; create and change them; run one without a ticket (POST /api/v1/admin/agents/:id/execute) |
kb:read, kb:write | read knowledge bases and search; create, upload, delete |
models:read, models:write | read models and provider keys; register models and save keys |
models:infer | POST /v1/messages and GET /v1/models (the Anthropic-compatible endpoint) |
tickets:read, tickets:approve | read tickets; approve, reject, reassign |
conversations:read | conversations and tasks; reply files GET /api/v1/files/:id |
teams:read, channels:read | see teams and channel status |
settings:read, settings:write | read and change cradle settings |
admin:* | everything, including issuing keys and managing people |
The org:admin scope is part of a person's role; it cannot be given to a key
(the answer is 400). A key with admin:* can choose the team with the header
X-Cradle-Team: <slug>; other keys work only in their own team.
How to check.
curl -s -H "Authorization: Bearer ck_live_..." http://127.0.0.1:31416/api/v1/auth/meThe answer has "kind":"key", teamSlug and the list of your key's scopes.
If it did not work. 401 unauthorized — the key is wrong, revoked or expired;
403 with a missing field — the scope named there is not granted; unknown scope: …
when issuing — the scope is not in the table above.