Onemap8

Users

Users are critical for maintaining secure interactions between users and the system. Below are the different endpoints available to handle users programmatically.

The Users Model

A user is an entity that can be used to authenticate and interact with the system. You can create, fetch, and delete users using the following endpoints.

Can only be used by admin or manager users

Scheme

  • Name
    id
    Type
    integer
    Description
    The unique identifier for the user.
  • Name
    name
    Type
    string
    Description
    The full name of the user.
  • Name
    email
    Type
    string
    Description
    The email address of the user.
  • Name
    phone
    Type
    string
    Description
    The phone number of the user.
  • Name
    readonly
    Type
    boolean
    Description
    Whether the user is read-only.
  • Name
    administrator
    Type
    boolean
    Description
    Whether the user is an administrator.
  • Name
    map
    Type
    string
    Description
    The default map of the user.
  • Name
    latitude
    Type
    number
    Description
    The default position's latitude presentation to the user
  • Name
    longitude
    Type
    number
    Description
    The default position's longitude presentation to the user
  • Name
    zoom
    Type
    integer
    Description
    The default zoom level presentation of the user.
  • Name
    password
    Type
    string
    Description
    The password of the user.
  • Name
    coordinateFormat
    Type
    string
    Description
    The format of the coordinate presentation of the user.
  • Name
    disabled
    Type
    boolean
    Description
    Whether the user is disabled.
  • Name
    expirationTime
    Type
    string
    Description
    in IS0 8601 format. eg. `1963-11-22T18:30:00Z`
  • Name
    deviceLimit
    Type
    integer
    Description
    The maximum number of devices the user can connect.
  • Name
    userLimit
    Type
    integer
    Description
    The maximum number of users the user can connect.
  • Name
    deviceReadonly
    Type
    boolean
    Description
    Whether the user is read-only on devices.
  • Name
    limitCommands
    Type
    boolean
    Description
    Whether the user is limited to commands.
  • Name
    fixedEmail
    Type
    boolean
    Description
    Whether the user's email is fixed.
  • Name
    poiLayer
    Type
    string
    Description
    The layer of the user's POI.
  • Name
    attributes
    Type
    object
    Description
    The attributes of the user.
GET/users

Fetch a list of users

This endpoint allows you to retrieve a list of users.

Authorizations

BasicAuth or ApiKey

  • Name
    BasicAuth
    Type
    scheme
    Description
    HTTP Authorization Scheme: basic
  • Name
    ApiKey
    Type
    scheme
    Description
    HTTP Authorization Scheme: bearer

Query Parameters

  • Name
    userId
    Type
    string
    Description
    Can only be used by admin or manager users
  • Name
    limit
    Type
    integer
    Description
    Limit the number of returned results
  • Name
    offset
    Type
    integer
    Description
    Offset for pagination
  • Name
    keyword
    Type
    string
    Description
    Search keyword filter (searches name, email)

Response schema

  • Name
    application/json
    Type
    schema
    Description

Responses

  • Name
    200
    Type
    success
    Description
    User
  • Name
    400
    Type
    error
    Description
    No Permission

Request

GET
/session
curl --location 'https://gw.onemap8.com/api/users?userId=%3Cstring%3E' \
--header 'Accept: application/json' \
--header 'Authorization: Basic {your_access_token}'

Response

{
"id": 0,
"name": "string",
"email": "string",
"phone": "string",
"readonly": true,
"administrator": true,
"map": "string",
"latitude": 0,
"longitude": 0,
"zoom": 0,
"password": "string",
"coordinateFormat": "string",
"disabled": true,
"expirationTime": "2019-08-24T14:15:22Z",
"deviceLimit": 0,
"userLimit": 0,
"deviceReadonly": true,
"limitCommands": true,
"fixedEmail": true,
"poiLayer": "string",
"attributes": { }
}
POST/users

Create a user

This endpoint allows you to create a user. Successful execution is subject to limits and permissions.

Authorizations

BasicAuth or ApiKey

  • Name
    BasicAuth
    Type
    scheme
    Description
    HTTP Authorization Scheme: basic
  • Name
    ApiKey
    Type
    scheme
    Description
    HTTP Authorization Scheme: bearer

Request body schema

  • Name
    application/json
    Type
    schema
    Description

Body schema

  • Name
    id
    Type
    integer
    Description
    The unique identifier for the user.
  • Name
    name
    Type
    string
    Description
    The full name of the user.
  • Name
    email
    Type
    string
    Description
    The email address of the user.
  • Name
    phone
    Type
    string
    Description
    The phone number of the user.
  • Name
    readonly
    Type
    boolean
    Description
    Whether the user is read-only.
  • Name
    administrator
    Type
    boolean
    Description
    Whether the user is an administrator.
  • Name
    map
    Type
    string
    Description
    The default map of the user.
  • Name
    latitude
    Type
    number
    Description
    The default position's latitude presentation to the user
  • Name
    longitude
    Type
    number
    Description
    The default position's longitude presentation to the user
  • Name
    zoom
    Type
    integer
    Description
    The default zoom level presentation of the user.
  • Name
    password
    Type
    string
    Description
    The password of the user.
  • Name
    coordinateFormat
    Type
    string
    Description
    The format of the coordinate presentation of the user.
  • Name
    disabled
    Type
    boolean
    Description
    Whether the user is disabled.
  • Name
    expirationTime
    Type
    string
    Description
    in IS0 8601 format. eg. `1963-11-22T18:30:00Z`
  • Name
    deviceLimit
    Type
    integer
    Description
    The maximum number of devices the user can connect.
  • Name
    userLimit
    Type
    integer
    Description
    The maximum number of users the user can connect.
  • Name
    deviceReadonly
    Type
    boolean
    Description
    Whether the user is read-only on devices.
  • Name
    limitCommands
    Type
    boolean
    Description
    Whether the user is limited to commands.
  • Name
    fixedEmail
    Type
    boolean
    Description
    Whether the user's email is fixed.
  • Name
    poiLayer
    Type
    string
    Description
    The layer of the user's POI.
  • Name
    attributes
    Type
    object
    Description
    The attributes of the user.

Response schema

  • Name
    application/json
    Type
    schema
    Description

Responses

  • Name
    200
    Type
    success
    Description
    User
  • Name
    400
    Type
    error
    Description
    Bad Request
  • Name
    401
    Type
    error
    Description
    Not authorized

Request

POST
/users
curl --location 'https://gw.onemap8.com/api/users' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic {your_access_token}' \
--data '{
"id": "<integer>",
"name": "<string>",
"email": "<string>",
"phone": "<string>",
"readonly": "<boolean>",
"administrator": "<boolean>",
"map": "<string>",
"latitude": "<number>",
"longitude": "<number>",
"zoom": "<integer>",
"password": "<string>",
"coordinateFormat": "<string>",
"disabled": "<boolean>",
"expirationTime": "<dateTime>",
"deviceLimit": "<integer>",
"userLimit": "<integer>",
"deviceReadonly": "<boolean>",
"limitCommands": "<boolean>",
"fixedEmail": "<boolean>",
"poiLayer": "<string>",
"attributes": {}
}'

Response

{
"id": 0,
"name": "string",
"email": "string",
"phone": "string",
"readonly": true,
"administrator": true,
"map": "string",
"latitude": 0,
"longitude": 0,
"zoom": 0,
"password": "string",
"coordinateFormat": "string",
"disabled": true,
"expirationTime": "2019-08-24T14:15:22Z",
"deviceLimit": 0,
"userLimit": 0,
"deviceReadonly": true,
"limitCommands": true,
"fixedEmail": true,
"poiLayer": "string",
"attributes": { }
}
PUT/users/{id}

Update a user

This endpoint allows you to update a user. Successful execution is subject to permissions.

Authorizations

BasicAuth or ApiKey

  • Name
    BasicAuth
    Type
    scheme
    Description
    HTTP Authorization Scheme: basic
  • Name
    ApiKey
    Type
    scheme
    Description
    HTTP Authorization Scheme: bearer

Path parameters

  • Name
    id
    Type
    integer
    Description
    required

Request body schema

  • Name
    application/json
    Type
    schema
    Description

Body schema

  • Name
    id
    Type
    integer
    Description
    The unique identifier for the user.
  • Name
    name
    Type
    string
    Description
    The full name of the user.
  • Name
    email
    Type
    string
    Description
    The email address of the user.
  • Name
    phone
    Type
    string
    Description
    The phone number of the user.
  • Name
    readonly
    Type
    boolean
    Description
    Whether the user is read-only.
  • Name
    administrator
    Type
    boolean
    Description
    Whether the user is an administrator.
  • Name
    map
    Type
    string
    Description
    The default map of the user.
  • Name
    latitude
    Type
    number
    Description
    The default position's latitude presentation to the user
  • Name
    longitude
    Type
    number
    Description
    The default position's longitude presentation to the user
  • Name
    zoom
    Type
    integer
    Description
    The default zoom level presentation of the user.
  • Name
    password
    Type
    string
    Description
    The password of the user.
  • Name
    coordinateFormat
    Type
    string
    Description
    The format of the coordinate presentation of the user.
  • Name
    disabled
    Type
    boolean
    Description
    Whether the user is disabled.
  • Name
    expirationTime
    Type
    string
    Description
    in IS0 8601 format. eg. `1963-11-22T18:30:00Z`
  • Name
    deviceLimit
    Type
    integer
    Description
    The maximum number of devices the user can connect.
  • Name
    userLimit
    Type
    integer
    Description
    The maximum number of users the user can connect.
  • Name
    deviceReadonly
    Type
    boolean
    Description
    Whether the user is read-only on devices.
  • Name
    limitCommands
    Type
    boolean
    Description
    Whether the user is limited to commands.
  • Name
    fixedEmail
    Type
    boolean
    Description
    Whether the user's email is fixed.
  • Name
    poiLayer
    Type
    string
    Description
    The layer of the user's POI.
  • Name
    attributes
    Type
    object
    Description
    The attributes of the user.

Response schema

  • Name
    application/json
    Type
    schema
    Description

Responses

  • Name
    200
    Type
    success
    Description
    User
  • Name
    400
    Type
    error
    Description
    Bad Request
  • Name
    401
    Type
    error
    Description
    Not authorized

Request

PUT
/users/{id}
curl --location --request PUT 'https://gw.onemap8.com/api/users/<integer>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic {your_access_token}' \
--data '{
"id": "<integer>",
"name": "<string>",
"email": "<string>",
"phone": "<string>",
"readonly": "<boolean>",
"administrator": "<boolean>",
"map": "<string>",
"latitude": "<number>",
"longitude": "<number>",
"zoom": "<integer>",
"password": "<string>",
"coordinateFormat": "<string>",
"disabled": "<boolean>",
"expirationTime": "<dateTime>",
"deviceLimit": "<integer>",
"userLimit": "<integer>",
"deviceReadonly": "<boolean>",
"limitCommands": "<boolean>",
"fixedEmail": "<boolean>",
"poiLayer": "<string>",
"attributes": {}
}'

Response

{
"id": 0,
"name": "string",
"email": "string",
"phone": "string",
"readonly": true,
"administrator": true,
"map": "string",
"latitude": 0,
"longitude": 0,
"zoom": 0,
"password": "string",
"coordinateFormat": "string",
"disabled": true,
"expirationTime": "2019-08-24T14:15:22Z",
"deviceLimit": 0,
"userLimit": 0,
"deviceReadonly": true,
"limitCommands": true,
"fixedEmail": true,
"poiLayer": "string",
"attributes": { }
}
DELETE/users/{id}

Delete a user

Authorizations

BasicAuth or ApiKey

  • Name
    BasicAuth
    Type
    scheme
    Description
    HTTP Authorization Scheme: basic
  • Name
    ApiKey
    Type
    scheme
    Description
    HTTP Authorization Scheme: bearer

Path parameters

  • Name
    id
    Type
    integer
    Description
    required

Responses

  • Name
    204
    Type
    success
    Description
    No content

Request

DELETE
/users/{id}
curl --location --request DELETE 'https://gw.onemap8.com/api/users/<integer>' \
--header 'Authorization: Basic {your_access_token}'

Response

No content
POST/users/totp

Generate TOTP secret

Generate a TOTP (Time-based One-Time Password) secret for two-factor authentication. No authentication required.

Responses

  • Name
    200
    Type
    success
    Description
  • Name
    text/plain
    Type
    response schema
    Description

    • TOTP secret string

Request

POST
/users/totp
curl --location --request POST 'https://gw.onemap8.com/api/users/totp'

Response

JBSWY3DPEHPK3PXP
GET/users/{id}

Fetch a User

Authorizations

BasicAuth or ApiKey

  • Name
    BasicAuth
    Type
    scheme
    Description
    HTTP Authorization Scheme: basic
  • Name
    ApiKey
    Type
    scheme
    Description
    HTTP Authorization Scheme: bearer

Path parameters

  • Name
    id
    Type
    integer required
    Description

Response schema

  • Name
    application/json
    Type
    schema
    Description

Responses

  • Name
    200
    Type
    success
    Description
    User
  • Name
    401
    Type
    error
    Description
    Unauthorized
  • Name
    404
    Type
    error
    Description
    Not found

Request

GET
/users/{id}
curl --location 'https://gw.onemap8.com/api/users/<integer>' \
--header 'Accept: application/json' \
--header 'Authorization: Basic {your_access_token}'

Response

{
"id": 0,
"name": "<string>",
"email": "<string>",
"phone": "<string>",
"readonly": true,
"administrator": true,
"map": "<string>",
"latitude": 0,
"longitude": 0,
"zoom": 0,
"password": "<string>",
"coordinateFormat": "<string>",
"disabled": true,
"expirationTime": "<date-time>",
"deviceLimit": 0,
"userLimit": 0,
"deviceReadonly": true,
"limitCommands": true,
"fixedEmail": true,
"poiLayer": "<string>",
"attributes": {}
}