Sessions

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

The Session Model

A session represents an authenticated interaction between a user and the system. You can create, fetch, and delete sessions using the following endpoints.

It also contains an attributes object to store any key-value pairs that can be used to store additional information about the session.

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/session

Retrieve session information

This endpoint allows you to retrieve a user by providing a token. Refer to the list at the top of this page to see which properties are included with session object.

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
    token
    Type
    string
    Description

Response schema

  • Name
    application/json
    Type
    schema
    Description

Responses

  • Name
    200
    Type
    success
    Description

    Session

  • Name
    400
    Type
    error
    Description

    Not found

Request

GET
/session
curl --location 'https://gw.onemap8.com/api/session?token=%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/session

Create a new session

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/x-www-form-urlencoded
    Type
    schema
    Description

Body schema

  • Name
    email
    Type
    string
    Description

    required

  • Name
    password
    Type
    string <password>
    Description

    required

Response schema

  • Name
    application/json
    Type
    schema
    Description

Responses

  • Name
    200
    Type
    success
    Description

    Session

  • Name
    401
    Type
    error
    Description

    Not authorized

Request

POST
/session
curl --location 'https://gw.onemap8.com/api/session' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--header 'Authorization: Basic {your_access_token}' \
--data-urlencode 'email=<string>' \
--data-urlencode 'password=<string>'

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/session

Close the session

Authorizations

BasicAuth or ApiKey

  • Name
    BasicAuth
    Type
    scheme
    Description

    HTTP Authorization Scheme: basic

  • Name
    ApiKey
    Type
    scheme
    Description

    HTTP Authorization Scheme: bearer

Responses

  • Name
    204
    Type
    success
    Description

    No content

Request

DELETE
/session
curl --location --request DELETE 'https://gw.onemap8.com/api/session' \
--header 'Authorization: Basic {your_access_token}'

Response

No content
GET/session/openid/auth

Retrieve OpenId Connect Session information

Authorizations

BasicAuth or ApiKey

  • Name
    BasicAuth
    Type
    scheme
    Description

    HTTP Authorization Scheme: basic

  • Name
    ApiKey
    Type
    scheme
    Description

    HTTP Authorization Scheme: bearer

Responses

  • Name
    303
    Type
    redirect
    Description

    Redirect to OpenID Connect identity provider

Request

GET
/session/openid/auth
curl --location 'https://gw.onemap8.com/api/session/openid/auth' \
--header 'Authorization: Basic {your_access_token}'

Response

  Redirect to OpenID Connect identity provider
GET/session/openid/callback

OpenId Connect Session information

Authorizations

BasicAuth or ApiKey

  • Name
    BasicAuth
    Type
    scheme
    Description

    HTTP Authorization Scheme: basic

  • Name
    ApiKey
    Type
    scheme
    Description

    HTTP Authorization Scheme: bearer

Responses

  • Name
    303
    Type
    redirect
    Description

    Successful authentication, redirect to homepage

Request

GET
/session/openid/auth
curl --location 'https://gw.onemap8.com/api/session/openid/callback' \
--header 'Authorization: Basic {your_access_token}'

Response

  Redirect to OpenID Connect identity provider