API reference

Authentication

15 methods. Request fields, an example response, and notes on what comes back in data.

Base https://api.groove.com.na Updated October 2026

POST /api/auth/apple

Public

Request

Parameter	In	Req.	Description
`identity_token`	body	Y	Apple identity token from Sign in with Apple (min 1).
`email`	body	N	Account email address (stored lowercase).
`full_name`	body	N	Optional display name from Apple on first authorization (min 1, max 120).

Example body

{
  "identity_token": "{{appleIdentityToken}}",
  "email": "customer@privaterelay.appleid.com",
  "full_name": "Apple Customer"
}

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

POST /api/auth/google

Public

Request

Parameter	In	Req.	Description
`id_token`	body	Y	Google ID token from the client SDK (min 1).

Example body

{
  "id_token": "{{googleIdToken}}"
}

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

POST /api/auth/login

Public

Request

Parameter	In	Req.	Description
`email`	body	Y	Account email address (stored lowercase).
`password`	body	Y	Account password (min 1).

Example body

{
  "email": "{{adminEmail}}",
  "password": "{{adminPassword}}"
}

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "rt_8f3c2a1b9e...",
    "expiresIn": 3600,
    "user": {
      "id": "66f0a1b2c3d4e5f678901234",
      "name": "Pat Fan",
      "email": "pat@example.com",
      "roles": [
        "customer"
      ]
    }
  }
}

Response data

Wrapped in the standard envelope (status, success, data, …). See the introduction for envelope fields.

Field	Description
`data.accessToken`	JWT access token. Send as Authorization: Bearer.
`data.refreshToken`	Long-lived refresh token for /api/auth/refresh.
`data.expiresIn`	Access token lifetime in seconds.
`data.user`	Object. Nested fields follow.
`data.user.id`	Resource identifier (Mongo ObjectId string).
`data.user.name`	Human-readable name.
`data.user.email`	Email address.
`data.user.roles`	Array. Element shape shown when sample includes objects.

POST /api/auth/logout

Revoke the refresh token and end the session.

Public

Request

Parameter	In	Req.	Description
`refreshToken`	body	Y	Opaque refresh token from login or the previous refresh call (min 1).

Example body

{
  "refreshToken": "{{refreshToken}}"
}

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

GET /api/auth/me

Return the signed-in user profile.

Bearer token

Request

No body or query parameters. Path values above, if any, are enough.

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {
    "id": "66f0a1b2c3d4e5f678901234",
    "name": "Pat Fan",
    "email": "pat@example.com",
    "roles": [
      "customer"
    ],
    "phone": "+264811234567"
  }
}

Response data

Wrapped in the standard envelope (status, success, data, …). See the introduction for envelope fields.

Field	Description
`data.id`	Resource identifier (Mongo ObjectId string).
`data.name`	Human-readable name.
`data.email`	Email address.
`data.roles`	Array. Element shape shown when sample includes objects.
`data.phone`	Phone number when present on the profile.

POST /api/auth/password-reset/complete

Set a new password after reset verification.

Public

Request

Parameter	In	Req.	Description
`email`	body	Y	Account email address (stored lowercase).
`resetToken`	body	Y	Short-lived token returned after a successful password-reset verify step (min 32, max 256).
`password`	body	Y	Account password (min 8, max 128).

Example body

{
  "email": "user@example.com",
  "resetToken": "\u2026",
  "password": "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022"
}

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

POST /api/auth/password-reset/request

Start a password reset for an email address.

Public

Request

Parameter	In	Req.	Description
`email`	body	Y	Account email address (stored lowercase).

Example body

{
  "email": "user@example.com"
}

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

POST /api/auth/password-reset/verify

Verify a password-reset code.

Public

Request

Parameter	In	Req.	Description
`email`	body	Y	Account email address (stored lowercase).
`code`	body	Y	One-time verification or OTP code (length 6).

Example body

{
  "email": "user@example.com",
  "code": "\u2026"
}

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

POST /api/auth/refresh

Exchange a refresh token for a new access token.

Public

Request

Parameter	In	Req.	Description
`refreshToken`	body	Y	Opaque refresh token from login or the previous refresh call (min 1).

Example body

{
  "refreshToken": "{{refreshToken}}"
}

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "rt_rotated_token...",
    "expiresIn": 3600
  }
}

Response data

Wrapped in the standard envelope (status, success, data, …). See the introduction for envelope fields.

Field	Description
`data.accessToken`	JWT access token. Send as Authorization: Bearer.
`data.refreshToken`	Long-lived refresh token for /api/auth/refresh.
`data.expiresIn`	Access token lifetime in seconds.

POST /api/auth/register/admin

Create an admin user.

Public

Request

Parameter	In	Req.	Description
`email`	body	Y	Account email address (stored lowercase).
`password`	body	Y	Account password (min 8, max 128).
`name`	body	Y	Display name (min 2, max 120).
`title`	body	N	Job title shown on the admin profile (max 80).
`bootstrapSecret`	body	N	One-time bootstrap secret for creating the first admin.
`assignedTier`	body	N	Admin tier: analyst, support, admin, or super_admin.

Example body

{
  "email": "admin2@groove.na",
  "password": "SecureAdminPass123!",
  "name": "Second Admin",
  "title": "Support"
}

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

POST /api/auth/register/customer

Create a fan (customer) account.

Public

Request

Parameter	In	Req.	Description
`email`	body	Y	Account email address (stored lowercase).
`password`	body	Y	Account password (min 8, max 128).
`firstName`	body	Y	Given name (min 1, max 80).
`lastName`	body	Y	Family name (min 1, max 80).
`phone`	body	N	Contact mobile number in international or local form (min 4, max 32).

Example body

{
  "email": "{{customerEmail}}",
  "password": "{{customerPassword}}",
  "firstName": "UAT",
  "lastName": "Customer",
  "phone": "+264811234567"
}

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

POST /api/auth/register/merchant

Create a merchant account.

Public

Request

Parameter	In	Req.	Description
`email`	body	Y	Account email address (stored lowercase).
`password`	body	Y	Account password (min 8, max 128).
`name`	body	Y	Display name (min 2, max 120).
`businessName`	body	Y	Merchant business / trading name (min 2, max 200).
`stallName`	body	N	Stall label shown on the floor and in reports (max 100).
`phone`	body	N	Contact mobile number in international or local form (min 4, max 32).

Example body

{
  "email": "{{merchantEmail}}",
  "password": "{{merchantPassword}}",
  "name": "UAT Merchant",
  "businessName": "UAT Stall",
  "stallName": "Food",
  "phone": "+264811234569"
}

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

POST /api/auth/register/organiser

Create an organiser account.

Public

Request

Parameter	In	Req.	Description
`name`	body	Y	Display name (min 2, max 120).
`orgName`	body	Y	Legal or trading name of the organiser business (min 2, max 200).
`email`	body	Y	Account email address (stored lowercase).
`phone`	body	N	Contact mobile number in international or local form (min 4, max 32).
`password`	body	Y	Account password (min 8, max 128).

Example body

{
  "name": "UAT Organiser",
  "orgName": "Groove UAT Org",
  "email": "{{organiserEmail}}",
  "phone": "+264811234568",
  "password": "{{organiserPassword}}"
}

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

POST /api/auth/resend-verification

Send a fresh email verification code.

Public

Request

Parameter	In	Req.	Description
`email`	body	Y	Account email address (stored lowercase).

Example body

{
  "email": "{{customerEmail}}"
}

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

POST /api/auth/verify-email

Confirm an email address with a verification code.

Public

Request

Parameter	In	Req.	Description
`email`	body	Y	Account email address (stored lowercase).
`code`	body	Y	One-time verification or OTP code (length 6).

Example body

{
  "email": "{{customerEmail}}",
  "code": "123456"
}

Example response

{
  "status": "success",
  "success": true,
  "statusCode": "00000",
  "message": "OK",
  "shortMessage": "SUCCESS",
  "timestamp": "2026-10-10T21:00:00.000Z",
  "requestId": "a1b2c3d4e5f6g7h8",
  "data": {}
}

Response data

Success returns the standard envelope. data holds the payload for this method — confirm the shape in your client when integrating.

Lock this page again

Authentication · 15 methods · October 2026

Resolve this before you come in.

Request

Example body

Example response

Response data

Request

Example body

Example response

Response data

Request

Example body

Example response

Response data

Request

Example body

Example response

Response data

Request

Example response

Response data

Request

Example body

Example response

Response data

Request

Example body

Example response

Response data

Request

Example body

Example response

Response data

Request

Example body

Example response

Response data

Request

Example body

Example response

Response data

Request

Example body

Example response

Response data

Request

Example body

Example response

Response data

Request

Example body

Example response

Response data

Request

Example body

Example response

Response data

Request

Example body

Example response

Response data