Authentication Service API (1)

Perform authentication

Authentication Service Wiki

Sign In with Email and Password

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{"user": {"email": "operator@example.com",
"password": "secret"
}
}

Response samples

200
401

Content type

application/json

{"bearer_token": "string",
"refresh_token": "string",
"user": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"email": "user@example.com",
"name": "John Doe",
"roles": ["SysAdmin"
],
"org_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
}

Driver Sign Up

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{"user": {"email": "driver@example.com",
"password": "secret",
"name": "Cleo",
"phone_number": 12345678
}
}

Response samples

200
422

Content type

application/json

{"message": "Successfully register freelance driver account"
}

Merchant signs up by requesting security code to the email provided

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{"user": {"email": "user@example.com",
"phone_number": "string"
}
}

Response samples

200

Content type

application/json

{"message": "Successfully sent security code to the email"
}

Merchant verifies security code

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{"user": {"paranoid_verification_code": "string"
}
}

Response samples

200

Content type

application/json

{"message": "Successfully verified security code"
}

Accept the invitation

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{"user": {"name": "Budi",
"password": "secret",
"invitation_token": "Bmdvstzgm6ySjkBWN7pV"
}
}

Response samples

200
401

Content type

application/json

{"status": "Invitation Accepted!"
}

Invite user by OrgAdmin

The invited user will automatically been assigned to OrgAdmin's organisation

Authorizations:

bearerAuth

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

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

Response samples

200
401
422

Content type

application/json

{"status": "Invitation sent!"
}

Invite user by OrgTransporter

The invited user will automatically been assigned to OrgTransporter's organisation

Authorizations:

bearerAuth

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

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

Response samples

200
401
422

Content type

application/json

{"status": "Invitation sent!"
}

OrgAdmin Generate invitation URL with token

Authorizations:

bearerAuth

query Parameters

email

required

string <email>

Email of the user to be invited

Responses

Response samples

200
401
404
422

Content type

application/json

{"invitation_token": "xxxxxx",
"invitation_url": "https://development.gotsurge.co/users/invitation/accept?invitation_token=xxxxxx"
}

SysAdmin Generate invitation URL with token

Authorizations:

bearerAuth

query Parameters

email

required

string <email>

Email of the user to be invited

Responses

Response samples

200
401
404
422

Content type

application/json

{"invitation_token": "xxxxxx",
"invitation_url": "https://development.gotsurge.co/users/invitation/accept?invitation_token=xxxxxx"
}

Invite user by SysAdmin

Authorizations:

bearerAuth

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{"user": {"email": "user@example.com",
"org_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
}

Response samples

200
401
422

Content type

application/json

{"status": "Invitation sent!"
}

Invite multiple users by SysAdmin (up to 5 emails)

Authorizations:

bearerAuth

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{"user": {"emails": ["user1@example.com",
"user2@example.com"
],
"org_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"role_id": "00000000-0000-0000-0000-000000000000"
}
}

Response samples

200
207
401
422

Content type

application/json

{"invited": ["user1@example.com",
"user2@example.com"
],
"failed": [ ]
}

Request new password

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

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

Response samples

201

Content type

application/json

{"message": "You will receive an email with instructions on how to reset your password in a few minutes."
}

Reset Password

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{"user": {"password": "secret",
"reset_password_token": "tBPAwD_N4ctQ6vCiUHqv"
}
}

Response samples

200
422

Content type

application/json

{"message": "Your password has been changed successfully."
}

Update profile information.

Authorizations:

bearerAuth

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{"user": {"name": "John Doe",
"current_password": "secret",
"password": "supersecret"
}
}

Response samples

200
401

Content type

application/json

{"message": "Your account has been updated successfully."
}

Update member profile information.

Authorizations:

bearerAuth

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{"user": {"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "John Doe",
"phone_number": 68780444555
}
}

Response samples

200
401

Content type

application/json

{"message": "Your account has been updated successfully."
}

List all of Users

Only SysAdmin can access it, Users can be filtered by org_id query string

Authorizations:

bearerAuth

query Parameters

org_id	string Filter users by org id (Only available for SysAdmin)
search	string Filter users by name or email (Only available for SysAdmin)
page	integer <int64> >= 1 Default: 1
per_page	integer <int64> >= 1 Default: 20

Responses

Response samples

200
401
403

Content type

application/json

Example

Users exist

{"users": [{"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"email": "xxx@xxxx.com",
"name": "John Doe",
"created_at": "2020-12-30T04:21:29.712Z",
"updated_at": "2020-12-30T04:21:29.712Z",
"org_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"roles": ["SysAdmin"
]
}
],
"meta": {"page": 1,
"per_page": 20,
"total": 1
}
}

List Users by Role

Only SysAdmin can access it. Returns users within an organization filtered by role.

Authorizations:

bearerAuth

query Parameters

org_id required	string Organization ID to filter users
role_name required	string Enum: "OrgAdmin" "OrgDriver" "OrgTransporter" Role name to filter
page	integer <int64> >= 1 Default: 1
per_page	integer <int64> >= 1 Default: 20
sort_by	string Default: "created_at" Enum: "name" "email" "created_at" Sort field. One of `name`, `email`, or `created_at`. Defaults to `created_at`.
order	string Default: "desc" Enum: "asc" "desc" Sort direction for `sort_by`. Defaults to `desc`.

Responses

Response samples

200
401
403

Content type

application/json

{"users": [{"id": "8f0824e6-ab71-47f5-9aac-7a1679848d80",
"email": "user@example.com",
"name": "Driver One",
"created_at": "2025-07-29T03:54:52.418Z",
"updated_at": "2025-07-29T03:54:52.583Z",
"org_id": "aa292132-223b-4eed-822c-36311da43354",
"roles_name": [ ],
"confirmed_at": "2025-07-29T03:54:52.515Z",
"invitation_token": null
}
],
"meta": {"page": 1,
"per_page": 50,
"total": 6,
"total_records": 6,
"total_pages": 1,
"has_next": false,
"has_previous": false
}
}

Get User Details by ID

Only SysAdmin can access it

Authorizations:

bearerAuth

path Parameters

userID

required

string

ID of the user to be read

Responses

Response samples

200
401
403
404

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"email": "user@example.com",
"name": "John Doe",
"org_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"roles": ["SysAdmin"
],
"confirmed_at": "2019-08-24T14:15:22Z"
}

Delete User

Only SysAdmin can access it, update the user email, adding deleted prefix

Authorizations:

bearerAuth

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

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

Response samples

200
400
401
403

Content type

application/json

{"code": "success",
"message": "Your user has been successfully deleted."
}

Get User Details by Email

Only SysAdmin can access it

Authorizations:

bearerAuth

query Parameters

email

string

user email

Responses

Response samples

200
401
403
404

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"email": "user@example.com",
"name": "John Doe",
"org_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"roles": ["SysAdmin"
],
"confirmed_at": "2019-08-24T14:15:22Z"
}

List of Users

Only OrgAdmin can access it, Users are filtered by org id (same as user logged in)

Authorizations:

bearerAuth

query Parameters

page	integer <int64> >= 1 Default: 1
per_page	integer <int64> >= 1 Default: 20

Responses

Response samples

200
401
403

Content type

application/json

Example

Users exist

{"users": [{"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"email": "xxx@xxxx.com",
"name": "John Doe",
"created_at": "2020-12-30T04:21:29.712Z",
"updated_at": "2020-12-30T04:21:29.712Z",
"org_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"roles": ["OrgAdmin"
]
}
],
"meta": {"page": 1,
"per_page": 20,
"total": 1
}
}

Update User details

OrgAdmin and OrgTransporter can access it, update the currently logged in user

Authorizations:

bearerAuth

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{"user": {"name": "John Doe",
"phone_number": 12345678
}
}

Response samples

200
400
401
403

Content type

application/json

{"code": "success",
"message": "Your user has been successfully updated."
}

Delete User details

Only Driver can access it, update the currently logged in user's email

Authorizations:

bearerAuth

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{"user": {"user": {"phone_number": 12345678,
"driver_profile": {"version_rev": "xx-0000"
}
}
}
}

Response samples

200
400
401
403

Content type

application/json

{"code": "success",
"message": "Your user has been successfully deleted."
}

Delete the Transporter user

Only Transporter can access it

Authorizations:

bearerAuth

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

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

Response samples

200
400
401
403

Content type

application/json

{"code": "success",
"message": "Your user has been successfully deleted."
}

Get User Details by ID

OrgAdmin and OrgTransporter can access it

Authorizations:

bearerAuth

path Parameters

userID

required

string

ID of the user to be read

Responses

Response samples

200
401
403
404

Content type

application/json

{"user": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"email": "user@example.com",
"name": "John Doe",
"roles": ["SysAdmin"
],
"org_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
}

Set name and password

Only users who registered through merchant self registration are allowed to use this API

Authorizations:

bearerAuth

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{"user": {"name": "John",
"password": "randomPassword"
}
}

Response samples

200
401
403

Content type

application/json

{"code": "success",
"message": "Successfully set name and password"
}

Assign organization to user

Only SysAdmin is allowed and the user should not have an org_id before

Authorizations:

bearerAuth

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{"user": {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b"
}
}

Response samples

200
401
403
404

Content type

application/json

{"code": "success",
"message": "Successfully assign org to user"
}

SysAdmin confirm user

Only SysAdmin is allowed and the user must not be confirmed before

Authorizations:

bearerAuth

path Parameters

userID

required

string

ID of the user to be confirmed

Responses

Response samples

200
400
401
403
404

Content type

application/json

{"code": "success",
"message": "User successfully confirmed"
}

Endpoint to retrieve bearer_token by the refresh_token

For internal fill client_key with 'gotsurge'

Request Body schema: application/json

refresh_token	string
client_key	string

Responses

Request samples

Payload

Content type

application/json

{"refresh_token": "string",
"client_key": "string"
}

Response samples

200
401

Content type

application/json

{"bearer_token": "string"
}

Endpoint for Platform Partners to invite user to their partner organizations

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{"user": {"email": "platformpartners-child@example.com",
"org_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"role_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
}

Response samples

200
401
422

Content type

application/json

{"status": "Invitation sent!"
}

Exchange MDP Token for GotSurge Bearer Token

Receives an MDP Bearer token via the Authorization header and attempts to verify it with the MDP service. If successful, it generates and returns a GotSurge Bearer token for the corresponding user (or a default payload if the user doesn't exist in GotSurge yet).

header Parameters

Authorization

required

string

Example: Bearer mdp_token_value_here

The Bearer token provided by MDP.

Responses

Response samples

200
401
500
503

Content type

application/json

{"message": "Token exchanged successfully",
"bearer_token": "eyJhbGciOiJIUzI1NiJ9...",
"bearer_token_expired_at": 1678886400
}