Authentication

Your apps need to authenticate with the API using an app-specific API key or, in some cases, app ID.

Obtaining an API key

Sign up and create an app for your project. Each app is given its own API key and app ID.

Using an API key

Append your API key as a query parameter called apikey for each request to API endpoints. API keys never expire.

?apikey={your-api-key}

Using an app ID

Append your app ID as a query parameter called appId. This is only required for authorize flow.

?appId={your-app-id}

Your app and its clients

To ensure the privacy of everyone connected to a Premium Zone, your app can only access data related to clients that are registered to your app. Likewise, your app can only access zone specific data for the zone it is registered to.

For example, your app can only receive events (webhooks) triggered by a client that is registered to your app. Likewise, a client will only be visible in the list of connected clients in a zone if it is registered to your app.

When registering a client to your app, you provide your own token. This token is the only identifiable client data that will be exposed to your app.

API endpoints

Note that all HTTP POST endpoints expect parameters in JSON format in the request body, along with a Content-Type: application/json header.

Create code

Create a code for the /register or /deregister endpoint.

Endpoint

POST https://api.premiumzone.com/v2/code

Request query parameters

apikey – API key for your app

Request body

{ "token": "{client-token}" }

tokenString Client token that will be paired with upcoming request

Response body

{ "code": "{generated-code}" }

codeString One-time code that can be used with the /register or /deregister endpoint. This code is only valid for 10 minutes after creation.

Response status

201 Created

Register a client to your app

For your app to be able to receive events (webhooks) related to a client, or to include a client when your app gets the list of clients in a zone, the client needs to be registered to your app. The client that performs this request will be paired with the token used to create the one-time code.

This request needs to be performed directly from the client and should not include the apikey query parameter.

Endpoint

POST https://api.premiumzone.com/v2/register

Request body

{ "code": "{your-code}" }

codeString Acquired from the /code endpoint

Response body

None.

Response status

200 OK

Expected errors

In the case of a client not being connected to a Premium Zone, this is the expected response:

Response body

{ "errors": [ { "message": "Validation failed" } ], "errorDetails": [ { "message": "You’re not in a Premium Zone" } ] }

Response status

404 Not Found

Deregister a client from your app

This request needs to be performed directly from the client and should not include the apikey query parameter.

Endpoint

POST https://api.premiumzone.com/v2/deregister

Request body

{ "code": "{your-code}" }

codeString Acquired from the /code endpoint

Response body

None.

Response status

200 OK

Expected errors

In the case of a client not being connected to a Premium Zone, this is the expected response:

Response body

{ "errors": [ { "message": "Validation failed" } ], "errorDetails": [ { "message": "You’re not in a Premium Zone" } ] }

Response status

404 Not Found

Get clients in a zone

Endpoint

GET https://api.premiumzone.com/v2/zone

Request query parameters

apikey – API key for your app

ip – (Optional) IP address of zone to request clients in, defaults to request origin

Example response body

{ "zone": { "id": 1, "ip": "1.1.1.1", "token": "{zone-token}" }, "isZone": true, "clients": [{ "token": "{client-token}" }, { "token": "{client-token}" }] }

zoneObject Describes the requested zone. Please note that the token property will only be included if your app is registered to this zone. See the /zone/register endpoint for more details.

isZoneBoolean true if requested ip is a zone, otherwise false.

clientsArray List of all connected clients.

Response status

200 OK

Check if a zone exists

Endpoint

GET https://api.premiumzone.com/v2/is-zone

Request query parameters

apikey – API key for your app

ip – (Optional) IP address of zone to request clients in, defaults to request origin

Example response body

{ "zone": { "id": 1, "ip": "1.1.1.1" }, "isZone": true }

zoneObject Describes the requested zone

isZoneBoolean true if requested ip is a zone, otherwise false

Response status

200 OK

Authorize API app for a zone

Some endpoints require specific scopes to be authorized by a user. These scopes are authorized on a app->zone level. Authorization can only be performed when a user is in a zone.

Use this endpoint to prompt your users for access to specific scopes. In general, this is the expected flow:

  1. Your app performs an API request that requires one or more pre-authorized scopes, e.g. basic.
    • API responds with “Insufficient permissions” error.
  2. Your app redirects the user to this endpoint. You pass in the scopes you want access to and the URI that should be called when the user grants or denies permission.
    • Your user makes a decision and gets redirected to the specified redirect URI. Any errors will be passed along as a query string parameter.
  3. Your app handles error (if any) and possibly attempts to perform action from step 1 again.

Endpoint

POST https://api.premiumzone.com/v2/zone/authorize

Request query parameters

appId – App ID for your app

redirectUri – The URI to redirect the user back to after granting or denying permission

scope – The scopes your app needs permission to, comma separated. See Available scopes below.

Available scopes

  • basic – Required for the /zone/register endpoint

Expected behaviors

Requested scopes are already authorized for this app and zone

  • User is immediately redirected to redirectUri.

An error occurs or user denies access

  • User is redirected to redirectUri with an ?error query string describing the error.

Register an API app with a zone

Using this endpoint you can store an app-specific token with a zone.

Requires the basic scope. For more details, see the /zone/authorize endpoint.

Endpoint

POST https://api.premiumzone.com/v2/zone/register

Request query parameters

apikey – API key for your app

ip – (Optional) IP address of zone to register your app with, defaults to request origin

Request body

{ "token": "{zone-token}" }

tokenString Your registration token

Response body

{ "success": [ { "message": "App registered successfully" } ], "token": "{zone-token}" }

Response status

201 Created

Expected errors

If your app isn’t authorized for your zone with the basic scope, this is the expected response:

Response body

{ "errors": [ { "message": "Validation failed" } ], "errorDetails": [ { "message": "Insufficient permissions" } ] }

Response status

403 Forbidden

Deregister an API app from a zone

Removes the token property from a zone.

Requires the basic scope. For more details, see the /zone/authorize endpoint.

Endpoint

POST https://api.premiumzone.com/v2/zone/deregister

Request query parameters

apikey – API key for your app

ip – (Optional) IP address of zone to register your app with, defaults to request origin

Response body

{ "success": [ { "message": "App deregistered successfully" } ] }

Response status

200 OK

Expected errors

If your app isn’t authorized for your zone with the basic scope, this is the expected response:

Response body

{ "errors": [ { "message": "Validation failed" } ], "errorDetails": [ { "message": "Insufficient permissions" } ] }

Response status

403 Forbidden

Events (webhooks)

API events are triggered when a client connects or disconnects. When an event occurs, the API will perform an HTTP POST request to your app’s webhook URL. Your app will only receive webhook requests related to events triggered by clients that have previously registered to your app.

Setting up webhooks

Each app has its own webhook URL. This can be configured from your app management.

Client connecting

The webhook request is a HTTP POST with a JSON payload in the request body. Example request body:

{ "eventType": "connected", "zone": { "id": 1, "ip": "1.1.1.1" }, "client": { "token": "{client-token}" } }

eventTypeString Type of the event that was triggered

zoneObject The zone for which the event occurred

clientObject Client that triggered the event

Client disconnecting

The webhook request is a HTTP POST with a JSON payload in the request body. Example request body:

{ "eventType": "disconnected", "zone": { "id": 1, "ip": "1.1.1.1" }, "client": { "token": "{client-token}" } }

eventTypeString Type of the event that was triggered

zoneObject The zone for which the event occurred

clientObject Client that triggered the event

Errors

If an error occurs while performing a request you will get a response including an HTTP error code and a JSON formatted body describing the error. Below is an example of a response to the /code endpoint request with an empty JSON payload.

{ "errors": [ { "message": "Validation failed" } ], "errorDetails": [ { "param": "token", "message": "Parameter is required" } ] }

errorsArray Contains a list of objects describing the errors that occurred

errorDetailsArray Contains a list of objects with details about the errors

Usage and best practices

Do not expose your API key to your clients. Only endpoints that uses a code instead of an apikey have CORS enabled, all other requests should be done by your backend.

API endpoints

In general, all HTTP GET endpoints expect query parameters, if there are any. Likewise, all HTTP POST endpoints expect parameters in JSON format in the request body, along with a Content-Type: application/json header.

Have your clients call your backend to fetch clients and then use the origin of that request as the ip parameter when calling the API. In general, you only want to expose clients in a zone to others in that same zone.