Authentication API

Authenticate against the SpireStock API with an API key or a session token. Covers the X-API-Key header, JWT sign-in, OTP, magic links and the desktop code exchange.

5 endpointsBase URL https://api.spirestock.com/api/v1

Every request needs an API key or a session token. Last updated .

On this page (5)

POSThttps://api.spirestock.com/api/v1/auth/login

Authenticate with email and password. Returns a JWT token, user profile, navigation modules, and workspace details. Accounts imported from a previous system sign in with their existing password: a Django pbkdf2_sha256 hash is verified and transparently upgraded to bcrypt on the first successful login, with no change to the request or response. In production the request must also carry a Cloudflare Turnstile token, so servers should use an API key instead. Five failed attempts lock the account for 30 minutes.

Request body

emailstringrequired
User email address
passwordstringrequired
Account password
Example request
curl -X POST https://api.spirestock.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'
Example response
{
  "response_code": 200,
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": 1,
    "salutation": "Mr",
    "first_name": "John",
    "middle_name": "",
    "last_name": "Doe",
    "store_name": null,
    "store_image": null,
    "official_email": "[email protected]",
    "primary_contact_number": "9876500020",
    "emp_sap_id": "EMP-001",
    "organization_id": 5,
    "organization_name": "Acme Dairy",
    "department_id": 129,
    "department_name": "Sales and Marketing",
    "role_id": 1,
    "role_name": "Admin",
    "reporting_to_id": null,
    "reporting_to_name": "Sample Manager",
    "reporting_to_emp_id": null,
    "profile_image": "https://media.example.com/sample.png",
    "device_id": "",
    "last_login": "2026-10-22T09:02:36.636Z",
    "last_auth_method": "password",
    "auth_methods_used": [
      "password"
    ],
    "onboarding_state": {
      "tour": {
        "variant": "admin",
        "last_step": 3,
        "completed_at": null,
        "dismissed_at": null,
        "remind_after": "2026-10-25T08:47:20.675Z"
      },
      "checklist": {
        "dismissed_at": "2026-10-22T08:47:20.682Z"
      }
    },
    "last_ip": "203.0.113.10",
    "status": 1,
    "user_type": 0,
    "is_distributor": 0,
    "is_super_stockist": 0,
    "is_retailer": 0,
    "is_tagged": 0,
    "tagged_by": null,
    "tagged_date": null,
    "periphery": null,
    "timing": null,
    "latitude": null,
    "longitude": null,
    "self_owned": 0,
    "other_brand_id": null,
    "other_brand_name": null,
    "retailer_type_id": null,
    "retailer_class_type_id": null,
    "purchase_milk_from_org": 0,
    "visit_date_time": null,
    "created_by": 41500,
    "oauth_provider": null,
    "portal_onboarding_completed_at": null,
    "app_version": null,
    "createdAt": "2020-10-10T05:08:33.000Z",
    "updatedAt": "2026-10-22T09:02:36.636Z",
    "sp_role": {
      "id": 0,
      "role_name": "Super Admin"
    },
    "basicDetails": null
  },
  "modules": [
    {
      "id": 1,
      "name": "Orders",
      "icon": "shopping-cart",
      "link": "/orders",
      "subModules": [
        {
          "id": 10,
          "name": "All Orders",
          "link": "/orders/all",
          "icon": "list"
        }
      ]
    }
  ],
  "workspace": {
    "workspace_id": "ws_abc123",
    "slug": "acme-dairy",
    "display_name": "Acme Dairy",
    "domain": null,
    "plan": "professional",
    "status": 1,
    "logo": null,
    "bg_image": null,
    "primary_color": "#1e40af",
    "secondary_color": "#f59e0b"
  },
  "platform_token": null,
  "platform_admin": null,
  "latitude": "12.9716000",
  "longitude": "77.5946000",
  "periphery": "",
  "timing": "",
  "tracking_time": "60",
  "mark_attendance_time": "6:00 AM",
  "battery_percentage": "1",
  "contact_number": "9876500020"
}

POSThttps://api.spirestock.com/api/v1/auth/otp/request

Email a one-time code (valid 5 minutes) for passwordless login. The response is the same whether or not the address has an account.

Request body

emailstringrequired
Account email address
Example request
curl -X POST https://api.spirestock.com/api/v1/auth/otp/request \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'
Example response
{
  "response_code": 200,
  "message": "If an account exists, an OTP has been sent."
}

POSThttps://api.spirestock.com/api/v1/auth/otp/verify

Verify the emailed code and receive a JWT. Every failure returns the same message, and a successful sign-in revokes the user's previous session.

Request body

emailstringrequired
Email used in the OTP request
otpstringrequired
The code from the email
Example request
curl -X POST https://api.spirestock.com/api/v1/auth/otp/verify \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "otp": "482910"
  }'
Example response
{
  "response_code": 200,
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": 42,
    "salutation": null,
    "first_name": "Sample",
    "middle_name": null,
    "last_name": "User",
    "store_name": null,
    "store_image": null,
    "official_email": "[email protected]",
    "primary_contact_number": "+919876543210",
    "emp_sap_id": null,
    "organization_id": 5,
    "organization_name": "Demo Dairy",
    "department_id": null,
    "department_name": null,
    "role_id": 391,
    "role_name": "Distributor",
    "reporting_to_id": null,
    "reporting_to_name": null,
    "reporting_to_emp_id": null,
    "profile_image": null,
    "device_id": null,
    "last_login": "2026-10-22T10:59:02.269Z",
    "last_auth_method": "otp",
    "auth_methods_used": [
      "password",
      "otp"
    ],
    "onboarding_state": null,
    "last_ip": "203.0.113.10",
    "status": 1,
    "user_type": 2,
    "is_distributor": 0,
    "is_super_stockist": 0,
    "is_retailer": 0,
    "is_tagged": 0,
    "tagged_by": null,
    "tagged_date": null,
    "periphery": null,
    "timing": null,
    "latitude": null,
    "longitude": null,
    "self_owned": 0,
    "other_brand_id": null,
    "other_brand_name": null,
    "retailer_type_id": null,
    "retailer_class_type_id": null,
    "purchase_milk_from_org": 0,
    "visit_date_time": null,
    "created_by": 41500,
    "oauth_provider": null,
    "portal_onboarding_completed_at": null,
    "app_version": null,
    "createdAt": "2026-10-22T10:59:01.314Z",
    "updatedAt": "2026-10-22T10:59:02.269Z",
    "sp_role": {
      "id": 391,
      "role_name": "IT Manager"
    },
    "basicDetails": {
      "id": 51865,
      "organization_id": 6,
      "user_id": 51905,
      "father_name": null,
      "mother_name": null,
      "date_of_birth": null,
      "gender": null,
      "blood_group": null,
      "aadhaar_nubmer": null,
      "pan_number": null,
      "cin": null,
      "gstin": null,
      "fssai": null,
      "working_shift_id": null,
      "working_shift_name": null,
      "order_timing": null,
      "date_of_joining": null,
      "personal_email": null,
      "outlet_owned": null,
      "outstanding_amount": null,
      "security_amount": null,
      "opening_crates": null,
      "production_unit_id": null,
      "tcs_applicable": 0,
      "tcs_value": null,
      "per_crate_incentive": null,
      "leave_count": null,
      "week_of_day": null,
      "status": 1,
      "createdAt": "2026-10-22T10:59:01.745Z",
      "updatedAt": "2026-10-22T10:59:01.745Z"
    }
  },
  "modules": [],
  "workspace": {
    "workspace_id": "ws_abc123",
    "slug": "acme-dairy",
    "display_name": "Acme Dairy",
    "domain": null,
    "plan": "professional",
    "status": 1,
    "logo": null,
    "bg_image": null,
    "primary_color": "#1e40af",
    "secondary_color": "#3b82f6"
  },
  "platform_token": null,
  "platform_admin": null,
  "latitude": "12.9716000",
  "longitude": "77.5946000",
  "periphery": "",
  "timing": "",
  "tracking_time": "60",
  "mark_attendance_time": "6:00 AM",
  "battery_percentage": "1",
  "contact_number": "9876500020"
}

GEThttps://api.spirestock.com/api/v1/auth/me

Retrieve the authenticated user’s profile, role, and organization context.

Example request
curl https://api.spirestock.com/api/v1/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN"
Example response
{
  "response_code": 200,
  "user": {
    "id": 51896,
    "salutation": "Mr",
    "first_name": "Sample",
    "middle_name": "",
    "last_name": "User",
    "store_name": null,
    "store_image": null,
    "official_email": "[email protected]",
    "primary_contact_number": "9876500020",
    "emp_sap_id": "EMP-001",
    "organization_id": 6,
    "organization_name": "Demo Dairy",
    "department_id": 129,
    "department_name": "Sales and Marketing",
    "role_id": 0,
    "role_name": "CTO",
    "reporting_to_id": null,
    "reporting_to_name": "Sample Manager",
    "reporting_to_emp_id": null,
    "profile_image": "https://media.example.com/sample.png",
    "device_id": "",
    "last_login": "2026-10-22T08:43:54.573Z",
    "last_auth_method": "password",
    "auth_methods_used": [
      "password"
    ],
    "onboarding_state": {
      "tour": {
        "variant": "admin",
        "last_step": 3,
        "completed_at": null,
        "dismissed_at": null,
        "remind_after": "2026-10-25T08:47:20.675Z"
      },
      "checklist": {
        "dismissed_at": "2026-10-22T08:47:20.682Z"
      }
    },
    "last_ip": "203.0.113.10",
    "status": 1,
    "user_type": 0,
    "is_distributor": 0,
    "is_super_stockist": 0,
    "is_retailer": 0,
    "is_tagged": 0,
    "tagged_by": null,
    "tagged_date": null,
    "periphery": null,
    "timing": null,
    "latitude": null,
    "longitude": null,
    "self_owned": 0,
    "other_brand_id": null,
    "other_brand_name": null,
    "retailer_type_id": null,
    "retailer_class_type_id": null,
    "purchase_milk_from_org": 0,
    "visit_date_time": null,
    "created_by": 41500,
    "oauth_provider": null,
    "portal_onboarding_completed_at": null,
    "app_version": null,
    "createdAt": "2020-10-10T05:08:33.000Z",
    "updatedAt": "2026-10-22T08:47:20.682Z",
    "sp_role": {
      "id": 0,
      "role_name": "Super Admin"
    },
    "basicDetails": null
  }
}

POSThttps://api.spirestock.com/api/v1/portal/login

Customer-portal sign-in for distributors, retailers and super-stockists. The identifier can be the email, the phone number, or the SAP customer code (emp_sap_id); username accepts an email or a SAP code. Imported passwords work as for /auth/login. The token (valid 30 days) is a portal token: it is confined to the customer-portal routes, and any customer id in the query or body is replaced with the signed-in customer's own id, so a customer can only ever see their own orders, ledger and crates. Every other route answers 403. Requires a Turnstile token in production; rate limited to 15 attempts per 15 minutes.

Request body

emp_sap_idstring
SAP customer code (or send email, phone or username)
emailstring
Account email
phonestring
Registered mobile number
passwordstringrequired
Account password
Example request
curl -X POST https://api.spirestock.com/api/v1/portal/login \
  -H "Content-Type: application/json" \
  -d '{
    "emp_sap_id": "CUST-011",
    "password": "your-password"
  }'
Example response
{
  "response_code": 200,
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": 44663,
    "salutation": null,
    "first_name": "Sample",
    "middle_name": null,
    "last_name": "User",
    "store_name": "Demo Store E",
    "store_image": null,
    "official_email": "[email protected]",
    "primary_contact_number": "9876500020",
    "emp_sap_id": "CUST-011",
    "organization_id": 6,
    "organization_name": "Demo Dairy",
    "department_id": null,
    "department_name": null,
    "role_id": 396,
    "role_name": "Distributor",
    "reporting_to_id": null,
    "reporting_to_name": null,
    "reporting_to_emp_id": null,
    "profile_image": null,
    "device_id": null,
    "last_login": null,
    "last_auth_method": null,
    "auth_methods_used": [],
    "onboarding_state": null,
    "last_ip": null,
    "status": 1,
    "user_type": 2,
    "is_distributor": 1,
    "is_super_stockist": 0,
    "is_retailer": 0,
    "is_tagged": 0,
    "tagged_by": null,
    "tagged_date": null,
    "periphery": null,
    "timing": null,
    "latitude": null,
    "longitude": null,
    "self_owned": 0,
    "other_brand_id": null,
    "other_brand_name": null,
    "retailer_type_id": null,
    "retailer_class_type_id": null,
    "purchase_milk_from_org": 0,
    "visit_date_time": null,
    "created_by": 41500,
    "oauth_provider": null,
    "portal_onboarding_completed_at": null,
    "app_version": null,
    "createdAt": "2026-10-22T10:59:00.364Z",
    "updatedAt": "2026-10-22T10:59:02.653Z",
    "basicDetails": {
      "id": 51863,
      "organization_id": 6,
      "user_id": 51903,
      "father_name": null,
      "mother_name": null,
      "date_of_birth": null,
      "gender": null,
      "blood_group": null,
      "aadhaar_nubmer": null,
      "pan_number": null,
      "cin": null,
      "gstin": null,
      "fssai": null,
      "working_shift_id": null,
      "working_shift_name": null,
      "order_timing": null,
      "date_of_joining": null,
      "personal_email": null,
      "outlet_owned": null,
      "outstanding_amount": null,
      "security_amount": null,
      "opening_crates": null,
      "production_unit_id": "17",
      "tcs_applicable": 0,
      "tcs_value": null,
      "per_crate_incentive": null,
      "leave_count": null,
      "week_of_day": null,
      "status": 1,
      "createdAt": "2026-10-22T10:59:00.745Z",
      "updatedAt": "2026-10-22T10:59:00.745Z"
    }
  }
}