API

Luminate API (V2)

Download OpenAPI specification:Download

Introduction

Luminate API uses common RESTful resourced based URL conventions and JSON as the exchange format.
Properties names are case-sensitive.
Some of Luminate API calls omit None values from the API response.

The base-URL is api.<tenant-name>.luminatesec.com. For example, if your administration portal URL is admin.acme.luminatesec.com, then your API base-URL is api.acme.luminatesec.com.

All examples below are performed on a tenant called acme.

Common Operations Steps

Below you may find a list of common operations and the relevant API calls for each. Each of these operations can also be performed by using the administrative portal at https://admin.acme.luminatesec.com.

  1. Creating a site and deploying a connector:
    1. Creating a new site using the Create site API.
    2. Once a site is created you can use its Id (returned in the response of the Create Site request) and call the Create connector API.
    3. Deploy the Luminate connector:
      1. Retrieve the deployment command using the Connector Deployment Command API.
      2. Execute the command on the target machine.
  2. Creating an application:
    1. An application is always associated with a specific site in order to route the traffic to the application via the connectors associated with the same site. In order to create the application, call the Create Application API
    2. Once the application is created, you *must* assign the application to a specific site in order to make it accessible. Assign the application to the required site using the Bind Application to Site API.
    3. Once the application is assigned to a site, you should update the access permissions for the application to allow specific entities (users/groups) to access the application using the Set/Update Access Policy API.

Object Model

The object model of the API is built around the following:

  1. Sites - Site is a representation of the physical or virtual data center your applications reside in.
  2. Connectors - A connector is a lightweight piece of software connecting your site to the Luminate platform.
  3. Applications - Application is the internal resource you would like to publish using Luminate.
  4. Access Policies - Luminate Access Policy lets administrators authorize who can access specific resources.
    The Access Policy is implemented by a set of 2-tuple entries named Directory Entity Binding:
    • Directory-Entity: user/group/api-client identity.
    • Security-Role: Access Permissions. Relevant for SSH resources only.
    • Identities: User/Group/Api-client that can be managed by one of the supported Identity Providers or locally by Luminate internal Identity Provider.
  5. Logs - Luminate internal logs for audit and forensics purposes:
    1. Audit Logs audit all operations done through the administration portal
    2. Web Access Logs audit any web access
    3. SSH Logs audit any SSH access
    4. RDP Logs audit any RDP access

Authentication

Authentication is done using OAuth2 with the Bearer authentication scheme.

OAuth2

Security scheme type: OAuth2
clientCredentials OAuth Flow
Token URL: https://api.acme.luminatesec.com/v1/oauth/token
Scopes:

    The Luminate API is available to Luminate users who have administrative privileges in their Luminate tenant. An administrator should create an API client through the Luminate Admin portal, check the ‘Allow access to Luminate management API’ permission and copy the ‘Client Id’ and the ‘Client Secret’.

    Retrieving the API access token is done using Basic-Authentication scheme, POST of a Base64 encoded Client-ID and Client-Secret:

    curl -X POST \
    
    https://api.acme.luminatesec.com/v1/oauth/token \
    
    -u yourApiClientId:yourApiClientSecret

    This call returns the following JSON: { "access_token":"edfe22e3-eb4c-4c83-8ce3-3152e6a2XXX", "expires_in":86400, "scope":"luminate-scope", "token_type":"Bearer", "error":"", "error_description":""}

    All further API calls should include the ‘Authorization’ header with value “Bearer AccessToken”

    For example:

      curl -H "Authorization: Bearer edfe22e3-eb4c-4c83-8ce3-3152e6a2XXX" "https://api.acme.luminatesec.com/v2/applications/d9f6ca17-9f2c-488c-aa86-51924a37092e"

    Versioning and Compatibility

    The latest Major Version is v2.

    The Major Version is included in the URL path (e.g. /v2/applications ) and it denotes breaking changes to the API. Minor and Patch versions are transparent to the client.

    Pagination

    Some of our API responses are paginated, meaning that only a certain number of items are returned at a time. The default number of items returned in a single page is 50. You can override this by passing a size parameter to set the maximum number of results, but cannot exceed 100. Specifying the page number sets the starting point for the result set, allowing you to fetch subsequent items that are not in the initial set of results. The sort order for returned data can be controlled using the sort parameter.
    You can constrain the results by using a filter.

    Note: Most methods that support pagination use the approach specified above. However, some methods use varied versions of pagination. The individual documentation for each API method is your source of truth for which pattern the method follows.

    Auditing

    All authentication operations and modify operations (POST, PUT, DELETE) are audited.

    Rate-limiting

    The API has a rate limit of 5 requests per second. If you have hit the rate limit, then a ‘429’ status code will be returned. In such cases, you should back-off from submitting new requests for 1 second before resuming.

    Note that rate-limitation applies to the accumulated requests of all of your clients. For example, if you have 6 clients submitting requests simultaneously at a rate of 1 request per second for each one then one of them is likely to get a 429 status code.

    Support

    For additional help you may refer to our support at https://support.luminate.io.

    Each request submitted to the API returns a unique request ID that is generated by the API. The request ID will be returned in header x-lum-request-id. If you need to contact us about any specific request then this ID will serve as a reference to the given request.

    Sites

    Site is a representation of the physical or virtual data center your applications reside in.

    Create Site

    post /sites

    Default server.

    https://api.acme.luminatesec.com/v2/sites

    Creates a Site in your Luminate tenant.

    Authorizations:
    Request Body schema: application/json
    name
    required
    string [ 2 .. 700 ]

    A descriptive name of the site.

    kubernetes_persistent_volume_name
    string (kubernetes_persistent_volume_name)
    Default: null

    A persistent volume to be used for storing the Luminate connector TLS Certificate.
    The persistent volume must be defined for deployments of type Kubernetes in order to support connector failovers. This property value is inherited from the contained site and can be overridden at the connector level.

    mute_health_notification
    boolean
    Default: false

    Indication whether health notifications are enabled for this site.

    kerberos_configuration
    object (KerberosConfiguration)

    Configuring Kerberos Constrained Delegation (KCD) SSO for Corporate Web Applications
    Note: This configuration applies to new connectors only.

    Responses

    201

    successful operation.

    Response Schema: application/json
    name
    required
    string [ 2 .. 700 ]

    A descriptive name of the site.

    id
    string <uuid>

    A unique identifier of this site. Note: This field is required for any operation other than initial creation.

    kubernetes_persistent_volume_name
    string (kubernetes_persistent_volume_name)
    Default: null

    A persistent volume to be used for storing the Luminate connector TLS Certificate.
    The persistent volume must be defined for deployments of type Kubernetes in order to support connector failovers. This property value is inherited from the contained site and can be overridden at the connector level.

    connectors
    Array of string <uuid>

    IDs of all connectors included in this site.

    application_ids
    Array of string <uuid>

    IDs of all applications included in this site.

    connector_objects
    Array of object (Connector)
    site_status
    object (SiteStatus)
    mute_health_notification
    boolean
    Default: false

    Indication whether health notifications are enabled for this site.

    kerberos_configuration
    object (KerberosConfiguration)

    Configuring Kerberos Constrained Delegation (KCD) SSO for Corporate Web Applications
    Note: This configuration applies to new connectors only.

    400

    Bad Request - The server cannot or will not process the request due to an apparent client error.

    401

    Unauthorized - Authentication is required and has failed or has not yet been provided.

    403

    Forbidden - The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource, or may need an account of some sort.

    409

    Conflict - Value of one of the provided fields is already used by an existing object.

    500

    Internal Server Error.

    Request samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "name": "DataCenterEurope",
    • "kubernetes_persistent_volume_name": "pv-81e55b9b-298b-11e9-b2bd-0ace4f35b420",
    • "mute_health_notification": false,
    • "kerberos_configuration":
      {
      }
    }

    Response samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "id": "6fd0a892-8b70-471a-9dd7-bf374b07451f",
    • "name": "DataCenterEurope",
    • "kubernetes_persistent_volume_name": "pv-81e55b9b-298b-11e9-b2bd-0ace4f35b420",
    • "connectors":
      [
      ],
    • "application_ids":
      [
      ],
    • "connector_objects":
      [
      ],
    • "site_status":
      {
      },
    • "mute_health_notification": false,
    • "kerberos_configuration":
      {
      }
    }

    List Sites

    get /sites

    Default server.

    https://api.acme.luminatesec.com/v2/sites

    Return an array of paginated JSON objects. Each object represents a site configured in your Luminate tenant.
    The supported sort keys are either ‘name’ for sorting by site name.
    Filter applies for the following fields: "name" and "description".
    Using the query filter=test will return all the sites for which one or more of the above listed fields contain "test" Filtering by Application ID may be applied - in such a case, Sites that are associated with this Application will be returned. If the Application ID does not exist then an empty array is returned.

    Authorizations:
    query Parameters
    sort
    string
    Default: "id,asc"
    Example: "name,desc"

    The value of this parameter is a comma-separated list of sort key and sort direction. By default, query results are sorted in ascending order by item id. The supported sort directions are either 'asc' for ascending or 'desc' for descending.

    size
    number <int32> <= 100
    Default: 50
    Example: 10

    The number of items returned in a single page.

    page
    number <int32>

    The page number.

    filter
    string
    Example: "test"

    The string by which the results are filtered (see description)

    Responses

    200

    successful operation.

    Response Schema: application/json
    content
    Array of object (Site)
    first
    boolean

    Indicates whether the current page is the first one.

    last
    boolean

    Indicates whether the current page is the last one.

    size
    number <int32>

    Maximum number of elements per page.

    totalElements
    number <int32>

    Number of elements included in the response.

    totalPages
    number <int32>

    Number of pages included in the response.

    number
    number <int32>

    Page number

    numberOfElements
    number <int32>

    Number of elements in current page.

    400

    Bad Request - The server cannot or will not process the request due to an apparent client error.

    401

    Unauthorized - Authentication is required and has failed or has not yet been provided.

    403

    Forbidden - The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource, or may need an account of some sort.

    500

    Internal Server Error.

    Request samples

    Copy
    curl -X GET 'https://api.acme.luminatesec.com/v2/sites?sort=name,desc&size=10&page=0&filter=test' -H 'Content-Type: application/json' -H 'Authorization:Bearer b8246240-8e79-495c-9959-332af85d5014' -i 

    Response samples

    application/json
    Copy
    Expand all Collapse all
    {
    • "content":
      [