List Tenants
============

.. http:get:: /sk-api/v1/tenants

  Get a list of tenants.

  :reqheader Authorization: The client's :ref:`Authorization header <authentication>`.

  :query managingOrgCode: (optional) Filter by tenants registered to the specified managing organization. If omitted, query for tenants from all managing organizations for which the user has permission.
  :query cursor: (optional) String value used to navigate result pagination.

  :status 200 OK: Query successful.

    :Response Data: - **tenants** -- A list of tenants.
                    - **nextCursor** -- 100 results are returned at a time. If more are available, this string value can be used to query the next set of results. If no more results are available, this value will be missing.

    Each entry in **tenants** is a JSON representation of a tenant in Skykit Admin.

    .. _user_response_data:

    :Tenant:

        - **domainName** -- The name of the domain to which this tenant is registered.
        - **managingOrgCode** -- The unique identification code of the managing organization to which this tenant belongs.
        - **managingOrgName** -- The name of the managing organization to which this tenant belongs.
        - **numberOfDisplays** -- The number of displays registered to this tenant.
        - **tenantCode** -- The tenant's unique identification code.
        - **tenantName** -- The tenant's name.


  :status 400 Bad Request: Request parameters invalid.

    :Response Data: - **message** -- A human-readable message explaining what went wrong.

  :status 401 Unauthorized: Authorization headers invalid.

    :Response Data: - **message** -- Unauthorized for URL.

  :status 403 Forbidden: Something was wrong in the authentication headers.

    :Response Data: - **message** -- Insufficient permission.

  **Example request**:

  .. sourcecode:: http

    GET /sk-api/v1/tenants HTTP/1.1

  **Example response**:

  .. sourcecode:: http

    HTTP/1.1 200 OK
    Content-Type: application/json

  .. sourcecode:: javascript

    {
      "tenants": [
        {
          "domainName": "example_domain_1.com",
          "managingOrgCode": "skykit_example_managing_org",
          "managingOrgName": "Skykit Example Managing Org.",
          "numberOfDisplays": 5
          "tenantCode": "skykit_example_tenant_1",
          "tenantName": "Skykit Example Tenant 1",
        },
        {
          "domainName": "example_domain_2.com",
          "managingOrgCode": "skykit_example_managing_org",
          "managingOrgName": "Skykit Example Managing Org.",
          "numberOfDisplays": 3
          "tenantCode": "skykit_example_tenant_2",
          "tenantName": "Skykit Example Tenant 2",
        }
      ],
      "nextCursor": "BS1OTNXKGYYOGSQ="
    }



  **Example usage**:

  .. sourcecode:: python

    from sign_jwt import make_headers  # see: Authentication
    from tqdm import tqdm  # for progress bar, if desired
    import requests


    BASE_URI = 'https://skykit-provisioning.appspot.com'
    LIST_TENANTS_ENDPOINT = 'sk-api/v1/tenants'
    URI = '{}/{}'.format(BASE_URI, LIST_TENANTS_ENDPOINT)


    def list_tenants(managing_org_code=None, tqdm=None):

        headers = make_headers()

        params = {}
        if managing_org_code:
            params['managingOrgCode'] = managing_org_code

        if tqdm:
            pbar = tqdm()
        cursor = ''
        tenants = []
        while True:
            response = requests.get(URI, headers=headers, params=params)
            response.raise_for_status()

            tenants_page = response.json()['tenants']
            tenants += tenants_page
            if tqdm:
                pbar.update(len(tenants_page))

            cursor = content.get('nextCursor')
            if cursor:
                params['cursor'] = cursor
            else:
                break

        return tenants


    example_tenants = list_tenants(managing_org_code='skykit_example_managing_org', tqdm=tqdm)