API docs by Redocly

Sponsoring-Portal Client API (5.5.0)

Download OpenAPI specification:Download

Support: support@onway.ch URL: https://www.onway.ch

Introduction

Response schema

Each response of the API is structured according to the same schema. The status property displays the returned HTTP status, while the links property provides useful URI templates (RFC 6570) for navigation. The answer itself is provided via the content property. If an error occurs, the problem property is set and provides useful information about the error.

Problem schema

A problem has four different properties. The type property specifies the type of the problem. In addition, the title property provides a human-readable title and the optional message property contains the error message itself. If the problem is of the type constraint-violations, the optional violations property provides more details about the problem. Such a violation object supplies the two fields field and message.

Response codes

The API uses only the following status codes:

  • The 200 (OK) status code indicates that the request has succeeded. The payload sent in a 200 response depends on the request method.

  • The 400 (Bad Request) status code indicates that the server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).

  • The 401 (Unauthorized) status code indicates that the request has not been applied because it lacks valid authentication credentials for the target resource.

  • The 403 (Forbidden) status code indicates that the server understood the request but refuses to authorize it.

  • 404 The 404 (Not Found) status code indicates that the origin server did not find a current representation for the target resource or is not willing to disclose that one exists. A 404 status code does not indicate whether this lack of representation is temporary or permanent.

  • The 500 (Internal Server Error) status code indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.

Asynchronous API calls

Most API calls on the Sponsoring Portal are processed asynchronously. This means that the initial status code 200 OK only indicates that a new task has been created and will be processed as soon as possible. To receive the actual result for the specified request, the Task API must be used.

Authentication

To use the client API, a security token must always be sent in the header. This token can be obtained via the authentication API.

api_header_token

Authentication token UUID

Security Scheme Type: API Key
Header parameter name: X-AUTH-TOKEN

Login and Logout

Authentication API to login and logout

Login to SP

Request Body schema: application/json
required

SP login object

username
required
string

SP user

password
required
string

Cleartext password

userDirectoryId
required
integer <int64>

User directory identifier

Responses

Request samples

Content type
application/json
{
  • "username": "user1",
  • "password": "top-secret",
  • "userDirectoryId": 1
}

Response samples

Content type
application/json
{
  • "reason": "OK",
  • "status": 200,
  • "content": {
    }
}

Logout from SP

Authorizations:
api_header_token

Responses

Request samples 

curl -v -H "X-AUTH-TOKEN:112f14f5-f260-4afd-a26b-0ca8ed1885d6" -H "Accept:application/json" -X POST https://sp01.example.org/api/logout

Response samples

Content type
application/json
{
  • "reason": "OK",
  • "status": 200
}

Tasks

API operations that modify data run asynchronously. For each of these operations, a task is created that runs in the background. The status of these tasks can be retrieved by following the link property in the API response.

Get task status by task identifier

Authorizations:
api_header_token
path Parameters
id
required
string <uuid>

API task identifier

Responses

Request samples 

curl -v -i -H "X-AUTH-TOKEN:9be7d5fe-b4a1-4e7f-894e-496916df1f94" -H "Accept: application/json" https://sp01.example.org/api/task/65efaf53-9da8-4e03-bb18-ec3ee8a878ce

Response samples

Content type
application/json
{
  • "reason": "OK",
  • "status": 200,
  • "content": {
    },
  • "links": {
    }
}

Delete task by task identifier

Authorizations:
api_header_token
path Parameters
id
required
string <uuid>

API task identifier

Responses

Request samples 

curl -v -i -H "X-AUTH-TOKEN:9be7d5fe-b4a1-4e7f-894e-496916df1f94" -X DELETE https://sp01.example.org/api/task/65efaf53-9da8-4e03-bb18-ec3ee8a878ce

Response samples

Content type
application/json
{
  • "reason": "OK",
  • "status": 200
}

Version

SP version information

Get current version information

Authorizations:
api_header_token

Responses

Request samples 

curl -v -i -H "X-AUTH-TOKEN:b5b3aeca-1e9d-414a-8d9d-c973424ab4eb" -H "Accept:application/json" https://sp01.example.org/api/version

Response samples

Content type
application/json
{
  • "reason": "OK",
  • "status": 200,
  • "content": {
    }
}

Guest Users

Guest user CRUD API

Create a new guest user

Authorizations:
api_header_token
Request Body schema: application/json
required

Guest user object

orgUnitId
required
integer <int64>

Organizational unit identifier (can't be updated)

customerKey
required
string

MPP customer key

groupKey
required
string

MPP group key

username
required
string

Guest user username

password
required
string

Guest user password

validForMinutes
required
integer <int64>

Guest user is valid for x minutes (0 means unlimited)

email
string

Guest user email address

comment
string

Guest user comment

validFrom
string <date-time>

Guest user start of validity

enabled
boolean

Enable the guest user immediately after creation

cellphoneNumber
string

Guest user cellphone number

sponsor
string

Guest user source of origin

redirectUrl
string

Guest user default redirect URL

deleteAfter
integer <int32>

Delete x minutes after creation

onDuplicateStrategy
string
Default: "take-ownership"
Enum: "reject" "take-ownership"
Array of objects (CustomField)

Customized input fields

Responses

Request samples

Content type
application/json
{
  • "orgUnitId": 1,
  • "customerKey": "WLP",
  • "groupKey": "TEST",
  • "username": "user.name_5",
  • "password": "paSsW0rd_saMp1e",
  • "validForMinutes": 1440,
  • "email": "username5@sp01.example.org",
  • "comment": "apprentice",
  • "validFrom": "2018-06-18T12:25:28.586Z",
  • "enabled": true,
  • "cellphoneNumber": 41791234567,
  • "sponsor": "third-party-application",
  • "redirectUrl": "https://www.onway.ch",
  • "deleteAfter": 30,
  • "onDuplicateStrategy": "take-ownership",
  • "customFields": [
    ]
}

Response samples

Content type
application/json
{
  • "reason": "OK",
  • "status": 200,
  • "content": {
    },
  • "links": {
    }
}

Search guest users

Authorizations:
api_header_token
query Parameters
search
string
Example: search=cmuster

Guest user search value

searchFilter
string
Enum: "ALL" "COMMENT" "MAIL" "PHONE" "USERNAME"
Example: searchFilter=USERNAME

Guest user search filter (default ALL)

size
integer <int64>
Example: size=50

max. number of results (default 50, max. 1000)

username
string
Example: username=cmusterhausen

Seek parameter, used to search above 1000 results; username of the first seek entity

id
number <int64>
Example: id=1234

Seek parameter, used to search above 1000 results; guest user id of the first seek entity

Responses

Request samples 

curl -v -i -H "X-AUTH-TOKEN:9be7d5fe-b4a1-4e7f-894e-496916df1f94" -H "Accept: application/json" https://sp01.example.org/api/guest-users?searchFilter=USERNAME&search=cmuster

Response samples

Content type
application/json
{
  • "reason": "OK",
  • "status": 200,
  • "content": {
    }
}

Read a guest user by identifier

Authorizations:
api_header_token
path Parameters
id
required
integer <int64>

Guest user identifier

Responses

Request samples 

curl -v -i -H "X-AUTH-TOKEN:67f74f28-eb45-45ca-9d5b-ac591ab97128" -H "Accept: application/json" https://sp01.example.org/api/guest-users/2

Response samples

Content type
application/json
{
  • "reason": "OK",
  • "status": 200,
  • "content": {
    },
  • "links": {
    }
}

Update guest user by identifier

Authorizations:
api_header_token
path Parameters
id
required
integer <int64>

Guest user identifier

Request Body schema: application/json
required

Guest user object

orgUnitId
required
integer <int64>

Organizational unit identifier (can't be updated)

customerKey
required
string

MPP customer key

groupKey
required
string

MPP group key

username
required
string

Guest user username

password
required
string

Guest user password

validForMinutes
required
integer <int64>

Guest user is valid for x minutes (0 means unlimited)

email
string

Guest user email address

comment
string

Guest user comment

validFrom
string <date-time>

Guest user start of validity

enabled
boolean

Enable the guest user immediately after creation

cellphoneNumber
string

Guest user cellphone number

sponsor
string

Guest user source of origin

redirectUrl
string

Guest user default redirect URL

deleteAfter
integer <int32>

Delete x minutes after creation

onDuplicateStrategy
string
Default: "take-ownership"
Enum: "reject" "take-ownership"
Array of objects (CustomField)

Customized input fields

Responses

Request samples

Content type
application/json
{
  • "orgUnitId": 1,
  • "customerKey": "WLP",
  • "groupKey": "TEST",
  • "username": "user.name_5",
  • "password": "paSsW0rd_saMp1e",
  • "validForMinutes": 1440,
  • "email": "username5@sp01.example.org",
  • "comment": "apprentice",
  • "validFrom": "2018-06-18T12:25:28.586Z",
  • "enabled": true,
  • "cellphoneNumber": 41791234567,
  • "sponsor": "third-party-application",
  • "redirectUrl": "https://www.onway.ch",
  • "deleteAfter": 30,
  • "onDuplicateStrategy": "take-ownership",
  • "customFields": [
    ]
}

Response samples

Content type
application/json
{
  • "reason": "OK",
  • "status": 200,
  • "content": {
    },
  • "links": {
    }
}

Delete guest user by identifier

Authorizations:
api_header_token
path Parameters
id
required
integer <int64>

Guest user identifier

Responses

Request samples 

curl -v -i -H "X-AUTH-TOKEN:67f74f28-eb45-45ca-9d5b-ac591ab97128" -X DELETE https://sp01.example.org/api/guest-users/2

Response samples

Content type
application/json
{
  • "reason": "OK",
  • "status": 200,
  • "content": {
    },
  • "links": {
    }
}

MPP Devices

MPP device CRUD API

Create a new MPP device

Authorizations:
api_header_token
Request Body schema: application/json
required

MPP device object

orgUnitId
required
integer <int64>

Organizational unit identifier (can't be updated)

customerKey
required
string

MPP customer key

groupKey
required
string

MPP group key

name
required
string

Device name

macAddresses
Array of strings
comment
string

Device comment

deleteAfter
integer <int32>

Delete x minutes after creation

Array of objects (CustomField)

Customized input fields

onDuplicateStrategy
string
Default: "take-ownership"
Enum: "reject" "take-ownership"

Responses

Request samples

Content type
application/json
{
  • "orgUnitId": 1,
  • "customerKey": "WLP",
  • "groupKey": "TEST",
  • "name": "iPhone",
  • "macAddresses": [
    ],
  • "comment": "6 SE",
  • "deleteAfter": 30,
  • "customFields": [
    ],
  • "onDuplicateStrategy": "take-ownership"
}

Response samples

Content type
application/json
{
  • "reason": "OK",
  • "status": 200,
  • "content": {
    },
  • "links": {
    }
}

Search MPP devices

Authorizations:
api_header_token
query Parameters
search
string
Example: search=112233445566

MPP device search value

searchFilter
string
Enum: "ALL" "COMMENT" "MAC" "NAME"
Example: searchFilter=MAC

MPP device search filter

size
integer <int64>
Example: size=50

Max. number of results (default 50, max. 1000)

name
string
Example: name=iPhone

Seek parameter, used to search above 1000 results; name of the first seek entity

id
number <int64>
Example: id=1234

Seek parameter, used to search above 1000 results; mpp device id of the first seek entity

Responses

Request samples 

curl -v -i -H "X-AUTH-TOKEN:9be7d5fe-b4a1-4e7f-894e-496916df1f94" -H "Accept: application/json" https://sp01.example.org/api/mpp-devices?searchFilter=MAC&search=112233445566

Response samples

Content type
application/json
{
  • "reason": "OK",
  • "status": 200,
  • "content": {
    }
}

Read MPP device by identifier

Authorizations:
api_header_token
path Parameters
id
required
integer <int64>

MPP device identifier

Responses

Request samples 

curl -v -i -H "X-AUTH-TOKEN:9be7d5fe-b4a1-4e7f-894e-496916df1f94" -H "Accept: application/json" https://sp01.example.org/api/mpp-devices/1

Response samples

Content type
application/json
{
  • "reason": "OK",
  • "status": 200,
  • "content": {
    },
  • "links": {
    }
}

Update MPP device by identifier

Authorizations:
api_header_token
path Parameters
id
required
integer <int64>

MPP device identifier

Request Body schema: application/json
required

MPP device object

orgUnitId
required
integer <int64>

Organizational unit identifier (can't be updated)

customerKey
required
string

MPP customer key

groupKey
required
string

MPP group key

name
required
string

Device name

macAddresses
Array of strings
comment
string

Device comment

deleteAfter
integer <int32>

Delete x minutes after creation

Array of objects (CustomField)

Customized input fields

onDuplicateStrategy
string
Default: "take-ownership"
Enum: "reject" "take-ownership"

Responses

Request samples

Content type
application/json
{
  • "orgUnitId": 1,
  • "customerKey": "WLP",
  • "groupKey": "TEST",
  • "name": "iPhone",
  • "macAddresses": [
    ],
  • "comment": "6 SE",
  • "deleteAfter": 30,
  • "customFields": [
    ],
  • "onDuplicateStrategy": "take-ownership"
}

Response samples

Content type
application/json
{
  • "reason": "OK",
  • "status": 200,
  • "content": {
    },
  • "links": {
    }
}

Delete MPP device by identifier

Authorizations:
api_header_token
path Parameters
id
required
integer <int64>

MPP device identifier

Responses

Request samples 

curl -v -i -H "X-AUTH-TOKEN:9be7d5fe-b4a1-4e7f-894e-496916df1f94" -X DELETE https://sp01.example.org/api/mpp-devices/1

Response samples

Content type
application/json
{
  • "reason": "OK",
  • "status": 200,
  • "content": {
    },
  • "links": {
    }
}

MPP Vouchers

MPP voucher CRUD API

Create a new MPP voucher

Authorizations:
api_header_token
Request Body schema: application/json
required

MPP voucher object

orgUnitId
required
integer <int64>

Organizational unit identifier (can't be updated)

customerKey
required
string

MPP customer key

groupKey
required
string

MPP group key

code
required
string

Voucher code

maxUsageCount
required
integer <int32>

Max usage count, 0 means unlimited

enabled
required
boolean

Enable the voucher immediately after creation

validFrom
string <date-time>

MPP voucher valid from

validTo
string <date-time>

MPP voucher valid to

comment
string

Guest user voucher code

Responses

Request samples

Content type
application/json
{
  • "orgUnitId": 1,
  • "customerKey": "WLP",
  • "groupKey": "TEST",
  • "code": 1234,
  • "maxUsageCount": 10,
  • "enabled": true,
  • "validFrom": "2018-06-18T11:24:25.577Z",
  • "validTo": "2018-06-18T11:24:25.577Z",
  • "comment": "4guests"
}

Response samples

Content type
application/json
{
  • "reason": "OK",
  • "status": 200,
  • "content": {
    },
  • "links": {
    }
}

Read MPP voucher by identifier

Authorizations:
api_header_token
path Parameters
id
required
integer <int64>

MPP voucher identifier

Responses

Request samples 

curl -v -i -H "X-AUTH-TOKEN:9be7d5fe-b4a1-4e7f-894e-496916df1f94" -H "Accept: application/json" https://sp01.example.org/api/mpp-vouchers/1

Response samples

Content type
application/json
{
  • "reason": "OK",
  • "status": 200,
  • "content": {
    },
  • "links": {
    }
}

Update MPP voucher by identifier

Authorizations:
api_header_token
path Parameters
id
required
integer <int64>

MPP voucher identifier

Request Body schema: application/json
required

MPP voucher object

orgUnitId
required
integer <int64>

Organizational unit identifier (can't be updated)

customerKey
required
string

MPP customer key

groupKey
required
string

MPP group key

code
required
string

Voucher code

maxUsageCount
required
integer <int32>

Max usage count, 0 means unlimited

enabled
required
boolean

Enable the voucher immediately after creation

validFrom
string <date-time>

MPP voucher valid from

validTo
string <date-time>

MPP voucher valid to

comment
string

Guest user voucher code

Responses

Request samples

Content type
application/json
{
  • "orgUnitId": 1,
  • "customerKey": "WLP",
  • "groupKey": "TEST",
  • "code": 1234,
  • "maxUsageCount": 10,
  • "enabled": true,
  • "validFrom": "2018-06-18T11:24:25.577Z",
  • "validTo": "2018-06-18T11:24:25.577Z",
  • "comment": "4guests"
}

Response samples

Content type
application/json
{
  • "reason": "OK",
  • "status": 200,
  • "content": {
    },
  • "links": {
    }
}

Delete MPP voucher by identifier

Authorizations:
api_header_token
path Parameters
id
required
integer <int64>

MPP voucher identifier

Responses

Request samples 

curl -v -i -H "X-AUTH-TOKEN:9be7d5fe-b4a1-4e7f-894e-496916df1f94" -X DELETE https://sp01.example.org/api/mpp-vouchers/1

Response samples

Content type
application/json
{
  • "reason": "OK",
  • "status": 200,
  • "content": {
    },
  • "links": {
    }
}