> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vultlocal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Admin Login

> Authenticate and receive JWT token

<Info>
  The login endpoint authenticates admin users and processors, returning JWT tokens for session-based access.
</Info>

## Endpoint

```http theme={null}
POST /api/v1/admin/login
```

***

## Request Body

<ParamField body="email" type="string" required>
  User email address
</ParamField>

<ParamField body="password" type="string" required>
  User password
</ParamField>

***

## User Types

<CardGroup cols={2}>
  <Card title="Admin Users" icon="shield">
    Dashboard users with roles like `system_admin`, `compliance_user`, `super_agent`
  </Card>

  <Card title="Processors" icon="store">
    Merchant accounts for POS terminal management
  </Card>
</CardGroup>

***

## Example

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl -X POST "https://demo.api.vultlocal.com/api/v1/admin/login" \
      -H "Content-Type: application/json" \
      -d '{
        "email": "admin@olive.sl",
        "password": "SecureP@ss123"
      }'
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "success": true,
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "refresh_token": "rt_abc123xyz...",
      "expires_at": 1704067200,
      "refresh_expires_at": 1704672000,
      "user": {
        "id": "123",
        "email": "admin@olive.sl",
        "first_name": "Admin",
        "last_name": "User",
        "role": "system_admin",
        "user_type": "admin",
        "status": "active",
        "pep_access_authorized": true,
        "last_login_at": "2025-01-14T15:30:00Z"
      }
    }
    ```
  </Tab>
</Tabs>

***

## Token Management

<Steps>
  <Step title="Login">
    Receive access token (15 min) and refresh token (7 days)
  </Step>

  <Step title="Use Token">
    Include in `Authorization: Bearer <token>` header
  </Step>

  <Step title="Refresh">
    When expired, use refresh endpoint to get new tokens
  </Step>

  <Step title="Logout">
    Revoke refresh token when logging out
  </Step>
</Steps>

***

## User Roles

| Role              | Access Level             |
| ----------------- | ------------------------ |
| `system_admin`    | Full system access       |
| `compliance_user` | Compliance monitoring    |
| `support_user`    | Customer support         |
| `sales_user`      | Sales operations         |
| `audit_user`      | Read-only audit access   |
| `super_agent`     | Agent network management |
| `sub_agent`       | Field agent operations   |
| `processor`       | POS merchant dashboard   |

***

## Errors

| Code | Error                 | Description                |
| ---- | --------------------- | -------------------------- |
| 400  | `INVALID_REQUEST`     | Missing email or password  |
| 401  | `INVALID_CREDENTIALS` | Wrong email or password    |
| 401  | `ACCOUNT_INACTIVE`    | User account is not active |
| 500  | `INTERNAL_ERROR`      | Server error               |

***

## Security Notes

<Warning>
  * Login attempts are logged for audit
  * Failed attempts may trigger account lockout
  * Access tokens expire after 15 minutes
  * Always use HTTPS in production
</Warning>

***

## Related

<CardGroup cols={3}>
  <Card title="Refresh Token" icon="refresh-cw" href="/api-reference/admin/refresh">
    Get new access token
  </Card>

  <Card title="Logout" icon="log-out" href="/api-reference/admin/logout">
    Revoke refresh token
  </Card>

  <Card title="Current User" icon="user" href="/api-reference/admin/me">
    Get current user info
  </Card>
</CardGroup>


## OpenAPI

````yaml olive-openapi.json POST /admin/login
openapi: 3.0.0
info:
  description: >-
    API Gateway for OLIVE NFC Card Payment System - Comprehensive payment, card
    management, agent operations, and admin authentication. All /api/v1 routes
    require authentication using either API Key or JWT token.
  title: OLIVE NFC Card Payment API
  termsOfService: http://swagger.io/terms/
  contact:
    name: API Support
    email: support@olive.sl
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
  - url: https://olive-gateway-a6ba.onrender.com/api/v1
security: []
paths:
  /admin/login:
    post:
      tags:
        - Admin
      summary: User login (Admin or Processor)
      description: Authenticates an admin user or processor and returns a JWT token
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/handler.LoginRequest'
        description: Login credentials
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.LoginResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
components:
  schemas:
    handler.LoginRequest:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
        password:
          type: string
    handler.LoginResponse:
      type: object
      properties:
        expires_at:
          type: integer
        refresh_expires_at:
          type: integer
        refresh_token:
          type: string
        success:
          type: boolean
        token:
          type: string
        user:
          $ref: '#/components/schemas/handler.UserInfo'
    handler.UserInfo:
      type: object
      properties:
        account_id:
          description: For processors
          type: string
        agent_id:
          type: string
        created_at:
          type: string
        email:
          type: string
        first_name:
          type: string
        id:
          type: string
        last_login_at:
          type: string
        last_name:
          type: string
        name:
          description: For processors
          type: string
        pep_access_authorized:
          type: boolean
        phone_number:
          type: string
        role:
          type: string
        status:
          type: string
        user_type:
          description: '"admin" or "processor"'
          type: string

````