Praman

Sign-in quickstart

Praman signs people up and in to your own app. You create a project in the dashboard; your app names that project on every sign-up and login.

  1. Create a project

    In the Notils dashboard, open Praman → Projects → New project. You need to be an owner or admin of the workspace. Choose a name and an id such as acme-shop: lowercase letters, digits and hyphens, starting with a letter, up to 28 characters. The id is how your app identifies itself, and it can't change later.

    Email and password sign-up, email verification and password reset work straight away. In the project's Configure pages you can add a logo for its emails, Google client ids, your Android app for invitation links, and a webhook.

  2. Sign someone up

    Every request goes to https://auth.notils.com. Sign-up and login need the X-Notils-App header with your project id:

    cURL
    curl https://auth.notils.com/v1/auth/signup \
  -H "X-Notils-App: acme-shop" \
  -H "Content-Type: application/json" \
  -d '{ "email": "ram@example.com", "password": "…", "name": "Ram Sharma" }'

    A 201 returns a token pair: a short-lived access_token, a refresh_token, expires_in in seconds, and the user, including email_verified. A common or breached password is refused with 422 password_too_common.

  3. Sign them in

    POST /v1/auth/login takes the same header and { "email", "password" }, and returns the same token pair. For Google, sign the person in with Google in your app, then send the ID token Google returns to POST /v1/auth/oauth/google as { "id_token" }. Google sign-in needs your client id on the project's Sign-in methods page.

    A wrong password and an unknown email both return 401 invalid_credentials, so nobody can find out who has an account.

  4. Keep them signed in

    Send Authorization: Bearer <access_token> to your own backend. When the access token expires, exchange the refresh token for a new pair; the old refresh token stops working at once.

    cURL
    curl https://auth.notils.com/v1/auth/token/refresh \
  -H "Content-Type: application/json" \
  -d '{ "refresh_token": "prt_…" }'

    If a refresh returns 401 refresh_token_reused, sign the person out and ask them to sign in again: never retry it. POST /v1/auth/logout ends one session and POST /v1/auth/logout/all ends all of them.

  5. Verify tokens on your backend

    Access tokens are ES256-signed JWTs. Check them against Praman's public keys at https://auth.notils.com/.well-known/jwks.json. Cache the keys, and fetch them again when a token names a key id you don't have.

Verification and password reset

Praman sends these emails for you, with your project's name and logo. Each one carries a 6-digit code your app asks the person to type in.

EndpointWhat it does
POST /v1/auth/email/verify/requestSigned in (Bearer token). Emails a verification code and returns 202 with retry_after_seconds: count that down before offering to resend.
POST /v1/auth/email/verify/confirm{ "token": "482913" } marks the email verified.
POST /v1/auth/password/forgotNeeds X-Notils-App. { "email" } always returns 204, whether or not an account exists.
POST /v1/auth/password/reset{ "token", "new_password" } sets the password and signs the account out everywhere.

Errors

Every error has the same shape: { "error": { "code", "message", "request_id" } }. Branch on code; the message is for people and may change. Sign-up, login and password reset are rate-limited and answer 429 rate_limited when a limit is reached.

See it in the dashboard

Each sign-up, sign-in and email appears in the project's Users, Activity and Emails pages, so you can check your integration as you build it. Test against a Development environment to keep test accounts out of Production.