---
name: superbot-auth
description: Sign a user in to Superbot with an emailed code and get a working token in one session. Use it when a Superbot call answers 401 and the user has no account.
---
# Sign your user in to Superbot
You need the user's email address and the 8-character code Superbot emails them.
Ask for the address if you do not have it.
Use the web origin `https://superbot.gg` for every step, because the API host mails a code only to an address that already has an account.

## 1. Ask for the code
Tell the user: "I will have Superbot email you a sign-in code. Tell me the code when it arrives."
`curl -sS -X POST https://superbot.gg/auth/email/start -H 'content-type: application/json' -d '{"email":"USER_EMAIL","kind":"cli","via":"agent"}'`
It answers 202 for every address, so a 202 does not prove a mail was sent.
No mail after 2 minutes: ask the user to check spam, then start once more.
A 429 means wait for the Retry-After seconds.

## 2. Verify the code
`curl -sS -X POST https://superbot.gg/auth/email/verify -H 'content-type: application/json' -d '{"email":"USER_EMAIL","code":"CODE","kind":"cli","via":"agent","device_name":"YOUR NAME"}'`
Send the code as a string, so a leading zero survives.
A 200 gives access_token, refresh_token, device_id and created.
A 400 invalid_code or expired means ask the user for the code again, or start over.
The token lasts 90 days and the user can revoke it in their account. Keep it secret.
Send it as `Authorization: Bearer sbk_…` on every call.

## 3. Check access
`curl -sS https://superbot.gg/v1/beta/status -H 'Authorization: Bearer sbk_…'`
When sign-up is open this grants the account on the spot, and `{"granted":true}` means you are in.
`{"granted":false}` means sign-up is invite only right now.
Ask the user for an invite code, then `curl -sS -X POST https://superbot.gg/v1/beta/redeem -H 'Authorization: Bearer sbk_…' -H 'content-type: application/json' -d '{"code":"INVITE_CODE"}'`.
No code yet: the user can ask for one at https://superbot.gg/invite.

## 4. Make your first call
Connect the MCP server `https://superbot.gg/mcp` with the same Bearer, or call `GET https://superbot.gg/answer?intent=...` with it.
This token does not work on the model routes under /v1. Those need an `sbc_` caller key, which you mint with the same Bearer:
`curl -sS -X POST https://superbot.gg/v1/keys -H 'Authorization: Bearer sbk_…' -H 'content-type: application/json' -d '{"name":"YOUR NAME"}'`
A 201 gives `{"key":"sbc_…","row":{…}}`. Keep the value of `key` now, because it is shown once.
Send it as `Authorization: Bearer sbc_…` on the model routes. Signing this device out revokes it.

## If the email path fails
Use the device grant: `POST https://superbot.gg/oauth/device/code` with `{}`, show the user the verification_uri_complete, then poll `POST https://superbot.gg/oauth/token` with grant_type urn:ietf:params:oauth:grant-type:device_code.