### Entitlement Requirement Example

Source: https://developers.lumos.com/reference/info

Demonstrates how to override base min/max values for entitlement types and specific capabilities. The key is the capability name, and it shows an example for when 'create_account' requires a ROLE and not a LICENSE.

```json
{
  "requirements": {
    "create_account": {
      "max": 0
    }
  }
}
```

--------------------------------

### Get Application

Source: https://developers.lumos.com/reference/get_application

Endpoint to retrieve details of a specific application instance.

```APIDOC
## GET /applications/{application_instance_id}

### Description
Retrieves the details of a specific application instance.

### Method
GET

### Endpoint
`/applications/{application_instance_id}`

### Parameters
#### Path Parameters
- **application_instance_id** (string) - Required - The ID of the application to retrieve.

#### Query Parameters
- **include_raw_data** (boolean) - Optional - Whether to include raw data in the response.
- **page_token** (string) - Optional - Token for pagination.

### Request Example
```json
{
  "request": {
    "application_instance_id": "app-123e4567-e89b-12d3-a456-426614174000"
  },
  "include_raw_data": true,
  "page": {
    "token": "some-pagination-token"
  }
}
```

### Response
#### Success Response (200)
- **application_details** (object) - Details of the application.
- **raw_data** (object) - Raw data associated with the application (if requested).

#### Response Example
```json
{
  "application_details": {
    "id": "app-123e4567-e89b-12d3-a456-426614174000",
    "name": "Example Application",
    "version": "1.0.0"
  },
  "raw_data": {
    "key": "value"
  }
}
```
```

--------------------------------

### Get Art API Request (cURL)

Source: https://developers.lumos.com/reference/meta

This snippet demonstrates how to make a GET request to the Lumos 'Get Art' API endpoint using cURL. It specifies the URL and the 'accept' header for the response format. This is a basic example to verify API connectivity.

```shell
curl --request GET \
     --url https://api.lumos.com/art \
     --header 'accept: text/plain'
```

--------------------------------

### Pagination Parameters Example

Source: https://developers.lumos.com/reference/get_connected_info

Shows the structure for pagination parameters used in requests and responses. It includes a token for retrieving subsequent pages and the size of items returned per page.

```json
{
  "token": "opaque_token_string",
  "size": 100
}
```

--------------------------------

### Get Art API Request (Ruby)

Source: https://developers.lumos.com/reference/meta

This Ruby snippet illustrates how to retrieve Lumos ASCII art via an HTTP GET request. It uses the 'net/http' library to interact with the Lumos API. This example is suitable for Ruby developers looking to integrate with the Lumos API.

```ruby
require 'net/http'
require 'uri'

uri = URI.parse('https://api.lumos.com/art')
response = Net::HTTP.get_response(uri)

puts "Status Code: #{response.code}"
puts response.body
```

--------------------------------

### Get Art API Request (Node.js)

Source: https://developers.lumos.com/reference/meta

This snippet shows how to fetch Lumos ASCII art using Node.js. It utilizes the built-in 'https' module to make a GET request to the specified API endpoint. This example is useful for integrating Lumos API functionality into Node.js applications.

```javascript
const https = require('https');

const options = {
  hostname: 'api.lumos.com',
  port: 443,
  path: '/art',
  method: 'GET',
  headers: {
    'accept': 'text/plain'
  }
};

const req = https.request(options, (res) => {
  console.log('statusCode:', res.statusCode);
  let data = '';
  res.on('data', (chunk) => {
    data += chunk;
  });
  res.on('end', () => {
    console.log(data);
  });
});

req.on('error', (e) => {
  console.error(e);
});
req.end();
```

--------------------------------

### How to Use This API

Source: https://developers.lumos.com/reference/get_connected_info

Outlines the general steps for interacting with the Lumos Connector API, including discovering, learning about, configuring, and authenticating with connectors.

```APIDOC
## How to Use This API

1. Discover available connectors
2. Learn about a specific connector
3. Configure a connector
4. (optional) Authenticate with OAuth
5. Read data from the connected tenant
6. Write (update) data in the connected tenant
```

--------------------------------

### Provisioning Webhook Object Documentation

Source: https://developers.lumos.com/reference/update_appstore_permission_appstore_requestable_permissions__permission_id__patch-1

Details about the 'provisioning_webhook' object, including its properties.

```APIDOC
## Provisioning Webhook Object

### Description
Represents an inline webhook used for provisioning.

### Properties

- **id** (string) - The ID of this inline webhook.

### Type
object
```

--------------------------------

### GET /{connector_id}/info

Source: https://developers.lumos.com/reference/info

Retrieves comprehensive metadata about a specific connector, useful for initial setup, runtime discovery, schema validation, and health checks.

```APIDOC
## GET /{connector_id}/info

### Description
Retrieve information about a specific connector. This operation is typically used during initial connector setup and configuration, runtime capability discovery, schema validation and type checking, documentation generation, and connector health checks. The response includes comprehensive metadata that helps understand the connector's capabilities and requirements.

### Method
GET

### Endpoint
`/{connector_id}/info`

### Parameters
#### Path Parameters
- **connector_id** (string) - Required - The unique identifier of the connector.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **connector_id** (string) - The unique identifier of the connector.
- **name** (string) - The name of the connector.
- **version** (string) - The version of the connector.
- **description** (string) - A brief description of the connector's functionality.
- **capabilities** (array) - A list of capabilities supported by the connector.
- **schema** (object) - The schema definition for the connector's data.

#### Response Example
```json
{
  "connector_id": "example_connector_123",
  "name": "Example Connector",
  "version": "1.0.0",
  "description": "A sample connector for demonstration purposes.",
  "capabilities": [
    "read",
    "write",
    "stream"
  ],
  "schema": {
    "type": "object",
    "properties": {
      "id": {"type": "integer"},
      "name": {"type": "string"}
    }
  }
}
```
```

--------------------------------

### Pagination Example Flow (TypeScript)

Source: https://developers.lumos.com/reference/activate_account

Illustrates a typical pagination flow using Lumos connectors. It shows an initial POST request with a specified page size, the subsequent response containing data and a pagination token, and the next request using that token to retrieve more data.

```typescript
// First request
POST /connectors/pagerduty/list_accounts
{
  "page": { "size": 100 }
}

// Response
{
  "response": [...],
  "page": {
    "token": "eyJwYWdlIjogMn0=",
    "size": 100
  }
}

// Next request
POST /connectors/pagerduty/list_accounts
{
  "page": {
    "token": "eyJwYWdlIjogMn0=",
    "size": 100
  }
}
```

--------------------------------

### Get App API Request (Ruby)

Source: https://developers.lumos.com/reference/core-1

This snippet demonstrates how to get app details from the Lumos API using Ruby. It uses the 'net/http' library to perform the GET request and parse the JSON response.

```ruby
require 'net/http'
require 'uri'
require 'json'

app_id = 'your_app_id' # Replace with the actual app ID
uri = URI.parse("https://api.lumos.com/apps/#{app_id}")

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri.request_uri)
request['accept'] = 'application/json'

begin
  response = http.request(request)
  if response.is_a?(Net::HTTPSuccess)
    app_details = JSON.parse(response.body)
    puts "App Details: #{app_details}"
  else
    puts "Error fetching app details: #{response.code} #{response.message}"
  end
rescue StandardError => e
  puts "An error occurred: #{e.message}"
end
```

--------------------------------

### List Connector App IDs using POST Request

Source: https://developers.lumos.com/reference/list_connector_app_ids

An example of how to list all available connector app IDs using a POST request. The response includes a list of connector identifiers and pagination information, allowing for efficient handling of potentially large lists of connectors.

```json
{
  "response": [
    "pagerduty",
    "activedirectory",
    "netsuite"
  ],
  "raw_data": {},
  "page": {
    "token": "some_opaque_token",
    "size": 100
  }
}
```

--------------------------------

### Get Art API Request (Python)

Source: https://developers.lumos.com/reference/meta

This Python snippet shows how to get Lumos ASCII art using the 'requests' library. It performs a simple GET request to the API endpoint and prints the response. This is a straightforward way to interact with the Lumos API in Python.

```python
import requests

url = "https://api.lumos.com/art"
headers = {
    "accept": "text/plain"
}

try:
    response = requests.get(url, headers=headers)
    response.raise_for_status()  # Raise an exception for bad status codes
    print(response.text)
except requests.exceptions.RequestException as e:
    print(f"Error: {e}")
```

--------------------------------

### Get Lumos ASCII Art (OpenAPI)

Source: https://developers.lumos.com/reference/lumos-art-1

This OpenAPI definition describes the GET /art endpoint. It returns Lumos ASCII art as plain text, which can be used to confirm the API is operational. No specific client-side dependencies are required beyond making an HTTP GET request.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Lumos",
    "description": "\n    The Lumos API gives you the building blocks to administer and extend Lumos programmatically.\n    Our REST API provides a management interface for the AppStore and a read interface\n    for the Lumos Core.\n    Go to https://developers.lumos.com to see our complete documentation.\n",
    "version": "0.1.0"
  },
  "servers": [
    {
      "url": "https://api.lumos.com"
    }
  ],
  "paths": {
    "/art": {
      "get": {
        "tags": [
          "Meta"
        ],
        "summary": "Get Art",
        "description": "Return Lumos ASCII art. Can be used to verify the API is working.",
        "operationId": "Lumos Art.",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  }
}
```

--------------------------------

### POST /{connector_id}/create_account

Source: https://developers.lumos.com/reference/create_account

Creates a new user account in the third-party system with specified details and required entitlements. This operation handles the initial setup of the account, including assigning mandatory permissions and setting the initial status.

```APIDOC
## POST /{connector_id}/create_account

### Description
Create a new user account in the third-party system.

This operation creates a new user account with the specified details and required entitlements.
The account creation process may vary between integrations, but typically involves:
- Creating the base user account with provided personal information
- Assigning the required entitlements (permissions, licenses, etc.) that must be set during creation
- Setting up the initial account status

Note: Only entitlements that are required for account creation should be specified here.
Optional entitlements should be assigned after creation using the assign_entitlement operation.

### Method
POST

### Endpoint
`/{connector_id}/create_account`

### Parameters
#### Path Parameters
- **connector_id** (string) - Required - The unique identifier for the connector.

#### Query Parameters
None

#### Request Body
- **response** (object) - Required - The details for creating the account.
  - **status** (string) - Required - The initial status of the account. Must be one of: `ACTIVE`, `INACTIVE`, `SUSPENDED`, `DEPROVISIONED`, `PENDING`, `DELETED`.
  - **created** (object) - Required - Information about the created account.
    - **id** (string) - Required - The ID of the created account.

### Request Example
```json
{
  "response": {
    "status": "ACTIVE",
    "created": {
      "id": "user-12345"
    }
  }
}
```

### Response
#### Success Response (200)
- **response** (object) - Contains the status and details of the created account.
  - **id** (string) - The ID of the created account.
  - **status** (string) - The initial status of the account.

#### Response Example
```json
{
  "response": {
    "id": "user-12345",
    "status": "ACTIVE"
  }
}
```
```

--------------------------------

### Application Configuration

Source: https://developers.lumos.com/reference/createaccessrequest-1

This section details the properties available for configuring applications, including manual steps, time-based access, and provisioning groups.

```APIDOC
## Application Configuration Details

### Description
This endpoint provides details about the configuration properties for an application within the Lumos platform. It includes settings for manual provisioning, time-based access durations, and provisioning group assignments.

### Method
GET

### Endpoint
/websites/developers_lumos_reference/apps/{appId}/configuration

### Parameters
#### Path Parameters
- **appId** (string) - Required - The unique identifier of the application.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **manual_steps_needed** (boolean | null) - Whether manual steps are needed for provisioning.
- **manual_instructions** (string | null) - The manual instructions for provisioning.
- **time_based_access** (array of strings) - A list of available time durations for time-based access (e.g., "2 hours", "7 days", "Unlimited").
- **time_based_access_override** (boolean | null) - Indicates if time-based access is overridden.
- **provisioning_group** (object | null) - Information about the provisioning group.
  - **id** (string | null) - The ID of the provisioning group.
  - **app_id** (string | null) - The ID of the application associated with the provisioning group.

#### Response Example
```json
{
  "manual_steps_needed": false,
  "manual_instructions": null,
  "time_based_access": [
    "2 hours",
    "4 hours",
    "12 hours",
    "7 days",
    "14 days",
    "30 days",
    "90 days",
    "Unlimited"
  ],
  "time_based_access_override": false,
  "provisioning_group": {
    "id": "group-123",
    "app_id": "app-abc"
  }
}
```
```

--------------------------------

### Get App API Request (PHP)

Source: https://developers.lumos.com/reference/core-1

This snippet shows how to retrieve app information from the Lumos API using PHP. It utilizes cURL to send a GET request and decodes the JSON response.

```php
<?php

$appId = 'your_app_id'; // Replace with the actual app ID
$apiUrl = "https://api.lumos.com/apps/{$appId}";

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('accept: application/json'));

$response = curl_exec($ch);

if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
} else {
    $appDetails = json_decode($response, true);
    if ($appDetails === null && json_last_error() !== JSON_ERROR_NONE) {
        echo 'Error decoding JSON: ' . json_last_error_msg();
    } else {
        echo 'App Details: '; print_r($appDetails);
    }
}

c_l_close($ch);

?>
```

--------------------------------

### Get App API Request (Python)

Source: https://developers.lumos.com/reference/core-1

This snippet illustrates how to retrieve app information from the Lumos API using Python. It employs the 'requests' library to send a GET request and process the JSON response.

```python
import requests

app_id = 'your_app_id'  # Replace with the actual app ID
api_url = f'https://api.lumos.com/apps/{app_id}'

headers = {
    'accept': 'application/json'
}

try:
    response = requests.get(api_url, headers=headers)
    response.raise_for_status()  # Raise an exception for bad status codes
    app_details = response.json()
    print('App Details:', app_details)
except requests.exceptions.RequestException as e:
    print(f'Error fetching app details: {e}')
```

--------------------------------

### TypeScript Example of Pagination Flow

Source: https://developers.lumos.com/reference/get_account_entitlement_associations

Illustrates a typical pagination flow using TypeScript. It shows an initial POST request with a specified page size, the subsequent response containing data and a pagination token, and the next request including the token to fetch more data.

```typescript
// First request
POST /connectors/pagerduty/list_accounts
{
  "page": { "size": 100 }
}

// Response
{
  "response": [...],
  "page": {
    "token": "eyJwYWdlIjogMn0=",
    "size": 100
  }
}

// Next request
POST /connectors/pagerduty/list_accounts
{
  "page": {
    "token": "eyJwYWdlIjogMn0=",
    "size": 100
  }
}

```

--------------------------------

### Get App API Request (cURL)

Source: https://developers.lumos.com/reference/core-1

This snippet demonstrates how to make a GET request to the Lumos API to retrieve a specific app's details using cURL. It includes the endpoint URL and necessary headers.

```shell
curl --request GET \
     --url https://api.lumos.com/apps/app_id \
     --header 'accept: application/json'
```

--------------------------------

### Resource Type Example

Source: https://developers.lumos.com/reference/get_connected_info

Illustrates a resource type, specifying its unique identifier and human-readable label. This is used to categorize different types of resources that the connector can manage.

```json
{
  "type_id": "aws_account",
  "type_label": "AWS Account"
}
```

--------------------------------

### Entitlement Requirement Example

Source: https://developers.lumos.com/reference/get_connected_info

Demonstrates how to define specific requirements for a capability within an entitlement type. This allows for overriding base min/max values and specifying conditions like role or license requirements for actions such as account creation.

```json
{
  "...": "...",
  "requirements": {
    "StandardCapabilityName.CREATE_ACCOUNT": {
      "max": 0
    }
  }
}
```

--------------------------------

### Get App by ID

Source: https://developers.lumos.com/reference/core-1

Retrieves details of a specific application using its unique ID.

```APIDOC
## GET /apps/{app_id}

### Description
Get an app by id.

### Method
GET

### Endpoint
https://api.lumos.com/apps/{app_id}

### Parameters
#### Path Parameters
- **app_id** (string) - required - The ID of the app to retrieve.

#### Query Parameters
- **expand** (array) - optional - Fields to expand. Supported fields: custom_attributes.

### Request Example
```json
{
  "example": ""
}
```

### Response
#### Success Response (200)
- **id** (string) - required - The ID of this app.
- **app_class_id** (string) - required - The non-unique ID of the service associated with this requestable permission.
- **instance_id** (string) - required - The non-unique ID of the instance associated with this app.
- **user_friendly_label** (string) - required - The user-friendly label of this app.
- **status** (string) - enum, required - The status of this app. Possible values: 'DISCOVERED', 'IN_REVIEW', 'NEEDS_REVIEW', 'APPROVED', 'BLOCKLISTED', 'DEPRECATED'.
- **sources** (array of strings) - required - The sources of this app.
- **allow_multiple_permission_selection** (boolean) - required - Determines whether users can request multiple permissions at once.
- **logo_url** (string) - optional - The URL of the logo of this app.
- **website_url** (string) - optional - The URL of the website of this app.
- **request_instructions** (string) - optional - The request instructions.
- **description** (string) - optional - The user-facing description of the app.
- **category** (string) - optional - The category of the app, as shown in the AppStore.
- **links** (object) - required - A collection of URLs related to this application.
  - **self** (string) - required - The canonical API URL for retrieving this specific application.
  - **admin_url** (string) - required - A URL to access this application within the Lumos web UI.
- **custom_attributes** (object) - optional - Custom attributes configured on the app.

#### Response Example
```json
{
  "id": "string",
  "app_class_id": "string",
  "instance_id": "string",
  "user_friendly_label": "string",
  "status": "DISCOVERED",
  "sources": [
    "string"
  ],
  "allow_multiple_permission_selection": true,
  "logo_url": null,
  "website_url": null,
  "request_instructions": null,
  "description": null,
  "category": null,
  "links": {
    "self": "string",
    "admin_url": "string"
  },
  "custom_attributes": null
}
```

#### Error Response (422)
- **detail** (array of objects) - required - Details about the validation error.
  - **loc** (array) - required - Location of the error.
  - **msg** (string) - required - Error message.
  - **type** (string) - required - Error type.

#### Error Response Example
```json
{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
```
```

--------------------------------

### GET /art

Source: https://developers.lumos.com/reference/lumos-art-1

Retrieves Lumos ASCII art, which can be used to verify the API's operational status.

```APIDOC
## GET /art

### Description
Return Lumos ASCII art. Can be used to verify the API is working.

### Method
GET

### Endpoint
/art

### Parameters

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **art** (string) - The Lumos ASCII art.

#### Response Example
```text
    _    ____   ____ ______   ______   _____
   / |  / __ \ / __ `/ ___/  / ____/  / ___/
  /  | / /_/ // /_/ // /__   / __/    \__ \
 /_  |/ ____/ \__,_/ \___/  / /___   /____/
   |_/_/                                  
```
```

--------------------------------

### Lumos Connectors API Introduction

Source: https://developers.lumos.com/reference/get_account_entitlement_associations

Introduction to the Lumos Connector API, its purpose, core components, data model, and how to use it.

```APIDOC
## Lumos Connector API

### Introduction
The Lumos Connector API is a standardized interface for Identity and Access Management (IAM) operations across various third-party systems. It enables seamless integration between Lumos and external applications by providing a consistent set of operations called **capabilities**.

Each integration (referred to as a "connector") implements these capabilities to work with different third-party API providers, focusing primarily on:
- User access management
- License and cost tracking
- User activity monitoring

### Core Components

#### Connectors
A connector is a specialized library that acts as a bridge between Lumos and third-party applications. It handles:
- Translation of Lumos requests into app-specific API calls
- Conversion of app-specific responses into standardized Lumos formats
- Authentication and authorization flows
- Data format transformations

#### Capabilities
Capabilities are standardized operations that each connector can implement. They provide:
- Consistent interfaces across different connectors
- Predictable behavior patterns
- Standardized error handling
- Unified data structures

### Data Model

#### Accounts
Accounts represent individual users or service accounts within a system. They serve as the primary entities for access management and support lifecycle operations such as creation, activation, deactivation, and deletion. Accounts can be associated with multiple entitlements and are typically identified by a unique account ID within the system.

#### Entitlements
Entitlements represent a permission or capability that can be granted to user accounts, such as a license or access level. They define specific permissions, access rights, or memberships and are always associated with a resource, which may be global or specific. Entitlements are categorized by `entitlement_type` (e.g., licenses, roles, permissions, group memberships) and have defined constraints for minimum and maximum assignments. The naming of entitlements may vary, such as using "membership" for group associations.

#### Resources
Resources represent entities within an application that can be accessed or managed. They are identified by a unique `resource_type` within each app and include a global resource (represented by an empty string) for top-level entities. Resources can represent hierarchical structures, such as Workspaces containing Users and Groups, and serve as the context for entitlement assignments. The usage of Resource IDs depends on the specific hierarchy, with an empty string for global resources and specific IDs (e.g., Workspace ID) for nested resources.

#### Associations
Associations define relationships from accounts to entitlements (which are resource specific). They follow a hierarchical structure of Account -> Entitlement -> Resource, with no direct account-to-resource associations allowed. Associations enable flexible access control models.

Note: The specific structure and use of resources and entitlements may vary depending on the integrated system's architecture and access model.

### How to Use This API

1. Discover available connectors
2. Learn about a specific connector
3. Configure a connector
4. (optional) Authenticate with OAuth
5. Read data from the connected tenant
6. Write (update) data in the connected tenant
```

--------------------------------

### Get Art API Request (PHP)

Source: https://developers.lumos.com/reference/meta

This PHP snippet demonstrates fetching Lumos ASCII art using cURL. It makes a GET request to the Lumos API endpoint and retrieves the response body. This is a common method for server-side API interactions in PHP.

```php
<?php

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.lumos.com/art');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'accept: text/plain'
]);

$response = curl_exec($ch);

if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
} else {
    echo $response;
}

curl_close($ch);
?>
```

--------------------------------

### User Account Creation

Source: https://developers.lumos.com/reference/create_account

This section details the process of creating a new user account. It includes information on the required request payload, authentication credentials, and entitlement configurations necessary for successful account creation.

```APIDOC
## POST /api/users

### Description
Creates a new user account with specified entitlements and authentication credentials.

### Method
POST

### Endpoint
/api/users

### Parameters
#### Request Body
- **request** (object) - Required - The main request payload containing user details and entitlements.
  - **entitlements** (array) - Required - List of required entitlements for the new account.
    - **integration_specific_resource_id** (string) - Optional - The unique identifier for the resource in the third-party system.
    - **entitlement_type** (string) - Required - The type of entitlement.
    - **integration_specific_id** (string) - Required - The unique identifier for the specific entitlement in the third-party system.
- **include_raw_data** (boolean) - Optional - Whether to include raw data in the response.

### Request Example
```json
{
  "request": {
    "entitlements": [
      {
        "entitlement_type": "role",
        "integration_specific_id": "admin_role_id",
        "integration_specific_resource_id": "workspace_123"
      }
    ]
  },
  "include_raw_data": false
}
```

### Response
#### Success Response (201)
- **account_id** (string) - The unique identifier for the newly created account.
- **status** (string) - The status of the account creation.

#### Response Example
```json
{
  "account_id": "acc_abc123",
  "status": "created"
}
```
```

--------------------------------

### Lumos Connectors API Introduction

Source: https://developers.lumos.com/reference/deactivate_account

Introduction to the Lumos Connector API, its purpose, and core components.

```APIDOC
## Lumos Connectors API

### Description
The Lumos Connector API is a standardized interface for Identity and Access Management (IAM) operations across various third-party systems. It enables seamless integration between Lumos and external applications by providing a consistent set of operations called **capabilities**.

Each integration (referred to as a "connector") implements these capabilities to work with different third-party API providers, focusing primarily on:
- User access management
- License and cost tracking
- User activity monitoring

### Core Components

#### Connectors
A connector is a specialized library that acts as a bridge between Lumos and third-party applications. It handles:
- Translation of Lumos requests into app-specific API calls
- Conversion of app-specific responses into standardized Lumos formats
- Authentication and authorization flows
- Data format transformations

#### Capabilities
Capabilities are standardized operations that each connector can implement. They provide:
- Consistent interfaces across different connectors
- Predictable behavior patterns
- Standardized error handling
- Unified data structures
```

--------------------------------

### Get User Data with Pagination

Source: https://developers.lumos.com/reference/downgrade_license

Retrieves a paginated list of user data. You can control the page size and use a token for subsequent requests to get the next page of results.

```APIDOC
## GET /api/users

### Description
Retrieves a paginated list of user data. Allows for filtering and sorting of results.

### Method
GET

### Endpoint
/api/users

### Parameters
#### Query Parameters
- **page.size** (integer) - Optional - Number of items to return per page. Defaults to 20.
- **page.token** (string) - Optional - Opaque token representing the next page of results. Include this token in subsequent requests to retrieve the next page.
- **include_raw_data** (boolean) - Optional - Whether to include raw data in the response.
- **settings** (object) - Optional - Connector-specific settings for the request.

### Request Example
```json
{
  "page": {
    "size": 50,
    "token": "nextPageToken123"
  },
  "include_raw_data": true,
  "settings": {
    "some_setting": "some_value"
  }
}
```

### Response
#### Success Response (200)
- **users** (array) - A list of user objects.
- **page** (object) - Pagination information.
  - **token** (string) - Opaque token representing the next page of results.
  - **size** (integer) - Number of items returned per page.

#### Response Example
```json
{
  "users": [
    {
      "account_id": "user456def",
      "name": "Jane Doe",
      "email": "jane.doe@example.com"
    }
  ],
  "page": {
    "token": "nextPageToken456",
    "size": 50
  }
}
```
```

--------------------------------

### Application Provisioning Configuration

Source: https://developers.lumos.com/reference/create_appstore_requestable_permission_appstore_requestable_permissions_post-1

This endpoint allows for the configuration of application provisioning, including time-based access options and webhook settings.

```APIDOC
## PUT /websites/developers_lumos_reference/apps/{app_id}/provisioning

### Description
Updates the provisioning configuration for a specific application. This includes setting time-based access options, overriding time-based access, and associating a provisioning group or webhook.

### Method
PUT

### Endpoint
`/websites/developers_lumos_reference/apps/{app_id}/provisioning`

### Parameters
#### Path Parameters
- **app_id** (string) - Required - The unique identifier of the application.

#### Request Body
- **time_based_access** (array[string]) - Optional - A list of available durations for time-based access (e.g., "4 hours", "12 hours", "7 days", "Unlimited").
- **time_based_access_override** (boolean | null) - Optional - Indicates if time-based access is overridden.
- **provisioning_group** (object | null) - Optional - The provisioning group associated with this configuration. It can include `id`, `app_id`, and `integration_specific_id`.
- **provisioning_webhook** (object | null) - Optional - The provisioning webhook associated with this configuration. It must include an `id`.

### Request Example
```json
{
  "time_based_access": [
    "4 hours",
    "12 hours",
    "7 days",
    "Unlimited"
  ],
  "time_based_access_override": true,
  "provisioning_group": {
    "id": "group-123",
    "app_id": "app-abc",
    "integration_specific_id": "int-xyz"
  },
  "provisioning_webhook": {
    "id": "webhook-456"
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the provisioning configuration was updated successfully.

#### Response Example
```json
{
  "message": "Provisioning configuration updated successfully."
}
```
```

--------------------------------

### POST /appstore/pre_approval_rules

Source: https://developers.lumos.com/reference/create_pre_approval_rule_appstore_pre_approval_rules_post-1

Create a pre-approval rule attached to an App in the AppStore.

```APIDOC
## POST /appstore/pre_approval_rules

### Description
Create a pre-approval rule attached to an App in the AppStore.

### Method
POST

### Endpoint
https://api.lumos.com/appstore/pre_approval_rules

### Parameters
#### Request Body
- **justification** (string) - Required - The justification of this preapproval rule.
- **time_based_access** (array) - Optional - Preapproval rule time access length. Possible values: "2 hours", "4 hours", "12 hours", "7 days", "14 days", "30 days", "90 days", "Unlimited".
- **app_id** (string) - Required - The ID of the app associated with this pre-approval rule.
- **preapproved_groups** (array) - Optional - The preapproved groups of this preapproval rule. Defaults to [].
  - **id** (string or null) - Optional - The ID of this group.
  - **app_id** (string or null) - Optional - The ID of the app that sources this group.
  - **integration_specific_id** (string or null) - Optional - The ID of this group, specific to the integration.
- **preapproved_permissions** (array) - Optional - The preapproved permissions of this preapproval rule.
  - **id** (string) - Required - The ID of this requestable permission.

### Request Example
```json
{
  "justification": "User needs temporary access for testing purposes.",
  "time_based_access": ["7 days"],
  "app_id": "app_123",
  "preapproved_groups": [
    {
      "id": "group_abc",
      "app_id": "app_123",
      "integration_specific_id": "int_group_xyz"
    }
  ],
  "preapproved_permissions": [
    {
      "id": "perm_def"
    }
  ]
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the created pre-approval rule.
- **justification** (string) - The justification for the rule.
- **time_based_access** (array) - The time-based access durations.
- **app_id** (string) - The ID of the associated app.
- **preapproved_groups** (array) - The preapproved groups.
- **preapproved_permissions** (array) - The preapproved permissions.

#### Response Example
```json
{
  "id": "rule_456",
  "justification": "User needs temporary access for testing purposes.",
  "time_based_access": [
    "7 days"
  ],
  "app_id": "app_123",
  "preapproved_groups": [
    {
      "id": "group_abc",
      "app_id": "app_123",
      "integration_specific_id": "int_group_xyz"
    }
  ],
  "preapproved_permissions": [
    {
      "id": "perm_def"
    }
  ]
}
```
```

--------------------------------

### Entitlement Type Example

Source: https://developers.lumos.com/reference/get_connected_info

Provides an example of an entitlement type, detailing its ID, label, and associated requirements. This structure defines the characteristics of an entitlement, including minimum and maximum values and specific capability requirements.

```json
{
  "type_id": "license",
  "type_label": "License",
  "resource_type_id": "",
  "min": 1,
  "max": 1,
  "requirements": {
    "create_account": {
      "max": 0
    }
  }
}
```

--------------------------------

### Activate Account Ruby Request

Source: https://developers.lumos.com/reference/write-capabilities

Example Ruby code to activate or reactivate a user account using the 'Net::HTTP' library. It shows how to construct the POST request with appropriate headers and JSON body.

```ruby
require 'uri'
require 'net/http'
require 'json'

url = URI('https://example.com/connector_id/activate_account')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request['accept'] = 'application/json'
request['content-type'] = 'application/json'

request.body = JSON.dump({
  auth: {
    service_account: {
      service_type: 'google_cloud'
    }
  }
})

response = http.request(request)
puts response.read_body
```

--------------------------------

### Get App API Request (Node.js)

Source: https://developers.lumos.com/reference/core-1

This snippet shows how to fetch app details from the Lumos API using Node.js. It utilizes the 'axios' library for making HTTP requests and handles the response.

```javascript
const axios = require('axios');

const appId = 'your_app_id'; // Replace with the actual app ID
const apiUrl = `https://api.lumos.com/apps/${appId}`;

axios.get(apiUrl, {
  headers: {
    'accept': 'application/json'
  }
})
  .then(response => {
    console.log('App Details:', response.data);
  })
  .catch(error => {
    console.error('Error fetching app details:', error);
  });
```

--------------------------------

### POST /websites/developers_lumos_reference/apps

Source: https://developers.lumos.com/reference/getapp-1

Creates a new application with custom attributes within the Lumos Developers reference project.

```APIDOC
## POST /websites/developers_lumos_reference/apps

### Description
Creates a new application with custom attributes within the Lumos Developers reference project. This endpoint allows for the creation of new applications, specifying various attributes and configurations.

### Method
POST

### Endpoint
/websites/developers_lumos_reference/apps

### Parameters
#### Request Body
- **name** (string) - Required - The name of the application.
- **description** (string) - Optional - A description for the application.
- **custom_attributes** (array) - Optional - A list of custom attributes to associate with the application. Each attribute should be an object with a `name` and `value` field.

### Request Example
```json
{
  "name": "MyNewApp",
  "description": "This is a test application.",
  "custom_attributes": [
    {
      "name": "version",
      "value": "1.0.0"
    },
    {
      "name": "environment",
      "value": "production"
    }
  ]
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created application.
- **name** (string) - The name of the application.
- **description** (string) - The description of the application.
- **custom_attributes** (array) - A list of custom attributes associated with the application.
- **allow_multiple_permission_selection** (boolean) - Indicates if multiple permission selections are allowed.
- **links** (object) - Links related to the application.

#### Response Example
```json
{
  "id": "app-12345",
  "name": "MyNewApp",
  "description": "This is a test application.",
  "custom_attributes": [
    {
      "name": "version",
      "value": "1.0.0"
    },
    {
      "name": "environment",
      "value": "production"
    }
  ],
  "allow_multiple_permission_selection": true,
  "links": {
    "self": "/apps/app-12345"
  }
}
```

#### Error Response (422)
- **detail** (array) - A list of validation errors.
  - **loc** (array) - The location of the error (e.g., field name).
  - **msg** (string) - The error message.
  - **type** (string) - The type of error.

#### Error Response Example
```json
{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```
```

--------------------------------

### GET /websites/developers_lumos_reference/accounts

Source: https://developers.lumos.com/reference/getuseraccounts

Retrieves a list of accounts associated with the current user.

```APIDOC
## GET /websites/developers_lumos_reference/accounts

### Description
Get a list of Accounts for this user.

### Method
GET

### Endpoint
/websites/developers_lumos_reference/accounts

### Parameters
#### Query Parameters
(No query parameters defined)

#### Request Body
(No request body defined)

### Request Example
(No request example provided)

### Response
#### Success Response (200)
- **accounts** (array) - A list of user accounts.
  - **accountId** (string) - The unique identifier for the account.
  - **accountName** (string) - The name of the account.

#### Response Example
```json
{
  "accounts": [
    {
      "accountId": "acc_12345",
      "accountName": "Example Account 1"
    },
    {
      "accountId": "acc_67890",
      "accountName": "Example Account 2"
    }
  ]
}
```
```

--------------------------------

### Create Account API

Source: https://developers.lumos.com/reference/create_account

This endpoint allows for the creation of a new user account. It returns details about the created account, including its status and a legacy flag.

```APIDOC
## POST /api/accounts

### Description
Creates a new user account and returns details about the account creation.

### Method
POST

### Endpoint
/api/accounts

### Request Body
- **account_details** (object) - Required - Details required for account creation.
  - **name** (string) - Required - The name of the account.
  - **email** (string) - Required - The email address for the account.
  - **password** (string) - Required - The password for the account.

### Request Example
```json
{
  "account_details": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "password": "securepassword123"
  }
}
```

### Response
#### Success Response (200)
- **created_account** (object) - Details about the created account.
  - **account_id** (string) - The unique identifier for the created account.
  - **status** (string) - The current status of the created account (e.g., "active", "pending").
  - **created** (boolean) - Legacy flag indicating successful account creation (deprecated).
- **page** (object) - Pagination parameters for requests and responses.
  - **token** (string) - Opaque token representing the next page of results.
  - **size** (integer) - Number of items to return per page.

#### Response Example
```json
{
  "created_account": {
    "account_id": "acc_12345abc",
    "status": "active",
    "created": true
  },
  "page": {
    "token": "next_page_token_xyz",
    "size": 20
  }
}
```

#### Error Response (4xx/5xx)
- **is_error** (boolean) - Always true for error responses.
- **error** (object) - Contains details about the error.
  - **message** (string) - A human-readable string explaining what went wrong.
  - **status_code** (integer) - An HTTP status code (if applicable).
  - **app_error_code** (string) - An application-specific error code.
  - **error_code** (string) - A general error code (e.g., "not_found", "unauthorized").

#### Error Response Example
```json
{
  "is_error": true,
  "error": {
    "message": "Authentication credentials didn't work",
    "status_code": 401,
    "app_error_code": "my_integration.token_expired",
    "error_code": "unauthorized"
  }
}
```
```