Deploy and run
Sign-in for your app
Let the users of your app sign in with an emailed code or their wallet. CLI keeps the users and gives your app a signed token to check.
Your app can let its users sign in without you building an account system. They get a code by email, or sign with their crypto wallet, and CLI tells your app who they are. There are no passwords for you to store or leak.
How to do it: in project settings, open Sign-in for your app, give it your app's name and the web addresses users may be sent back to, and press Turn on sign-in. Then add the short snippet from the technical version to your app.
"Add email sign-in to my app using CLI's sign-in for apps."
You can see and remove users from the same panel.
Your app can have sign-in without you building or running an auth service. Its users sign in with a code sent to their email, or by signing a message with their wallet. CLI keeps the users and gives your app a token (a JWT signed with Ed25519) that says who they are. There are no passwords to store.
Turn it on
In project settings, Sign-in for your app, give the app a name (it appears in the emails) and the URLs it may send people back to, then choose Turn on sign-in.
PUT /v1/projects/:id/auth {"name": "Acme Shop", "redirects": ["https://shop.acme.com/callback"]}To send the codes from your own domain instead of CLI's, set emailFrom to an address on a verified email domain (/docs/email). Those emails are charged like any other.
Sign a user in
Your app calls these public endpoints. <issuer> is https://<your CLI>/v1/auth-apps/<project id>.
With an emailed code:
POST <issuer>/email/start {"email": "[email protected]"}sends a six-digit code, good for 10 minutes.POST <issuer>/email/verify {"email", "code"}returns{token, expiresAt, user}.
After five wrong codes the user has to ask for a new one, and codes can be asked for once a minute.
With a wallet:
POST <issuer>/wallet/challenge {"address"}returns a message to sign.- The user signs it in their wallet, then
POST <issuer>/wallet/verify {"address", "message", "signature"}returns the token.
Check the token
The token is a JWT with iss (the issuer), aud (the project id), sub (the user's id), and email or wallet. Check it either way:
- Yourself: verify the EdDSA signature with the keys at
<issuer>/jwks.json, then checkaud,issandexp. Any JWT library that supports EdDSA does this. - By asking CLI:
GET <issuer>/mewithAuthorization: Bearer <token>returns the user, and refuses tokens for disabled or deleted users.
Sessions last a week unless you set sessionHours.
Manage users
Sign-in for your app lists the users and when they last signed in. Admins can disable a user (their tokens stop working at /me, and they can't sign in again) or delete them (DELETE /v1/projects/:id/auth/users/:userId).
Each project's tokens are signed with its own key, so one app's tokens never work for another. Agents can set this up with cli_app_signin.