Extreme Networks Logo
Documentation Powered by ReDoc

ExtremeGuest REST API (6.0.0)

Download OpenAPI specification:Download

Extreme Networks Support: support@extremenetworks.com URL: https://www.extremenetworks.com
ExtremeGuest User Documentation

Introduction

The ExtremeGuest API allows developers to programmatically create, access, and manage guest users, devices, sites, customers, and access points in a simple and secure manner. It is based on RESTful principles and uses standard HTTP methods for requests and responses. API request and response bodies are formatted in JavaScript Object Notation (JSON).
You can use any language or library that can submit REST API requests and process JSON to query the ExtremeGuest API. Examples of languages and libraries that can build REST clients include:

  • For Java, the Jersey library provides the reference implementation of JAX-RS, a Java standard for RESTful web services. The implementation includes a client library that can run directly on the JVM.
  • For Python, the Requests and JSON libraries facilitate REST API applications.
  • For .Net, the core language provides facilities for submitting HTTP requests, and .Net libraries include a serializer for JSON.
  • For the Linux shell, Wget and cURL can execute REST API calls. Linux shell utilities, like awk and grep, can parse and process JSON.

You can access the REST API Development Center via the ExtremeGuest Graphical User Interface (GUI). Go to Operations > REST API in the GUI to test out API calls. You can also use tools like Postman, an easy-to-use Chrome extension for making HTTP requests. Note: To submit API calls and make configuration changes through the REST API, your RESTful API consuming program needs to have logged in using full Administrator credentials.

Authentication and Authorization

The ExtremeGuest API supports the HTTP Bearer Authentication scheme in conjuntion with the OAuth 2.0 protocol to provide secure authorized access to the API. OAuth is an authorization framework that enables web, mobile, and desktop applications to access protected resources. To begin, pass your login credentials within a POST request to the /v1/oauth2/token endpoint with the following JSON data and structure:

{
   "grantType": "password",
   "userId": "string",
   "password": "string"
}

In exchange for these credentials the ExtremeGuest authorization server issues tokens called bearer tokens that you need to include in the Authorization header when making subsequent REST API calls. Below is a sample response to the token request:

{
    "access_token":"OWtsSajgOvHo7TOQV4nrQdMWp1bW8TZG",
    "token_type":"Bearer",
    "idle_timeout":0,
    "twoFactorAuthenticationRequired":false,
    "resetPassword":false,
    "aclTemplate":{},
    "expires_in":86400
}

Note: Access tokens have a finite lifetime. The expires_in field in the response indicates the lifetime, in seconds, of the access token. For example, a value of 3600 indicates that the access token expires in one hour from the time the response was generated. The API endpoint issues a HTTP 401 Unauthorized status code when it detects an expired token.

bearerAuth

Security scheme type: HTTP
HTTP Authorization Scheme bearer

API Request Components

To construct a REST API request, combine the following components:

Component Description
The HTTP method
  • GET: Retrieve data from the server
  • DELETE: Delete a resource from the server
  • POST: Create a new resource on the server
  • PUT: Update an existing resource on the server
The base URL of the API https://{IP_Address}, where {IP_Address} is the IPv4 or IPv6 address of the server that hosts the on-premise ExtremeGuest installation.
The URI to the resource The resource to create, update, query, or delete. For example, /v1/guestdevices.
Path parameters These variables are part of the full URL path and are used to point to a specific resource within a collection. For example, /v1/guestUsers/{guestUserId}, where {guestUserId} is the path parameter and is substituted with an actual value when making the API call.
Query string parameters For most REST GET calls, you can specify one or more optional query parameters on the request URI to filter, limit the size of, and sort the data in an API response. Query string parameters appear after a question mark (?) in the endpoint. Each parameter is listed one right after the other with an ampersand (&) separating them. The order of the query string parameters does not matter.
HTTP request headers The following HTTP headers are supported:
  • Accept: Required for operations with a response body, syntax is Accept: application/json
  • Content-Type: Required for operations with a request body, syntax is Content-Type: application/json
  • Authorization: Required to get an access token or make API calls, syntax is Authorization: username:password
JSON request body Required for most POST and PUT requests.

When you POST or PUT data to the REST API server, set the Content-Type header to application/json. It can also be useful to set the following request headers:

  • accept: application/json
  • accept-encoding: gzip,deflate,br
  • accept-language: en-US,en;q=0.8,und;q=0.6

Response Codes

The ExtremeGuest REST API returns standard HTTP response codes in addition to JSON-based error messages in the response body to help you identify the source of a problem:

HTTP Code Description
200 OK The request was successful
201 Created The resource was created successfully
204 No Content Success with no response body
400 Bad Request The operation failed because the request is syntactically incorrect or violated schema
401 Unauthorized The authentication credentials are invalid or the user is not authorized to use the API
404 Not Found The server did not find the specified resource that matches the request URL
405 Method Not Allowed The API does not support the requested HTTP method

oauth2/token

OAuth2 authentication and authorization

Create an access token using Oauth2 authorization

Authorizations:
bearerAuth
Request Body schema: application/json

A valid RequestTokenElement object containing the manadatory properties for administrator authentication and authorization

grantType
required
string [ 8 .. 16 ] characters
Default: "password"

A non-empty, valid string with the default value of password

userId
required
string [ 1 .. 64 ] characters

Username for the account

scope
string <= 128 characters

Scope of the access token. This field is not currently used.

password
required
string [ 1 .. 64 ] characters

Password for the above user account.

Responses

200

Access token was created successfully

post /v1/oauth2/token

ExtremeGuest API Server URL

https://IP_Address/v1/oauth2/token

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "grantType": "password",
  • "userId": "string",
  • "scope": "string",
  • "password": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "idle_timeout": 0,
  • "twoFactorAuthenticationRequired": false,
  • "resetPassword": false,
  • "aclTemplate": { },
  • "expires_in": 0
}

Delete an access token

Authorizations:
bearerAuth
path Parameters
accessToken
required
string

The access token to be deleted

Responses

400

Invalid access token supplied

delete /v1/oauth2/token/{accessToken}

ExtremeGuest API Server URL

https://IP_Address/v1/oauth2/token/{accessToken}

guestusers

Configure and manage guest users. Operations supported by this resource correspond to managing guest users through the ExtremeGuest Web Admin GUI.

Create a new guest user account

Authorizations:
bearerAuth
Request Body schema: application/json

A valid GuestUserElement object with the attributes to be created

firstName
required
string <= 64 characters

First name of the guest user.

lastName
required
string <= 64 characters

Last name of the guest user.

email
string [ 6 .. 128 ] characters

Email address of the guest user. The email address can not be reused for another guest user. At least one field must be provided among userId, email, and mobileNumber. This property can not be modified after creation.

mobileNumber
string [ 10 .. 64 ] characters

Mobile number of the guest user. The string must contain numbers only, including country code. The mobile number can not be reused for another guest user. At least one field must be provided among userId, email, and mobileNumber. This property can not be modified after creation.

userId
string [ 1 .. 128 ] characters

User name for the guest user account. It is recommended to use only lower case letters and digits in the user name. White space characters and the characters @, -, :, . are not permitted in user name. The user name cannot be all digits and cannot be reused for another guest user. At least one field must be provided among userId, email, and mobileNumber. This property can not be modified after creation.

password
required
string [ 1 .. 128 ] characters

Password for the guest user account

organization
string <= 128 characters

Name of the guest user organization

reason
string <= 128 characters

Field to add any additional notes

siteName
required
string [ 1 .. 32 ] characters

Initial site of the guest user. The site must be already present.

groupName
required
string [ 1 .. 64 ] characters

User group of the guest user. The group must be already present.

startTime
required
string <date-time>

Time when the guest user account gets activated

expiryTime
required
string <date-time>

Time when the guest user account expires

id
string

A unique identifier generated by ExtremeGuest for each resource

Responses

200

Guest user account was created

405

Invalid input

post /v1/guestusers

ExtremeGuest API Server URL

https://IP_Address/v1/guestusers

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "mobileNumber": "stringstri",
  • "userId": "string",
  • "password": "string",
  • "organization": "string",
  • "reason": "string",
  • "siteName": "string",
  • "groupName": "string",
  • "startTime": "2019-08-07T17:37:51Z",
  • "expiryTime": "2019-08-07T17:37:51Z",
  • "id": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "mobileNumber": "stringstri",
  • "userId": "string",
  • "password": "string",
  • "organization": "string",
  • "reason": "string",
  • "siteName": "string",
  • "groupName": "string",
  • "startTime": "2019-08-07T17:37:51Z",
  • "expiryTime": "2019-08-07T17:37:51Z",
  • "id": "string"
}

Retrieve guest user information

Returns a single or multiple guest users

Authorizations:
bearerAuth
query Parameters
siteName
string

A valid site name of the specified guest user

networkName
string

A valid network name of the specified guest user

page
integer

The zero-relative start index of the entire list of items that are returned in the response. Default value of page is 0

page_size
integer

The number of items to return in the response. For example, the combination of page=0 and page_size=20 returns the first 20 items

Responses

200

Guest user information

400

Invalid input supplied

404

Guest user not found

get /v1/guestusers

ExtremeGuest API Server URL

https://IP_Address/v1/guestusers

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "mobileNumber": "stringstri",
  • "userId": "string",
  • "password": "string",
  • "organization": "string",
  • "reason": "string",
  • "siteName": "string",
  • "groupName": "string",
  • "startTime": "2019-08-07T17:37:51Z",
  • "expiryTime": "2019-08-07T17:37:51Z",
  • "id": "string"
}

Retrieve guest user account information by ID

Returns a single guest user

Authorizations:
bearerAuth
path Parameters
guestUserId
required
string

A valid ID for the guest user account to be retrieved

Responses

200

Guest user information

400

Invalid ID supplied

404

Guest user not found

get /v1/guestusers/{guestUserId}

ExtremeGuest API Server URL

https://IP_Address/v1/guestusers/{guestUserId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "mobileNumber": "stringstri",
  • "userId": "string",
  • "password": "string",
  • "organization": "string",
  • "reason": "string",
  • "siteName": "string",
  • "groupName": "string",
  • "startTime": "2019-08-07T17:37:51Z",
  • "expiryTime": "2019-08-07T17:37:51Z",
  • "id": "string"
}

Update a guest user account by ID

Authorizations:
bearerAuth
path Parameters
guestUserId
required
string

A valid ID for the guest user account to be updated

Request Body schema: application/json

A valid GuestUserElement object containing the updated parameters

firstName
required
string <= 64 characters

First name of the guest user.

lastName
required
string <= 64 characters

Last name of the guest user.

email
string [ 6 .. 128 ] characters

Email address of the guest user. The email address can not be reused for another guest user. At least one field must be provided among userId, email, and mobileNumber. This property can not be modified after creation.

mobileNumber
string [ 10 .. 64 ] characters

Mobile number of the guest user. The string must contain numbers only, including country code. The mobile number can not be reused for another guest user. At least one field must be provided among userId, email, and mobileNumber. This property can not be modified after creation.

userId
string [ 1 .. 128 ] characters

User name for the guest user account. It is recommended to use only lower case letters and digits in the user name. White space characters and the characters @, -, :, . are not permitted in user name. The user name cannot be all digits and cannot be reused for another guest user. At least one field must be provided among userId, email, and mobileNumber. This property can not be modified after creation.

password
required
string [ 1 .. 128 ] characters

Password for the guest user account

organization
string <= 128 characters

Name of the guest user organization

reason
string <= 128 characters

Field to add any additional notes

siteName
required
string [ 1 .. 32 ] characters

Initial site of the guest user. The site must be already present.

groupName
required
string [ 1 .. 64 ] characters

User group of the guest user. The group must be already present.

startTime
required
string <date-time>

Time when the guest user account gets activated

expiryTime
required
string <date-time>

Time when the guest user account expires

id
string

A unique identifier generated by ExtremeGuest for each resource

Responses

200

Updated guest user information

405

Invalid input

put /v1/guestusers/{guestUserId}

ExtremeGuest API Server URL

https://IP_Address/v1/guestusers/{guestUserId}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "mobileNumber": "stringstri",
  • "userId": "string",
  • "password": "string",
  • "organization": "string",
  • "reason": "string",
  • "siteName": "string",
  • "groupName": "string",
  • "startTime": "2019-08-07T17:37:51Z",
  • "expiryTime": "2019-08-07T17:37:51Z",
  • "id": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "mobileNumber": "stringstri",
  • "userId": "string",
  • "password": "string",
  • "organization": "string",
  • "reason": "string",
  • "siteName": "string",
  • "groupName": "string",
  • "startTime": "2019-08-07T17:37:51Z",
  • "expiryTime": "2019-08-07T17:37:51Z",
  • "id": "string"
}

Delete a guest user account by ID

Authorizations:
bearerAuth
path Parameters
guestUserId
required
string

A valid ID of the guest user account to be deleted

Responses

200

Guest user account was deleted successfully

400

Invalid ID supplied

404

Guest user not found

delete /v1/guestusers/{guestUserId}

ExtremeGuest API Server URL

https://IP_Address/v1/guestusers/{guestUserId}

Retrieve guest user account information by email ID

Returns a single guest user

Authorizations:
bearerAuth
path Parameters
emailId
required
string

A valid guest user email ID

query Parameters
page
integer

The zero-relative start index of the entire list of items that are returned in the response. Default value of page is 0

page_size
integer

The number of items to return in the response. For example, the combination of page=0 and page_size=20 returns the first 20 items

Responses

200

Guest user account information

400

Invalid ID supplied

404

Guest user not found

get /v1/guestusers/byemail/{emailId}

ExtremeGuest API Server URL

https://IP_Address/v1/guestusers/byemail/{emailId}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "mobileNumber": "stringstri",
  • "userId": "string",
  • "password": "string",
  • "organization": "string",
  • "reason": "string",
  • "siteName": "string",
  • "groupName": "string",
  • "startTime": "2019-08-07T17:37:51Z",
  • "expiryTime": "2019-08-07T17:37:51Z",
  • "id": "string"
}

Update a guest user account by email ID

Authorizations:
bearerAuth
path Parameters
emailId
required
string

The email address for the guest user account to be updated

Request Body schema: application/json

A valid GuestUserElement object containing the new values of parameters to be updated.

firstName
required
string <= 64 characters

First name of the guest user.

lastName
required
string <= 64 characters

Last name of the guest user.

email
string [ 6 .. 128 ] characters

Email address of the guest user. The email address can not be reused for another guest user. At least one field must be provided among userId, email, and mobileNumber. This property can not be modified after creation.

mobileNumber
string [ 10 .. 64 ] characters

Mobile number of the guest user. The string must contain numbers only, including country code. The mobile number can not be reused for another guest user. At least one field must be provided among userId, email, and mobileNumber. This property can not be modified after creation.

userId
string [ 1 .. 128 ] characters

User name for the guest user account. It is recommended to use only lower case letters and digits in the user name. White space characters and the characters @, -, :, . are not permitted in user name. The user name cannot be all digits and cannot be reused for another guest user. At least one field must be provided among userId, email, and mobileNumber. This property can not be modified after creation.

password
required
string [ 1 .. 128 ] characters

Password for the guest user account

organization
string <= 128 characters

Name of the guest user organization

reason
string <= 128 characters

Field to add any additional notes

siteName
required
string [ 1 .. 32 ] characters

Initial site of the guest user. The site must be already present.

groupName
required
string [ 1 .. 64 ] characters

User group of the guest user. The group must be already present.

startTime
required
string <date-time>

Time when the guest user account gets activated

expiryTime
required
string <date-time>

Time when the guest user account expires

id
string

A unique identifier generated by ExtremeGuest for each resource

Responses

200

Guest user account has been updated

405

Invalid input

put /v1/guestusers/byemail/{emailId}

ExtremeGuest API Server URL

https://IP_Address/v1/guestusers/byemail/{emailId}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "mobileNumber": "stringstri",
  • "userId": "string",
  • "password": "string",
  • "organization": "string",
  • "reason": "string",
  • "siteName": "string",
  • "groupName": "string",
  • "startTime": "2019-08-07T17:37:51Z",
  • "expiryTime": "2019-08-07T17:37:51Z",
  • "id": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "mobileNumber": "stringstri",
  • "userId": "string",
  • "password": "string",
  • "organization": "string",
  • "reason": "string",
  • "siteName": "string",
  • "groupName": "string",
  • "startTime": "2019-08-07T17:37:51Z",
  • "expiryTime": "2019-08-07T17:37:51Z",
  • "id": "string"
}

Delete a guest user account by email ID

Authorizations:
bearerAuth
path Parameters
emailId
required
string

The email address of the guest user account to be deleted

Responses

200

Guest user account has been deleted

400

Invalid ID supplied

404

Guest user not found

delete /v1/guestusers/byemail/{emailId}

ExtremeGuest API Server URL

https://IP_Address/v1/guestusers/byemail/{emailId}

Retrieve guest user account information by mobile number

Returns a single guest user

Authorizations:
bearerAuth
path Parameters
mobileNumber
required
string

The mobile number associated with the guest user account. The string must contain numbers only, including country code.

query Parameters
page
integer

The zero-relative start index of the entire list of items that are returned in the response. Default value of page is 0

page_size
integer

The number of items to return in the response. For example, the combination of page=0 and page_size=20 returns the first 20 items

Responses

200

Guest user account information

400

Invalid mobile number supplied

404

Guest user not found

get /v1/guestusers/bymobile/{mobileNumber}

ExtremeGuest API Server URL

https://IP_Address/v1/guestusers/bymobile/{mobileNumber}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "mobileNumber": "stringstri",
  • "userId": "string",
  • "password": "string",
  • "organization": "string",
  • "reason": "string",
  • "siteName": "string",
  • "groupName": "string",
  • "startTime": "2019-08-07T17:37:51Z",
  • "expiryTime": "2019-08-07T17:37:51Z",
  • "id": "string"
}

Update a guest user account by mobile number

Authorizations:
bearerAuth
path Parameters
mobileNumber
required
string

The mobile number associated with the guest user account to be updated. The string must contain numbers only, including country code.

Request Body schema: application/json

A valid GuestUserElement object containing the new values for parameters to be updated

firstName
required
string <= 64 characters

First name of the guest user.

lastName
required
string <= 64 characters

Last name of the guest user.

email
string [ 6 .. 128 ] characters

Email address of the guest user. The email address can not be reused for another guest user. At least one field must be provided among userId, email, and mobileNumber. This property can not be modified after creation.

mobileNumber
string [ 10 .. 64 ] characters

Mobile number of the guest user. The string must contain numbers only, including country code. The mobile number can not be reused for another guest user. At least one field must be provided among userId, email, and mobileNumber. This property can not be modified after creation.

userId
string [ 1 .. 128 ] characters

User name for the guest user account. It is recommended to use only lower case letters and digits in the user name. White space characters and the characters @, -, :, . are not permitted in user name. The user name cannot be all digits and cannot be reused for another guest user. At least one field must be provided among userId, email, and mobileNumber. This property can not be modified after creation.

password
required
string [ 1 .. 128 ] characters

Password for the guest user account

organization
string <= 128 characters

Name of the guest user organization

reason
string <=