Quickstart

You need a DevSewa account and a backend that can keep a secret — any server-side runtime will do. Nothing in this guide runs in a browser.

1. 1

   Create an application

   In the console open Auth → Applications → New application. Give it a display name, a tenant slug (lowercase, digits, single underscores) and pick test. You get a Client ID immediately.
2. 2

   Generate a client secret

   On the Credentials tab press Generate secret. It is shown once — store it in your backend’s secret store as DEVSEWA_CLIENT_SECRET.
3. 3

   Create a test user

   Open Users → Create user, or connect your own signup form to POST /v1/auth/signup. A test key stops in DevSewa Sandbox; AUTH_APP and every other live engine remain untouched.
4. 4

   Handle the auth outcome

   Follow outcome and required_action for e-mail verification or MFA. An authenticated response carries a single-use ticket; exchange it server-side:

curl -X POST https://auth.api.devsewa.com/v1/auth/signup \
  -H "Authorization: Bearer $DEVSEWA_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "email": "ada@acme.com", "password": "choose-a-strong-password", "client_ip": "203.0.113.10" }'

{ "success": true,
  "outcome": "VERIFY_EMAIL_REQUIRED",
  "required_action": { "type": "verify_email", "description": "…" },
  "user": { "user_id": "…", "email": "ada@acme.com" },
  "ticket": null }

The call belongs on your backend. DevSewa derives the tenant from the client secret; neither the browser nor your request can select another application’s user pool.

curl -X POST https://auth.api.devsewa.com/v1/auth/exchange \
  -H "Authorization: Bearer $DEVSEWA_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "ticket": "tkt_…" }'

{ "ok": true,
  "user": { "subject": "usr_…", "email": "ada@acme.com", "name": "Ada" } }

Create your own session for user.subject. The ticket is single-use and scoped to the tenant that issued it; a second exchange fails.

Add DATABASE_URL under the application’s Secrets tab, then read it at start-up with the same credential:

curl https://auth.api.devsewa.com/v1/secrets/DATABASE_URL \
  -H "Authorization: Bearer $DEVSEWA_CLIENT_SECRET"

{ "name": "DATABASE_URL", "value": "postgres://…" }