Onemap8

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. No authentication required.

Query Parameters

  • Name
    token
    Type
    string
    Description

Response schema

  • Name
    application/json
    Type
    schema
    Description

Responses

  • Name
    200
    Type
    success
    Description
    Session
  • Name
    404
    Type
    error
    Description
    Not found

Request

GET
/session
curl --location 'https://gw.onemap8.com/api/session?token=%3Cstring%3E' \
--header 'Accept: application/json'

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' \
--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
POST/session/token

Generate session token

Generate a session token with an optional expiration date.

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 parameters

  • Name
    expiration
    Type
    string (date-time)
    Description
    Optional expiration date-time for the token

Responses

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

    • Token string

Request

POST
/session/token
curl --location 'https://gw.onemap8.com/api/session/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic {your_access_token}' \
--data-urlencode 'expiration=<date-time>'

Response

eyJhbGciOi...
POST/session/token/revoke

Revoke session token

Revoke a previously issued session token.

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 parameters

  • Name
    token
    Type
    string required
    Description
    The token string to revoke

Responses

  • Name
    204
    Type
    success
    Description
    No content
  • Name
    400
    Type
    error
    Description
    Bad Request

Request

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

Response

No content
GET/session/{id}

Open a Session as another User

Admin or manager only. Establishes a session impersonating the specified 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
/session/{id}
curl --location 'https://gw.onemap8.com/api/session/<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": {}
}