Welcome, Guest Login

Public Cloud Center

Add-On Provider API

Last Updated: Apr 19, 2017 10:46AM EDT

The Add-on Provider API is implemented by the add-on provider - this API is how Xervo interacts with a customer’s add-on service.

Provider API

There are two major pieces the configuring a Xervo add-on: supplying an addon-manifest.json configuration file and building an API which Xervo will use to provision, deprovision and update add-ons for users. The API must use HTTP basic authentication using the ID and password provided in the add-on manifest (explained below).

An add-on provider will implement an API with two endpoints, one for working with the add-on (base_url) and one to allow users to authenticate and manage their account on the provider’s platform (sso_url). The specifics of these routes, along with the message formats are defined below.

Add On Manifest

When creating a new add-on, an addon-manifest.json must be supplied which defines how your add-on resources will be compiled into a user's project. The manifest also provides configuration variables which are what will be compiled into the environment when the add-on has been provisioned. These configuration variables must be prefixed with your add-on ID.

Note: to create a skeleton manifest using the dia test utility, run dia init.

{
  "id": "addonid",
  "api": {
    "config_vars": [ "ADDONID_API_KEY" ],
    "password": "password_goes_here",
    "sso_salt": "salt_goes_here",
    "production": {
      "base_url": "https://yourapp-nnnn.app.xervo.io/xervo/resources",
      "sso_url": "https://yourapp-nnnn.app.xervo.io/sso/login"
    },
    "test": {
      "base_url": "http://localhost:8000/xervo/resources",
      "sso_url": "http://localhost:8000/sso/login"
    }
  }
}

API Endpoints

The base API endpoint URL must be defined in your manifest as part of the API property (see example above). This URL is how Xervo will interface with your add-on. API base endpoints (excluding single sign on) must implement basic authentication using the ID and password supplied in the manifest. Successful attempts must return 200 status code.

It is strongly suggested that the dia test utility be run for all add-ons prior to submitting the add-on to Xervo.

Provision / POST

A provision from Xervo will be a POST to the API base URL defined in the provider's manifest.

Request body POST to /xervo/resources

{
  "xervo_id": "addonid123",
  "email": "user@example.com",
  "plan": "basic",
  "region": "amazon-web-services::us-east-1",
  "callback_url": "https://api.xervo.io/vendor/apps/addonid123",
  "options": {}
}

Expected response body

{
  "id": "300",
  "config": { "ADDONID_API_KEY": "1234567" },
  "message": "some response message"
}

Plan change / PUT

A plan change from Xervo will be a PUT to your API base URL with the ID of the provisioned add-on (supplied by the provider - response from the provision request) as a parameter.

Request body PUT to /xervo/resources/300

{ "xervo_id": "addonid123", "plan": "foo" }

Expected response

{ "config": { "ADDONID_API_KEY": "7654321" }, "message": "response message" }

Deprovision / DELETE

A deprovision from Xervo will be a DELETE to your API base URL with the ID of the provisioned add-on (supplied by the provider - response from the provision request) as a parameter.

Note that the expected response is a 200.

Single sign on

A single sign on request will be a POST request to the API SSO URL defined in the provider's manifest

Request body

{
  "nav-data": "",
  "email": "username@example.com",
  "timestamp": "1369950166",
  "id": "myaddon",
  "token": "fa6d5e2e8a210e6fd03d6241b2131eeaff6b23dd"
}

Validating the single sign on token

A single sign on request includes a timestamp and token which must be validated using the provided timestamp and the salt defined in the manifest. This validation uses a SHA1 hash with hex digest as follows:

id:salt:timestamp

The result must match the supplied token to authenticate a single sign on user.


Go to top
 

Contact Us

    Our Support Policy
    Submit a Support Request

  • Public Cloud Support Hours
    9am-5pm EST Mon-Fri
    Outside of these hours response times may be up to 24hrs.


    Submit a support ticket by clicking 'status and support' icon on the left side of this page.



help@hellotangible.com
https://cdn.desk.com/
false
desk
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
false
Invalid characters found
/customer/en_us/portal/articles/autocomplete