Agent activation API

CPE subscriptions with SamKnows allow a certain number of activated CPE at any one time although as many can be registered with our infrastructure as necessary in a dormant/inactive state. This API allows you to activate, deactivate and view the current state of any applicable agent.

The Agent Activation API is a JSON based with all requests and responses using JSON. This Agent Activation API requires a CPE Subscription and access token which should be passed in the HTTP Authentication header. All communication should be over HTTP with TLS 1.2.

Please read general documentation of APIs here before continuing.

Development

Developer documentation is available below. URLs for production and development purposes will be provided upon commencement of a project. Authentication tokens are managed through the SamKnows One UI.

Performance and capacity

We actively manage capacity planning to ensure that it can handle as many simultaneous connections/sessions as required by our clients, it has been load tested to be able to handle thousands of hits per minute and scales easily and linearly. Requests usually respond within a couple of hundred milliseconds.

Logging

API call counts are logged for auditing purposes and activations/deactivations are added to the CPE activation log, displayed in SamKnows One.

Authentication

All requests to the Agent Activation API require authentication using a HTTP Authorization header and a valid token. This token is provided by SamKnows and generated from within SamKnows One.

Example: HTTP Authorization header

Authorization: Bearer <token>

Example: Authentication failure

If the request cannot be authentication a HTTP 403 response will be returned.

+ Request (application/json)

          + Headers

                  Accept: application/json
                  Authorization: Bearer <token>

          + Body

                      {
                        "state": "active"
                      }
      + Response 403 (application/json)

          + Body

                    {
                      "code": "ACCESS_DENIED",
                      "message": "Access Denied",
                    }

Activate or deactivate a CPE [PUT /cpe/{mac}]

This endpoint allows you to indefinitely activate or deactivate a CPE with an optional TTL (ttl: in days after which the CPE will be deactivated), a test schedule (test_schedule_id) and a text reason (reason).

URL parameters

ParameterDescriptionmacThe MAC address of the CPE to be activated/deactivated

Body fields

FieldDescriptionTypeAllowed valuesExampleRequiredActivation OnlystateThe desired state for the CPEstring"active", "inactive""active"YesNoreasonFree text reason for the changen/astring"My reason"NoNottlThe number of days a CPE should be active after which it will be deactivated, if a TTL was previously specified this value will either extend the TTL or make it permanentinteger or nullnull or integer greater than 030NoYestest_schedule_idThe ID of the test schedule the CPE should use when activeintegerA valid test schedule id10NoYes

Example: Activating a CPE

+ Request (application/json)

          + Headers

                  Accept: application/json
                  Authorization: Bearer <token>

          + Body

                      {
                        "state": "active"
                      }

      + Response 200 (application/json)

          + Body

                      {
                        "code": "OK",
                        "message": "Request successful"
                      }

Example: Activating a CPE for 30 days on test schedule 10

      + Request (application/json)

          + Headers

                  Accept: application/json
                  Authorization: Bearer <token>

          + Body

                      {
                        "state": "active",
                        "ttl": 30,
                        "test_schedule_id": 10
                      }

      + Response 200 (application/json)

          + Body

                      {
                        "code": "OK",
                        "message": "Request successful"
                      }
      

Example: Deactivating a CPE

+ Request (application/json)

          + Headers

                  Accept: application/json
                  Authorization: Bearer <token>

          + Body

                      {
                        "state": "inactive",
                      }

      + Response 200 (application/json)

          + Body

                      {
                        "code": "OK",
                        "message": "Request successful"
                      }

      + Response 422 (application/json)

          + Body

                      {
                        "code": "VALIDATION_FAIL",
                        "message": "Validation failed",
                        "errors": {
                          "subscription": "CPE already inactive"
                        }
                      }

Example: Already active CPE error

+ Request (application/json)

          + Headers

                  Accept: application/json
                  Authorization: Bearer <token>

          + Body

                      {
                        "state": "active",
                      }

      + Response 422 (application/json)

          + Body

                      {
                        "code": "VALIDATION_FAIL",
                        "message": "Validation failed",
                        "errors": {
                          "subscription": "CPE already active"
                        }
                      }
      

Example: Invalid MAC address

+ Request (application/json)

          + Headers

                  Accept: application/json
                  Authorization: Bearer <token>

          + Body

                      {
                        "state": "active",
                      }

      + Response 404 (application/json)

          + Body

                      {
                        "code": "NOT_FOUND",
                        "message": "Not found"
                      }

View a CPEs state [GET /cpe/{mac}]

This endpoint enables the retrieval of a CPE state (active or inactive)

URL parameters

ParameterDescriptionmacThe MAC address of the CPE to be retrieved

Example: Retrieving a CPE's state

+ Request (application/json)

          + Headers

                  Accept: application/json
                  Authorization: Bearer <token>

      + Response 200 (application/json)

          + Body

                      {
                        "code": "OK",
                        "message": "Request successful",
                        "data": {
                          "state": "active"
                        }
                      }

Example: Retrieving a CPE's state with a TTL set

+ Request (application/json)

          + Headers

                  Accept: application/json
                  Authorization: Bearer <token>

      + Response 200 (application/json)

          + Body

                      {
                        "code": "OK",
                        "message": "Request successful",
                        "data": {
                          "state": "active",
                          "expires_at": "2018-06-23T07:55:08+00:00"
                        }
                      }
      

Example: Invalid MAC address

+ Request (application/json)

          + Headers

                  Accept: application/json
                  Authorization: Bearer <token>

      + Response 404 (application/json)

          + Body

                      {
                        "code": "NOT_FOUND",
                        "message": "Not found"
                      }

Errors

If an error occurs while processing a request to the Agent Activation API, you may receive the following error:

+ Response 500 (application/json)

          + Body

                      {
                        "code": "UNKNOWN_ERROR",
                        "message": "An unexpected error has occurred. This has been reported to our engineering teams, please try again shortly.",
                      }