LivePin Logo

Account and Sessions API

These endpoints operate on the account behind the credentials you are using. When you authenticate with an API key, the resulting session is bound to the API key owner, so GET /api/user/profile returns that owner's profile.

All endpoints require the standard credentials:

x-api-key: <YOUR_API_KEY>
Authorization: Bearer <JWT_TOKEN>

User profile

  • Name
    GET /api/user/profile
    Description
    Read the current profile.
  • Name
    PUT /api/user/profile
    Description
    Update username or email.
  • Name
    GET /api/user/generate-websocket-token
    Description

    Mint a short-lived token for the realtime websocket.

Profile fields

  • Name
    id
    Type
    integer
    Description
    User ID.
  • Name
    username
    Type
    string
    Description
    Display name. Minimum 3 characters.
  • Name
    email
    Type
    string
    Description
    Email address.
  • Name
    phone_number
    Type
    string
    Description
    Phone number in E.164 format.
  • Name
    account_type
    Type
    enum
    Description

    APP_USER, DASHBOARD_USER, DEALER, LOADING_POINT, or UNLOADING_POINT.

  • Name
    confirmed
    Type
    boolean
    Description
    Account confirmation flag.
  • Name
    blocked
    Type
    boolean
    Description
    Blocked flag.
  • Name
    email_verified
    Type
    boolean
    Description
    Email verification flag.
  • Name
    saved_addresses
    Type
    array
    Description
    Saved address components.

Read profile

GET
/api/user/profile
curl "$LIVEPIN_API_BASE_URL/api/user/profile" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

Changing the email sets email_verified to false and sends a new verification code.

Update profile

PUT
/api/user/profile
curl -X PUT "$LIVEPIN_API_BASE_URL/api/user/profile" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username":"fleet-ops","email":"ops@example.com"}'

Returns a token scoped to the location channels you are allowed to subscribe to. Pass imei to scope it to a single device.

Websocket token

GET
/api/user/generate-websocket-token
curl -G "$LIVEPIN_API_BASE_URL/api/user/generate-websocket-token" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d imei=352592573176740

Saved addresses

Saved addresses are stored as an ordered array on the user. They are used as the default billing and shipping addresses for orders placed through the Storefront API.

  • Name
    POST /api/user/save-address
    Description
    Append an address.
  • Name
    DELETE /api/user/address/:index
    Description

    Remove the address at the given array index.

Address fields

  • Name
    first_name
    Type
    string
    Description
    Required.
  • Name
    last_name
    Type
    string
    Description
    Required.
  • Name
    address_line_1
    Type
    string
    Description
    Required.
  • Name
    address_line_2
    Type
    string
    Description
    Optional.
  • Name
    city
    Type
    string
    Description
    Required.
  • Name
    pin_code
    Type
    string
    Description
    Required.
  • Name
    state
    Type
    string
    Description
    Required.
  • Name
    country
    Type
    string
    Description
    Required.
  • Name
    gstin
    Type
    string
    Description
    Optional tax identifier.

Save address

POST
/api/user/save-address
curl -X POST "$LIVEPIN_API_BASE_URL/api/user/save-address" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Doe",
    "address_line_1": "1 Main Street",
    "address_line_2": "Unit 2",
    "city": "Mumbai",
    "pin_code": "400001",
    "state": "Maharashtra",
    "country": "India",
    "gstin": "27XXXXX0000X1Z5"
  }'

Delete address

DELETE
/api/user/address/:index
curl -X DELETE "$LIVEPIN_API_BASE_URL/api/user/address/0" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

Email verification

  • Name
    POST /api/user/resend-verification-email
    Description

    Send a verification code to the current email address.

  • Name
    POST /api/user/verify-email
    Description

    Confirm the email with the code. Body: otp.

Despite the name, this endpoint sends a numeric code, not a verification link. The code is valid for 30 minutes.

Resend verification

POST
/api/user/resend-verification-email
curl -X POST "$LIVEPIN_API_BASE_URL/api/user/resend-verification-email" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

Verify email

POST
/api/user/verify-email
curl -X POST "$LIVEPIN_API_BASE_URL/api/user/verify-email" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"otp":"123456"}'

Password management

  • Name
    POST /api/user/change-password
    Description

    Change the password. Body: current_password, new_password.

  • Name
    POST /api/user/forgot-password
    Description

    Start a reset. Body: phone_number or email.

  • Name
    POST /api/user/reset-password
    Description

    Complete a reset. Body: reset_token, otp, new_password.

Change password

POST
/api/user/change-password
curl -X POST "$LIVEPIN_API_BASE_URL/api/user/change-password" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"current_password":"<CURRENT>","new_password":"<NEW>"}'

The response always contains a reset_token; the otp is delivered by email and SMS. Both expire after one hour.

Forgot password

POST
/api/user/forgot-password
curl -X POST "$LIVEPIN_API_BASE_URL/api/user/forgot-password" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com"}'

Reset password

POST
/api/user/reset-password
curl -X POST "$LIVEPIN_API_BASE_URL/api/user/reset-password" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reset_token": "0f8c2a1d9b7e4f6a3c5d8e2b1a4f7c9d",
    "otp": "123456",
    "new_password": "<NEW>"
  }'

One-time passcode login

End-user applications authenticate with an OTP sent by SMS rather than a password. The flow is two calls: request a code, then exchange it for a JWT and refresh token.

  • Name
    POST /api/user/send-otp
    Description
    Send a login code by SMS.
  • Name
    POST /api/user/verify-otp
    Description
    Exchange the code for tokens.
  • Name
    POST /api/user/login-with-api-key
    Description

    Exchange an API key and secret for a JWT.

  • Name
    POST /api/user/refresh-access-token
    Description

    Rotate an expired access token. Body: refreshToken.

  • Name
    POST /api/user/logout
    Description

    Invalidate the current session and clear its push token.

send-otp body

  • Name
    phone_number
    Type
    string
    Description

    Required. E.164 format, 10–15 characters, must start with +91 or +1.

verify-otp body

  • Name
    phone_number
    Type
    string
    Description
    Required.
  • Name
    otp
    Type
    string
    Description
    Required. Six digits, valid for 10 minutes.
  • Name
    is_oauth
    Type
    boolean
    Description

    When true, returns an OAuth code instead of tokens. Defaults to false.

Send OTP

POST
/api/user/send-otp
curl -X POST "$LIVEPIN_API_BASE_URL/api/user/send-otp" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number":"+919999999999"}'

Verify OTP

POST
/api/user/verify-otp
curl -X POST "$LIVEPIN_API_BASE_URL/api/user/verify-otp" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number":"+919999999999","otp":"231456"}'

Refresh access token

POST
/api/user/refresh-access-token
curl -X POST "$LIVEPIN_API_BASE_URL/api/user/refresh-access-token" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"refreshToken":"3f9a1c..."}'

Logout

POST
/api/user/logout
curl -X POST "$LIVEPIN_API_BASE_URL/api/user/logout" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

OAuth token generation

For native integrations that complete the OTP flow with is_oauth: true. The verification step returns a short-lived code, which is exchanged here.

  • Name
    POST /api/oauth/generate-token
    Description

    Exchange an authorization code or refresh token for an access token.

Body

  • Name
    grant_type
    Type
    string
    Description

    Required. authorization_code or refresh_token.

  • Name
    code
    Type
    string
    Description

    Required when grant_type is authorization_code.

  • Name
    refresh_token
    Type
    string
    Description

    Required when grant_type is refresh_token.

Authorization code

POST
/api/oauth/generate-token
curl -X POST "$LIVEPIN_API_BASE_URL/api/oauth/generate-token" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"authorization_code","code":"<OAUTH_CODE>"}'

Refresh token

POST
/api/oauth/generate-token
curl -X POST "$LIVEPIN_API_BASE_URL/api/oauth/generate-token" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"refresh_token","refresh_token":"7c1e5a..."}'

Sessions

Each sign-in creates a session record. Devices and integrations can be revoked individually or all at once — useful when a device is lost or a token leaks.

  • Name
    GET /api/user-sessions
    Description

    List your active sessions. Each entry includes isCurrent.

  • Name
    GET /api/user-sessions/:id
    Description
    Get a session by ID.
  • Name
    DELETE /api/user-sessions/:id
    Description

    Invalidate one session. Cannot be used on the current session.

  • Name
    GET /api/user-sessions/sign-out-all
    Description

    Invalidate every session except the current one.

Session fields

  • Name
    id
    Type
    integer
    Description
    Session ID.
  • Name
    userAgent
    Type
    string
    Description
    Client user agent string.
  • Name
    ipAddress
    Type
    string
    Description
    Client IP address.
  • Name
    ipInfo
    Type
    object
    Description
    Geo-derived IP metadata.
  • Name
    lastActiveAt
    Type
    datetime
    Description
    Last request seen on the session.
  • Name
    createdAt
    Type
    datetime
    Description
    Session creation time.
  • Name
    isCurrent
    Type
    boolean
    Description
    Whether this is the calling session.

List sessions

GET
/api/user-sessions
curl "$LIVEPIN_API_BASE_URL/api/user-sessions" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

Sign out all

GET
/api/user-sessions/sign-out-all
curl "$LIVEPIN_API_BASE_URL/api/user-sessions/sign-out-all" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

User preferences

Per-user display preferences for the Livepin dashboards.

  • Name
    GET /api/user-preferences/:id
    Description

    Read the current user's preferences. Any :id value works — the value is ignored and the calling user is used.

  • Name
    PUT /api/user-preferences/:id
    Description

    Update the current user's preferences. Creates the record on first write.

Preference fields

  • Name
    listViewShowImage
    Type
    boolean
    Description
    Defaults to true.
  • Name
    appDefaultOpeningScreen
    Type
    enum
    Description

    MAP_VIEW or LIST_VIEW. Defaults to MAP_VIEW.

  • Name
    language
    Type
    enum
    Description

    ENGLISH, HINDI, TELEGU, TAMIL, or KANNADA. Defaults to ENGLISH.

  • Name
    dashboardVariant
    Type
    enum
    Description

    LIST_MAP or ZONE_MAP_LIST. Defaults to LIST_MAP.

  • Name
    showGeofenceInMap
    Type
    boolean
    Description
    Defaults to false.

Read preferences

GET
/api/user-preferences/me
curl "$LIVEPIN_API_BASE_URL/api/user-preferences/me" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

Update preferences

PUT
/api/user-preferences/me
curl -X PUT "$LIVEPIN_API_BASE_URL/api/user-preferences/me" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"language":"HINDI","dashboardVariant":"ZONE_MAP_LIST"}'
Continue to Plans and Billing

Was this page helpful?