Docs menu

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.

Explain it

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.

API
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:

  1. POST <issuer>/email/start {"email": "[email protected]"} sends a six-digit code, good for 10 minutes.
  2. 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:

  1. POST <issuer>/wallet/challenge {"address"} returns a message to sign.
  2. 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 check aud, iss and exp. Any JWT library that supports EdDSA does this.
  • By asking CLI: GET <issuer>/me with Authorization: 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.