API docs by Redocly

Sponsoring-Portal Client API (4.14.1)

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

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

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": "http://www.google.com",
  • "deleteAfter": 30,
  • "onDuplicateStrategy": "take-ownership",
  • "customFields": [
    ]
}

Response samples

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

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

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": "http://www.google.com",
  • "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

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": {
    }
}

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

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

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

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": {
    }
}

Macman Users

Macman user CRUD API

Create a new Macman user

Authorizations:
api_header_token
Request Body schema: application/json

Macman user object

orgUnitId
required
integer <int64>

Organizational unit identifier (can't be updated)

deviceGroupId
required
integer <int64>

Macman device group identifier

username
required
string

Macman user name

password
required
string

Macman user password

comment
string

User comment

expires
string <date-time>

User expiration

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,
  • "deviceGroupId": 1,
  • "username": "user1",
  • "password": "paSsW0rd_saMp1e",
  • "comment": "Test User1",
  • "expires": "2018-06-18T12:25:28.586Z",
  • "deleteAfter": 30,
  • "customFields": [
    ],
  • "onDuplicateStrategy": "take-ownership"
}

Response samples

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

Read Macman user by identifier

Authorizations:
api_header_token
path Parameters
id
required
integer <int64>

Macman user 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/macman-users/1

Response samples

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

Update Macman user by identifier

Authorizations:
api_header_token
path Parameters
id
required
integer <int64>

Macman user identifier

Request Body schema: application/json

Macman user object

orgUnitId
required
integer <int64>

Organizational unit identifier (can't be updated)

deviceGroupId
required
integer <int64>

Macman device group identifier

username
required
string

Macman user name

password
required
string

Macman user password

comment
string

User comment

expires
string <date-time>

User expiration

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,
  • "deviceGroupId": 1,
  • "username": "user1",
  • "password": "paSsW0rd_saMp1e",
  • "comment": "Test User1",
  • "expires": "2018-06-18T12:25:28.586Z",
  • "deleteAfter": 30,
  • "customFields": [
    ],
  • "onDuplicateStrategy": "take-ownership"
}

Response samples

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

Delete Macman user by identifier

Authorizations:
api_header_token
path Parameters
id
required
integer <int64>

Macman user identifier

Responses

Request samples 

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

Response samples

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

Search Macman users by query

Authorizations:
api_header_token
query Parameters
org_unit_id
integer <int64>

Organizational unit identifier

match_type
string
Default: "all"
Enum: "all" "any"

Search logic.

  • all -> all query parameter values must match (AND logic)
  • any -> any query parameter value must match (OR logic)
match_similarity
string
Default: "exact"
Enum: "exact" "contain" "similar"

Defines the accuracy of the search.

  • exact -> query parameter value must match exactly
  • contain -> query parameter value is contained
  • similar -> query parameter value is similar

Note: similar is not supported on custom fields

username
string

Macman user name

comment
string

Macman user comment

object
Example:

Custom fields map. Custom field identifier as key and search term as value

Responses

Request samples 

curl -v -i -H "X-AUTH-TOKEN:9be7d5fe-b4a1-4e7f-894e-496916df1f94" -H "Accept: application/json" "https://sp01.example.org/api/macman-users/search?org_unit_id=1&match_type=all&match_similarity=exact&username=john&comment=test&custom_fields%5B3%5D=Zurich&custom_fields%5B2%5D=true"

Response samples

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

Macman Devices

Macman device CRUD API

Create a new Macman device

Authorizations:
api_header_token
Request Body schema: application/json

Macman device object

orgUnitId
required
integer <int64>

Organizational unit identifier (can't be updated)

deviceGroupId
required
integer <int64>

Device group identifier

deviceTypeId
required
integer <int64>

Device type identifier

macmanOrgUnitId
required
integer <int64>

Macman organizational unit identifier

name
required
string

Device name

enabled
required
boolean

Enable the device immediately after creation

description
string

Device description

deleteAfter
integer <int32>

Delete x minutes after creation

Array of objects (MacmanInterface)

Macman interfaces

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,
  • "deviceGroupId": 1,
  • "deviceTypeId": 1,
  • "macmanOrgUnitId": 1,
  • "name": "iPhone",
  • "enabled": true,
  • "description": "6 SE",
  • "deleteAfter": 30,
  • "macmanInterfaces": [
    ],
  • "customFields": [
    ],
  • "onDuplicateStrategy": "take-ownership"
}

Response samples

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

Read Macman device by identifier

Authorizations:
api_header_token
path Parameters
id
required
integer <int64>

Macman 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/macman-devices/1

Response samples

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

Update Macman device by identifier

Authorizations:
api_header_token
path Parameters
id
required
integer <int64>

Macman device identifier

Request Body schema: application/json

Macman device object

orgUnitId
required
integer <int64>

Organizational unit identifier (can't be updated)

deviceGroupId
required
integer <int64>

Device group identifier

deviceTypeId
required
integer <int64>

Device type identifier

macmanOrgUnitId
required
integer <int64>

Macman organizational unit identifier

name
required
string

Device name

enabled
required
boolean

Enable the device immediately after creation

description
string

Device description

deleteAfter
integer <int32>

Delete x minutes after creation

Array of objects (MacmanInterface)

Macman interfaces

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,
  • "deviceGroupId": 1,
  • "deviceTypeId": 1,
  • "macmanOrgUnitId": 1,
  • "name": "iPhone",
  • "enabled": true,
  • "description": "6 SE",
  • "deleteAfter": 30,
  • "macmanInterfaces": [
    ],
  • "customFields": [
    ],
  • "onDuplicateStrategy": "take-ownership"
}

Response samples

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

Delete Macman device by identifier

Authorizations:
api_header_token
path Parameters
id
required
integer <int64>

Macman device identifier

Responses

Request samples 

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

Response samples

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