---
title: "Authentication API — SpireStock REST API"
description: "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."
source: https://developers.spirestock.com/api-reference/auth
---

# 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.

Base URL: `https://api.spirestock.com/api/v1`. Every request needs an API key (`X-API-Key`) or a session token (`Authorization: Bearer`); see https://developers.spirestock.com/api-reference/auth.

## Endpoints

- [POST /auth/login](https://developers.spirestock.com/api-reference/auth#post-auth-login)
- [POST /auth/otp/request](https://developers.spirestock.com/api-reference/auth#post-auth-otp-request)
- [POST /auth/otp/verify](https://developers.spirestock.com/api-reference/auth#post-auth-otp-verify)
- [GET /auth/me](https://developers.spirestock.com/api-reference/auth#get-auth-me)
- [POST /portal/login](https://developers.spirestock.com/api-reference/auth#post-portal-login)

## POST /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**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | yes | User email address |
| `password` | string | yes | Account password |

**Example request**

```bash
curl -X POST https://api.spirestock.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password"
  }'
```

**Example response**

```json
{
  "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": "user@example.com",
    "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"
}
```

## POST /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**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | yes | Account email address |

**Example request**

```bash
curl -X POST https://api.spirestock.com/api/v1/auth/otp/request \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'
```

**Example response**

```json
{
  "response_code": 200,
  "message": "If an account exists, an OTP has been sent."
}
```

## POST /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**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | yes | Email used in the OTP request |
| `otp` | string | yes | The code from the email |

**Example request**

```bash
curl -X POST https://api.spirestock.com/api/v1/auth/otp/verify \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "otp": "482910"
  }'
```

**Example response**

```json
{
  "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": "user@example.com",
    "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"
}
```

## GET /auth/me

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

**Example request**

```bash
curl https://api.spirestock.com/api/v1/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Example response**

```json
{
  "response_code": 200,
  "user": {
    "id": 51896,
    "salutation": "Mr",
    "first_name": "Sample",
    "middle_name": "",
    "last_name": "User",
    "store_name": null,
    "store_image": null,
    "official_email": "user@example.com",
    "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
  }
}
```

## POST /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**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `emp_sap_id` | string | no | SAP customer code (or send email, phone or username) |
| `email` | string | no | Account email |
| `phone` | string | no | Registered mobile number |
| `password` | string | yes | Account password |

**Example request**

```bash
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**

```json
{
  "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": "user@example.com",
    "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"
    }
  }
}
```
