Using the StarLeaf Cloud API
Last updated July 19, 2017 Cloud API
The StarLeaf Cloud API is a RESTful API that enables external clients to manage StarLeaf deployments and services.
This document defines the Cloud API and describes its usage.
To use the API, the client must make HTTPS requests to the StarLeaf Cloud API server: https://api.starleaf.com/v1
The body type for all POST and PUT requests must be of type application/json.
GET and DELETE requests do not require a body. Where the server response includes a body, it is also of type application/json. Strings must be UTF-8 encoded. All responses include the header X-SL-SERVER, which identifies the server from which the response came. The client should include this information in any logs, to assist with debugging any issues.
Details of the requests, together with the specification of the associated JSON bodies, are given in the following sections. Where a field is defined as being optional, then it may be omitted from the request body, in which case the default value is used. Response bodies may contain additional optional fields that are not described in this specification. Request bodies are permitted to include these additional fields so long as the value is not modified.
We recommend that clients do not rely on the default value of boolean arguments. StarLeaf may change any default value in a future release.
Before the client can make any API requests, the client must first authenticate itself with the StarLeaf Cloud API server. Clients authenticate with the StarLeaf Cloud either as an individual user or as an integration which is effectively a ‘dummy’ user which can either have administrator access to the organization or not.
The two authentication methods:
- Authentication header method: Introduced in Cloud 4.6 and used for integration access. This allows a client to authenticate with the StarLeaf Cloud as a ‘dummy’ user. You can use this as the authentication method for clients that will create and manage conferences. Such a client can also request a feature list and the software version of the server. If you give the integration ‘admin’ privileges, it can also create users in its own organization. Such a client cannot be associated with a real user; therefore the conferences it creates would not belong to a ‘real’ owner. Such a client cannot access the Cloud with reseller privileges. For more information, refer to Authentication using authentication header method
- Challenge-response method: To authenticate as a real user, the client must use the challenge-response method of authentication. The set of requests that these clients can use are only restricted by the privileges associated with the user whose credentials have been used for the authentication. For example, a user with reseller-level privileges can create new organizations and users, whereas, a user with no privileges is restricted to managing and creating conferences, sending guest invites, and requesting version information and a feature list. For more information, refer to Authentication using challenge and response method