---
title: MokN
slug: connectors/mokn
createdAt: 2026-11-16T09:02:40.782Z
---

MokN is a deception technology platform that deploys decoy login portals (baits) and agents to detect and analyze credential-based attacks in real time.

MokN is a deception-based security platform that deploys realistic login portals ("baits") and integrates with identity providers to detect and analyze credential theft attempts. This connector enables Swimlane Turbine users to automate the deployment, management, and monitoring of MokN baits and agents, retrieve detailed attack analytics, and orchestrate rapid responses to identity-based threats. By integrating MokN with Swimlane Turbine, security teams can proactively detect credential harvesting, gain deep visibility into attacker behavior, and streamline identity protection workflows—all without writing code.

### Limitations

- Actions that change baits or agents require an API key with write permissions. A key without them returns `403 Forbidden` with the message `Not enough permission to perform this action.`
- Deleting a bait is asynchronous. Use Retrieve Bait Creation Status or Retrieve a Bait to follow its progress.
- Dashboard actions accept months in `YYYY/MM` format only.

### Supported Versions

This MokN connector uses the MokN API version 1 (`/api/v1`).

## Configuration

### Prerequisites

To use the MokN connector, ensure you have the following prerequisites:

- API Key Authentication:
  - URL: The base endpoint for your MokN instance's API.
  - API Key: A valid MokN API key for authenticating requests, sent in the X-MOKN-API-KEY header.
- HTTP Bearer Token Authentication:
  - URL: The base endpoint for your MokN instance's API.
  - API Token: A valid MokN API token to be used as a bearer token for authentication.

## Authentication Methods

### API Key Authentication:

- URL: The URL of your MokN tenant.
- API Key: A MokN API key with the permissions needed by the actions you run.

### HTTP Bearer Authentication:

- URL: The URL of your MokN tenant.
- API Token: A MokN API token with the permissions needed by the actions you run.

## Capabilities

This MokN connector provides the following capabilities:

- Bulk Update Baits
- Create a New Agent
- Delete a Bait
- Delete an Agent
- Export Agent Configuration
- List All Agents
- List All Baits
- List Attacker Aggregates
- List Available Skins
- List Certificate Authorities
- Retrieve a Bait
- Retrieve Agent Details
- Retrieve Agents Queue
- Retrieve Average Time Between Two Attempts
- Retrieve Bait Creation Status
  *... and so on*

### Bait Management

### Bulk Update Baits

Updates several baits in a single request, for example whether the data collected by each bait is kept. Provide a list of objects, each with the bait `id` and the fields to change.

### Delete a Bait

Deletes a bait by its ID. The deletion is processed asynchronously.

### List All Baits

Lists all baits with their hosting, certificate, status and alerting configuration. Set `include_deleted` to include deleted baits.

### List Available Skins

Lists the skins (login portal templates, such as a Fortinet VPN portal) available for creating baits.

### List Certificate Authorities

Lists the certificate authorities available to issue TLS certificates for baits.

### Retrieve a Bait

Retrieves the details of a bait by its ID.

### Retrieve Bait Creation Status

Retrieves the creation status of the baits currently being deployed.

### Retrieve Short List of Baits

Retrieves the ID and name of every bait. Set `include_deleted` to include deleted baits.

### Agent Management

Agents connect MokN to your identity provider to check whether captured credentials are valid.

### Create a New Agent

Creates an agent connected to an identity provider. `name` and `agent_type` are required. The other fields depend on the agent type (see [Agent Types](docId\:D62jNecTT1NGQeDIDe37k)).

### Delete an Agent

Deletes an agent by its ID.

### Export Agent Configuration

Exports the configuration archive (zip) used to install or update an agent. `export` must be `true`. Set `new` to `true` to generate a configuration for a new installation instead of an update of the existing one.

### List All Agents

Lists all agents with their status and the latest available agent versions.

### Retrieve Agent Details

Retrieves the details of an agent by its ID.

### Retrieve Agents Queue

Retrieves the login attempts waiting to be checked by agents, being checked, and already checked. Filter by `bait_id`, and use `nb_checked` to limit the number of checked attempts returned.

### Retrieve Short List of Agents

Retrieves the ID and name of every agent.

### Update an Agent

Updates the configuration of an existing agent. Only the fields you provide are changed.

### Attack Intelligence and Dashboards

The dashboard actions accept the following optional parameters:

- `id`: Restrict the results to these bait IDs. When omitted, all baits are returned.
- `start_month` and `end_month`: The period to report on, in `YYYY/MM` format.
- `detail`: Whether to include detailed results for each bait.
- `limit`: The maximum number of entries returned for each bait (Top Passwords and Top Usernames only).

### List Attacker Aggregates

Lists attacker aggregates computed from the login attempts captured by baits. Supports `page`, `page_size`, `date_from` and `date_to`.

### Retrieve Average Time Between Two Attempts

Retrieves the average time between two login attempts, for all baits and for each bait.

### Retrieve Monthly History

Retrieves the monthly history of login attempts, for all baits and for each bait.

### Retrieve Monthly History Dates

Retrieves the first and last months for which a monthly history is available.

### Retrieve Targeting Countries Data

Retrieves the top countries from which login attempts originate.

### Retrieve Threat Level

Retrieves the threat level, for all baits and for each bait.

### Retrieve Top Passwords

Retrieves the passwords most used in login attempts.

### Retrieve Top Usernames

Retrieves the usernames most targeted in login attempts.

### Retrieve Unique Targeted Accounts Data

Retrieves the number of unique accounts targeted in login attempts.

## Tasks Setup

### Agent Types

The `agent_type` input of Create a New Agent and Update an Agent accepts the following values:

| Value         | Identity provider  | Type-specific fields                                                                                                     |
| ------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `AgentAD`     | Active Directory   | `domain`, `domain_controller`, `search_base`, `lockout_threshold` (0 to 9999), `tls_ssl`, `tls_ssl_verify`, `attributes` |
| `AgentEntra`  | Microsoft Entra ID | `tenant_id`, `client_id`, `client_secret` (the secret value, not the secret ID), `domains`, `is_fast_setup`              |
| `AgentOkta`   | Okta               | `domain`, `ssws_token` (Okta API token), `domains`                                                                       |
| `AgentGoogle` | Google Workspace   | `domains`, `attributes`, `tls_client_certificate`, `tls_client_private_key` (PEM-encoded)                                |
| `AgentXSOAR`  | Cortex XSOAR       | None                                                                                                                     |
| `AgentCustom` | Custom             | None                                                                                                                     |

All agent types accept `recipients`, the email addresses notified about the agent. To monitor an agent with a known valid account, set `valid_username` and `valid_password` together.

## Additional Documentation

- [MokN Connector Documentation](https://docs.swimlane.com/connectors/mokn)
- [MokN Authentication Guide](https://docs.swimlane.com/authentication-guides/mokn)
- [MokN (Vendor)](https://www.mokn.io)

# Configurations

## MokN API Key Authentication

Authenticates using a MokN API key sent in the X-MOKN-API-KEY header.

### Configuration Parameters

| **Parameter**  | **Description**                                                   | **Type** | **Required** |
| -------------- | ----------------------------------------------------------------- | -------- | ------------ |
| url            | The URL of your MokN tenant, for example https\://.mokn.io.<br /> | string   | Required     |
| X-MOKN-API-KEY | The MokN API key generated in the MokN console.                   | string   | Required     |
| verify\_ssl    | Verify SSL certificate                                            | boolean  | Optional     |
| http\_proxy    | A proxy to route requests through.                                | string   | Optional     |

## MokN HTTP Bearer Authentication

Authenticates using a MokN API token sent as a bearer token.

### Configuration Parameters

| **Parameter** | **Description**                                                   | **Type** | **Required** |
| ------------- | ----------------------------------------------------------------- | -------- | ------------ |
| url           | The URL of your MokN tenant, for example https\://.mokn.io.<br /> | string   | Required     |
| token         | The MokN API token generated in the MokN console.                 | string   | Required     |
| verify\_ssl   | Verify SSL certificate                                            | boolean  | Optional     |
| http\_proxy   | A proxy to route requests through.                                | string   | Optional     |

# Actions

## Bulk Update Baits

Update multiple MokN baits in a single request, including options such as retaining or modifying bait data.

### Endpoint

- **URL:** `/api/v1/baits/baits`
- **Method:** `PATCH`

### Output

| **Parameter** | **Type** | **Description**                                 |
| ------------- | -------- | ----------------------------------------------- |
| `status_code` | number   | The HTTP status code of the response.           |
| `reason`      | string   | The HTTP reason phrase of the response.         |
| `status`      | string   | The status of the request (success or error).   |
| `message`     | string   | A message describing the result of the request. |
| `data`        | string   | The updated baits.                              |

### Output Example

`{"status":"active","message":"string","data":"string"}`

## Create a New Agent

Create a new MokN agent linked to an identity provider such as Active Directory, Entra ID, Okta, Google, XSOAR, or Custom by specifying the agent name and type.

### Endpoint

- **URL:** `/api/v1/baits/agents`
- **Method:** `POST`

### Input

| **Argument Name**        | **Type** | **Required** | **Description**                                                                               |
| ------------------------ | -------- | ------------ | --------------------------------------------------------------------------------------------- |
| `name`                   | string   | Optional     | The display name of the agent.                                                                |
| `agent_type`             | string   | Optional     | The identity provider type the agent connects to.                                             |
| `recipients`             | array    | Optional     | The email addresses notified about this agent.                                                |
| `valid_username`         | string   | Optional     | A valid account username used to monitor the agent. Must be set together with Valid Password. |
| `valid_password`         | string   | Optional     | The password of the monitoring account.                                                       |
| `domain`                 | string   | Optional     | The domain of the identity provider (Active Directory and Okta agents).                       |
| `domains`                | array    | Optional     | The email domains handled by the agent (Entra ID, Okta and Google agents).                    |
| `domain_controller`      | string   | Optional     | The host of the domain controller (Active Directory agents).                                  |
| `search_base`            | string   | Optional     | The LDAP search scope (Active Directory agents).                                              |
| `lockout_threshold`      | integer  | Optional     | The account lockout threshold, between 0 and 9999 (Active Directory agents).                  |
| `tls_ssl`                | boolean  | Optional     | Whether LDAP connections use TLS/SSL (Active Directory agents).                               |
| `tls_ssl_verify`         | boolean  | Optional     | Whether the LDAP TLS certificate is verified (Active Directory agents).                       |
| `attributes`             | array    | Optional     | The directory attributes used to match usernames (Active Directory and Google agents).        |
| `tenant_id`              | string   | Optional     | The Microsoft Entra ID tenant ID (Entra ID agents).                                           |
| `client_id`              | string   | Optional     | The Microsoft Entra ID application client ID (Entra ID agents).                               |
| `client_secret`          | string   | Optional     | The Microsoft Entra ID application client secret value, not the secret ID (Entra ID agents).  |
| `is_fast_setup`          | boolean  | Optional     | Whether the Entra ID fast setup is used (Entra ID agents).                                    |
| `ssws_token`             | string   | Optional     | The Okta API token (Okta agents).                                                             |
| `tls_client_certificate` | string   | Optional     | The PEM-encoded TLS client certificate (Google agents).                                       |
| `tls_client_private_key` | string   | Optional     | The PEM-encoded TLS client private key (Google agents).                                       |

### Input Example

`{"json_body":{"name":"Corporate AD agent","agent_type":"AgentAD","recipients":["soc@example.com"],"domain":"corp.example.com","domain_controller":"dc01.corp.example.com","search_base":"DC=corp,DC=example,DC=com","lockout_threshold":0,"tls_ssl":true,"tls_ssl_verify":false,"attributes":["mail","samaccountname","userprincipalname"]}}`

### Output

| **Parameter**        | **Type** | **Description**                                                        |
| -------------------- | -------- | ---------------------------------------------------------------------- |
| `status_code`        | number   | The HTTP status code of the response.                                  |
| `reason`             | string   | The HTTP reason phrase of the response.                                |
| `status`             | string   | The status of the request (success or error).                          |
| `message`            | string   | A message describing the result of the request.                        |
| `data`               | object   | The agent details.                                                     |
| `data.id`            | integer  | The unique identifier of the agent.                                    |
| `data.name`          | string   | The display name of the agent.                                         |
| `data.agent_type`    | string   | The identity provider type the agent connects to.                      |
| `data.is_alive`      | boolean  | Whether the agent is currently alive and reporting to MokN.            |
| `data.is_reachable`  | boolean  | Whether the identity provider is reachable by the agent.               |
| `data.last_seen`     | string   | The date and time the agent last contacted MokN.                       |
| `data.date_created`  | string   | The date and time the agent was created.                               |
| `data.server`        | string   | The server the agent is installed on.                                  |
| `data.version`       | string   | The installed agent version.                                           |
| `data.recipients`    | array    | The email addresses notified about this agent.                         |
| `data.last_check_at` | string   | The date and time of the last credential check performed by the agent. |
| `data.today_checks`  | integer  | The number of credential checks performed today.                       |
| `data.total_checks`  | integer  | The total number of credential checks performed by the agent.          |
| `data.domain`        | string   | The domain the agent is attached to (Active Directory / Okta).         |
| `data.domains`       | array    | The email domains handled by the agent.                                |

### Output Example

`{"status":"active","message":"string","data":{"id":123,"name":"Example Name","agent_type":"string","is_alive":true,"is_reachable":true,"last_seen":"string","date_created":"string","server":"string","version":"string","recipients":["string"],"last_check_at":"string","today_checks":123,"total_checks":123,"domain":"string","domains":["string"]}}`

## Delete a Bait

Remove a MokN bait asynchronously using its unique bait ID.

### Endpoint

- **URL:** `/api/v1/baits/baits/{{bait_id}}`
- **Method:** `DELETE`

### Input

| **Argument Name**         | **Type** | **Required** | **Description**                    |
| ------------------------- | -------- | ------------ | ---------------------------------- |
| `path_parameters.bait_id` | integer  | Required     | The unique identifier of the bait. |

### Input Example

`{"path_parameters":{"bait_id":101}}`

### Output

| **Parameter** | **Type** | **Description**                                 |
| ------------- | -------- | ----------------------------------------------- |
| `status_code` | number   | The HTTP status code of the response.           |
| `reason`      | string   | The HTTP reason phrase of the response.         |
| `status`      | string   | The status of the request (success or error).   |
| `message`     | string   | A message describing the result of the request. |
| `data`        | object   | The result of the deletion.                     |

### Output Example

`{"status":"active","message":"string","data":{}}`

## Delete an Agent

Remove a MokN agent from your environment using the specified agent ID.

### Endpoint

- **URL:** `/api/v1/baits/agents/{{agent_id}}`
- **Method:** `DELETE`

### Input

| **Argument Name**          | **Type** | **Required** | **Description**                     |
| -------------------------- | -------- | ------------ | ----------------------------------- |
| `path_parameters.agent_id` | integer  | Required     | The unique identifier of the agent. |

### Input Example

`{"path_parameters":{"agent_id":12}}`

### Output

| **Parameter** | **Type** | **Description**                                 |
| ------------- | -------- | ----------------------------------------------- |
| `status_code` | number   | The HTTP status code of the response.           |
| `reason`      | string   | The HTTP reason phrase of the response.         |
| `status`      | string   | The status of the request (success or error).   |
| `message`     | string   | A message describing the result of the request. |
| `data`        | object   | The result of the deletion.                     |

### Output Example

`{"status":"active","message":"string","data":{}}`

## Export Agent Configuration

Export the configuration archive (ZIP) for a MokN agent using the agent ID and export parameters to facilitate installation or updates.

### Endpoint

- **URL:** `/api/v1/baits/agents/{{agent_id}}`
- **Method:** `GET`

### Input

| **Argument Name**          | **Type** | **Required** | **Description**                                                                           |
| -------------------------- | -------- | ------------ | ----------------------------------------------------------------------------------------- |
| `path_parameters.agent_id` | integer  | Required     | The unique identifier of the agent.                                                       |
| `parameters.export`        | boolean  | Required     | Must be true to export the agent configuration archive.                                   |
| `parameters.new`           | boolean  | Optional     | Generate a new configuration (new installation) instead of an update of the existing one. |

### Input Example

`{"parameters":{"export":true,"new":false},"path_parameters":{"agent_id":12}}`

### Output

| **Parameter**    | **Type** | **Description**                           |
| ---------------- | -------- | ----------------------------------------- |
| `status_code`    | number   | The HTTP status code of the response.     |
| `reason`         | string   | The HTTP reason phrase of the response.   |
| `file`           | object   | The exported agent configuration archive. |
| `file.file`      | string   | Output field: file.file                   |
| `file.file_name` | string   | Name of the resource                      |

### Output Example

`{"file":{"file":"string","file_name":"Example Name"}}`

## List All Agents

Retrieve a list of all MokN agents, including their current status and the latest available agent versions.

### Endpoint

- **URL:** `/api/v1/baits/agents`
- **Method:** `GET`

### Input

| **Argument Name**     | **Type** | **Required** | **Description**                                |
| --------------------- | -------- | ------------ | ---------------------------------------------- |
| `parameters.can_sync` | boolean  | Optional     | Return only agents that can synchronize users. |

### Input Example

`{"parameters":{"can_sync":true}}`

### Output

| **Parameter**               | **Type** | **Description**                                                        |
| --------------------------- | -------- | ---------------------------------------------------------------------- |
| `status_code`               | number   | The HTTP status code of the response.                                  |
| `reason`                    | string   | The HTTP reason phrase of the response.                                |
| `status`                    | string   | The status of the request (success or error).                          |
| `message`                   | string   | A message describing the result of the request.                        |
| `data`                      | object   | The agents and the latest available agent versions.                    |
| `data.agents`               | array    | The list of agents.                                                    |
| `data.agents.id`            | integer  | The unique identifier of the agent.                                    |
| `data.agents.name`          | string   | The display name of the agent.                                         |
| `data.agents.agent_type`    | string   | The identity provider type the agent connects to.                      |
| `data.agents.is_alive`      | boolean  | Whether the agent is currently alive and reporting to MokN.            |
| `data.agents.is_reachable`  | boolean  | Whether the identity provider is reachable by the agent.               |
| `data.agents.last_seen`     | string   | The date and time the agent last contacted MokN.                       |
| `data.agents.date_created`  | string   | The date and time the agent was created.                               |
| `data.agents.server`        | string   | The server the agent is installed on.                                  |
| `data.agents.version`       | string   | The installed agent version.                                           |
| `data.agents.recipients`    | array    | The email addresses notified about this agent.                         |
| `data.agents.last_check_at` | string   | The date and time of the last credential check performed by the agent. |
| `data.agents.today_checks`  | integer  | The number of credential checks performed today.                       |
| `data.agents.total_checks`  | integer  | The total number of credential checks performed by the agent.          |
| `data.agents.domain`        | string   | The domain the agent is attached to (Active Directory / Okta).         |
| `data.agents.domains`       | array    | The email domains handled by the agent.                                |
| `data.last_version`         | object   | The latest available version for each installable agent type.          |
| `data.last_version.ad`      | string   | The latest Active Directory agent version.                             |
| `data.last_version.xsoar`   | string   | The latest XSOAR agent version.                                        |

### Output Example

`{"status":"active","message":"string","data":{"agents":[{}],"last_version":{"ad":"string","xsoar":"string"}}}`

## List All Baits

Retrieve all MokN baits along with their hosting details, certificate information, and alerting configuration.

### Endpoint

- **URL:** `/api/v1/baits/baits`
- **Method:** `GET`

### Input

| **Argument Name**            | **Type** | **Required** | **Description**                       |
| ---------------------------- | -------- | ------------ | ------------------------------------- |
| `parameters.include_deleted` | boolean  | Optional     | Include deleted baits in the results. |

### Input Example

`{"parameters":{"include_deleted":false}}`

### Output

| **Parameter**               | **Type** | **Description**                                                |
| --------------------------- | -------- | -------------------------------------------------------------- |
| `status_code`               | number   | The HTTP status code of the response.                          |
| `reason`                    | string   | The HTTP reason phrase of the response.                        |
| `status`                    | string   | The status of the request (success or error).                  |
| `message`                   | string   | A message describing the result of the request.                |
| `data`                      | array    | The list of baits.                                             |
| `data.id`                   | integer  | The unique identifier of the bait.                             |
| `data.name`                 | string   | The display name of the bait.                                  |
| `data.profile`              | string   | The skin (login portal template) used by the bait.             |
| `data.profile_short`        | string   | The short label of the bait skin.                              |
| `data.category`             | string   | The category of the bait, such as VPN, WEBMAIL or APPLICATION. |
| `data.domain`               | string   | The domain name the bait is exposed on.                        |
| `data.hosting`              | string   | Where the bait is hosted (azure, aws or on-premise).           |
| `data.status`               | string   | The current status of the bait (UP or DOWN).                   |
| `data.reason`               | string   | The reason the bait is down, when status is DOWN.              |
| `data.is_running`           | boolean  | Whether the bait is running.                                   |
| `data.is_deleted`           | boolean  | Whether the bait has been deleted.                             |
| `data.is_data_kept`         | boolean  | Whether the data collected by the bait is kept after deletion. |
| `data.public_ip`            | string   | The public IP address of the bait.                             |
| `data.cloud_public_ip`      | string   | The public IP address of the cloud instance hosting the bait.  |
| `data.ip_proxy_in`          | string   | The inbound proxy IP address for on-premise baits.             |
| `data.ip_proxy_out`         | string   | The outbound proxy IP address for on-premise baits.            |
| `data.certificate`          | string   | The state of the TLS certificate of the bait.                  |
| `data.expiration_date_cert` | string   | The expiration date of the TLS certificate.                    |
| `data.auto_renew`           | boolean  | Whether the TLS certificate is automatically renewed.          |
| `data.renew_server`         | string   | The server used to renew the TLS certificate.                  |

### Output Example

`{"status":"active","message":"string","data":[{"id":123,"name":"Example Name","profile":"string","profile_short":"string","category":"string","domain":"string","hosting":"string","status":"active","is_running":true,"is_deleted":true,"is_data_kept":true,"public_ip":"string","cloud_public_ip":"string","ip_proxy_in":"string","ip_proxy_out":"string"}]}`

## List Attacker Aggregates

Retrieve aggregated attacker data based on login attempts captured by MokN baits.

### Endpoint

- **URL:** `/api/v1/baits/attacks`
- **Method:** `GET`

### Input

| **Argument Name**      | **Type** | **Required** | **Description**                                   |
| ---------------------- | -------- | ------------ | ------------------------------------------------- |
| `parameters.page`      | integer  | Optional     | The page number to return.                        |
| `parameters.page_size` | integer  | Optional     | The number of results per page.                   |
| `parameters.date_from` | string   | Optional     | The start date for filtering attacker aggregates. |
| `parameters.date_to`   | string   | Optional     | The end date for filtering attacker aggregates.   |

### Input Example

`{"parameters":{"page":1,"page_size":30}}`

### Output

| **Parameter** | **Type** | **Description**                                 |
| ------------- | -------- | ----------------------------------------------- |
| `status_code` | number   | The HTTP status code of the response.           |
| `reason`      | string   | The HTTP reason phrase of the response.         |
| `status`      | string   | The status of the request (success or error).   |
| `message`     | string   | A message describing the result of the request. |
| `data`        | string   | The attacker aggregates.                        |

### Output Example

`{"status":"active","message":"string","data":"string"}`

## List Available Skins

Retrieve a list of available login portal templates (skins) that can be used to create MokN baits.

### Endpoint

- **URL:** `/api/v1/baits/skins`
- **Method:** `GET`

### Output

| **Parameter** | **Type** | **Description**                                 |
| ------------- | -------- | ----------------------------------------------- |
| `status_code` | number   | The HTTP status code of the response.           |
| `reason`      | string   | The HTTP reason phrase of the response.         |
| `status`      | string   | The status of the request (success or error).   |
| `message`     | string   | A message describing the result of the request. |
| `data`        | array    | The available skins.                            |
| `data.name`   | string   | The name of the skin.                           |

### Output Example

`{"status":"active","message":"string","data":[{"name":"Example Name"}]}`

## List Certificate Authorities

Retrieve a list of certificate authorities available to issue TLS certificates for MokN baits.

### Endpoint

- **URL:** `/api/v1/baits/baits/certificate-authorities`
- **Method:** `GET`

### Output

| **Parameter** | **Type** | **Description**                                 |
| ------------- | -------- | ----------------------------------------------- |
| `status_code` | number   | The HTTP status code of the response.           |
| `reason`      | string   | The HTTP reason phrase of the response.         |
| `status`      | string   | The status of the request (success or error).   |
| `message`     | string   | A message describing the result of the request. |
| `data`        | array    | The certificate authorities.                    |
| `data.name`   | string   | The name of the certificate authority.          |

### Output Example

`{"status":"active","message":"string","data":[{"name":"Example Name"}]}`

## Retrieve a Bait

Retrieve detailed information for a specific MokN bait using its unique bait ID.

### Endpoint

- **URL:** `/api/v1/baits/baits/{{bait_id}}`
- **Method:** `GET`

### Input

| **Argument Name**         | **Type** | **Required** | **Description**                    |
| ------------------------- | -------- | ------------ | ---------------------------------- |
| `path_parameters.bait_id` | integer  | Required     | The unique identifier of the bait. |

### Input Example

`{"path_parameters":{"bait_id":101}}`

### Output

| **Parameter**               | **Type** | **Description**                                                |
| --------------------------- | -------- | -------------------------------------------------------------- |
| `status_code`               | number   | The HTTP status code of the response.                          |
| `reason`                    | string   | The HTTP reason phrase of the response.                        |
| `status`                    | string   | The status of the request (success or error).                  |
| `message`                   | string   | A message describing the result of the request.                |
| `data`                      | object   | The bait details.                                              |
| `data.id`                   | integer  | The unique identifier of the bait.                             |
| `data.name`                 | string   | The display name of the bait.                                  |
| `data.profile`              | string   | The skin (login portal template) used by the bait.             |
| `data.profile_short`        | string   | The short label of the bait skin.                              |
| `data.category`             | string   | The category of the bait, such as VPN, WEBMAIL or APPLICATION. |
| `data.domain`               | string   | The domain name the bait is exposed on.                        |
| `data.hosting`              | string   | Where the bait is hosted (azure, aws or on-premise).           |
| `data.status`               | string   | The current status of the bait (UP or DOWN).                   |
| `data.reason`               | string   | The reason the bait is down, when status is DOWN.              |
| `data.is_running`           | boolean  | Whether the bait is running.                                   |
| `data.is_deleted`           | boolean  | Whether the bait has been deleted.                             |
| `data.is_data_kept`         | boolean  | Whether the data collected by the bait is kept after deletion. |
| `data.public_ip`            | string   | The public IP address of the bait.                             |
| `data.cloud_public_ip`      | string   | The public IP address of the cloud instance hosting the bait.  |
| `data.ip_proxy_in`          | string   | The inbound proxy IP address for on-premise baits.             |
| `data.ip_proxy_out`         | string   | The outbound proxy IP address for on-premise baits.            |
| `data.certificate`          | string   | The state of the TLS certificate of the bait.                  |
| `data.expiration_date_cert` | string   | The expiration date of the TLS certificate.                    |
| `data.auto_renew`           | boolean  | Whether the TLS certificate is automatically renewed.          |
| `data.renew_server`         | string   | The server used to renew the TLS certificate.                  |

### Output Example

`{"status":"active","message":"string","data":{"id":123,"name":"Example Name","profile":"string","profile_short":"string","category":"string","domain":"string","hosting":"string","status":"active","is_running":true,"is_deleted":true,"is_data_kept":true,"public_ip":"string","cloud_public_ip":"string","ip_proxy_in":"string","ip_proxy_out":"string"}}`

## Retrieve Agent Details

Retrieve detailed information for a specific MokN agent using its unique agent ID.

### Endpoint

- **URL:** `/api/v1/baits/agents/{{agent_id}}`
- **Method:** `GET`

### Input

| **Argument Name**          | **Type** | **Required** | **Description**                       |
| -------------------------- | -------- | ------------ | ------------------------------------- |
| `parameters.export`        | boolean  | Optional     | Whether to export the agent details.  |
| `parameters.new`           | boolean  | Optional     | Whether to retrieve the agent as new. |
| `path_parameters.agent_id` | integer  | Required     | The unique identifier of the agent.   |

### Input Example

`{"path_parameters":{"agent_id":12}}`

### Output

| **Parameter**        | **Type** | **Description**                                                        |
| -------------------- | -------- | ---------------------------------------------------------------------- |
| `status_code`        | number   | The HTTP status code of the response.                                  |
| `reason`             | string   | The HTTP reason phrase of the response.                                |
| `status`             | string   | The status of the request (success or error).                          |
| `message`            | string   | A message describing the result of the request.                        |
| `data`               | object   | The agent details.                                                     |
| `data.id`            | integer  | The unique identifier of the agent.                                    |
| `data.name`          | string   | The display name of the agent.                                         |
| `data.agent_type`    | string   | The identity provider type the agent connects to.                      |
| `data.is_alive`      | boolean  | Whether the agent is currently alive and reporting to MokN.            |
| `data.is_reachable`  | boolean  | Whether the identity provider is reachable by the agent.               |
| `data.last_seen`     | string   | The date and time the agent last contacted MokN.                       |
| `data.date_created`  | string   | The date and time the agent was created.                               |
| `data.server`        | string   | The server the agent is installed on.                                  |
| `data.version`       | string   | The installed agent version.                                           |
| `data.recipients`    | array    | The email addresses notified about this agent.                         |
| `data.last_check_at` | string   | The date and time of the last credential check performed by the agent. |
| `data.today_checks`  | integer  | The number of credential checks performed today.                       |
| `data.total_checks`  | integer  | The total number of credential checks performed by the agent.          |
| `data.domain`        | string   | The domain the agent is attached to (Active Directory / Okta).         |
| `data.domains`       | array    | The email domains handled by the agent.                                |

### Output Example

`{"status":"active","message":"string","data":{"id":123,"name":"Example Name","agent_type":"string","is_alive":true,"is_reachable":true,"last_seen":"string","date_created":"string","server":"string","version":"string","recipients":["string"],"last_check_at":"string","today_checks":123,"total_checks":123,"domain":"string","domains":["string"]}}`

## Retrieve Agents Queue

Retrieve the list of login attempts that are pending, in progress, or completed in the agents' queue.

### Endpoint

- **URL:** `/api/v1/baits/agents/queue`
- **Method:** `GET`

### Input

| **Argument Name**       | **Type** | **Required** | **Description**                                           |
| ----------------------- | -------- | ------------ | --------------------------------------------------------- |
| `parameters.bait_id`    | integer  | Optional     | The unique identifier of the bait.                        |
| `parameters.nb_checked` | integer  | Optional     | The maximum number of already checked attempts to return. |

### Input Example

`{"parameters":{"nb_checked":50}}`

### Output

| **Parameter**            | **Type** | **Description**                                       |
| ------------------------ | -------- | ----------------------------------------------------- |
| `status_code`            | number   | The HTTP status code of the response.                 |
| `reason`                 | string   | The HTTP reason phrase of the response.               |
| `status`                 | string   | The status of the request (success or error).         |
| `message`                | string   | A message describing the result of the request.       |
| `data`                   | object   | The agents queue.                                     |
| `data.in_queue`          | array    | The login attempts waiting in the queue.              |
| `data.waiting_for_check` | array    | The login attempts waiting to be checked by an agent. |
| `data.checked`           | array    | The login attempts already checked by an agent.       |

### Output Example

`{"status":"active","message":"string","data":{"in_queue":[],"waiting_for_check":[],"checked":[]}}`

## Retrieve Average Time Between Two Attempts

Retrieve the average time between two login attempts across all baits and for each individual bait in MokN.

### Endpoint

- **URL:** `/api/v1/baits/dashboard/average`
- **Method:** `GET`

### Input

| **Argument Name**        | **Type** | **Required** | **Description**                                                               |
| ------------------------ | -------- | ------------ | ----------------------------------------------------------------------------- |
| `parameters.id`          | array    | Optional     | Restrict the results to these bait IDs. When omitted, all baits are returned. |
| `parameters.start_month` | string   | Optional     | The first month of the period, in YYYY/MM format.                             |
| `parameters.end_month`   | string   | Optional     | The last month of the period, in YYYY/MM format.                              |
| `parameters.detail`      | boolean  | Optional     | Whether to include detailed results for each bait.                            |

### Input Example

`{"parameters":{"id":[101],"start_month":"2026/01","end_month":"2026/10","detail":true}}`

### Output

| **Parameter** | **Type** | **Description**                                               |
| ------------- | -------- | ------------------------------------------------------------- |
| `status_code` | number   | The HTTP status code of the response.                         |
| `reason`      | string   | The HTTP reason phrase of the response.                       |
| `status`      | string   | The status of the request (success or error).                 |
| `message`     | string   | A message describing the result of the request.               |
| `data`        | array    | The average time per bait.                                    |
| `data.id`     | integer  | The bait ID. Null for the aggregate entry covering all baits. |
| `data.name`   | string   | The bait name, or "All baits" for the aggregate entry.        |
| `data.time`   | number   | The average time between two login attempts.                  |

### Output Example

`{"status":"active","message":"string","data":[{"id":123,"name":"Example Name","time":123}]}`

## Retrieve Bait Creation Status

Retrieve the current creation status of MokN baits being deployed.

### Endpoint

- **URL:** `/api/v1/baits/baits/status`
- **Method:** `GET`

### Output

| **Parameter** | **Type** | **Description**                                 |
| ------------- | -------- | ----------------------------------------------- |
| `status_code` | number   | The HTTP status code of the response.           |
| `reason`      | string   | The HTTP reason phrase of the response.         |
| `status`      | string   | The status of the request (success or error).   |
| `message`     | string   | A message describing the result of the request. |
| `data`        | string   | The bait creation status.                       |

### Output Example

`{"status":"active","message":"string","data":"string"}`

## Retrieve Monthly History

Retrieve the monthly history of login attempts for all baits and each individual bait in MokN.

### Endpoint

- **URL:** `/api/v1/baits/dashboard/monthly`
- **Method:** `GET`

### Input

| **Argument Name**        | **Type** | **Required** | **Description**                                                               |
| ------------------------ | -------- | ------------ | ----------------------------------------------------------------------------- |
| `parameters.id`          | array    | Optional     | Restrict the results to these bait IDs. When omitted, all baits are returned. |
| `parameters.start_month` | string   | Optional     | The first month of the period, in YYYY/MM format.                             |
| `parameters.end_month`   | string   | Optional     | The last month of the period, in YYYY/MM format.                              |
| `parameters.detail`      | boolean  | Optional     | Whether to include detailed monthly history.                                  |

### Input Example

`{"parameters":{"id":[101],"start_month":"2026/01","end_month":"2026/10","detail":true}}`

### Output

| **Parameter**             | **Type** | **Description**                                                        |
| ------------------------- | -------- | ---------------------------------------------------------------------- |
| `status_code`             | number   | The HTTP status code of the response.                                  |
| `reason`                  | string   | The HTTP reason phrase of the response.                                |
| `status`                  | string   | The status of the request (success or error).                          |
| `message`                 | string   | A message describing the result of the request.                        |
| `data`                    | array    | The monthly history per bait.                                          |
| `data.id`                 | integer  | The bait ID. Null for the aggregate entry covering all baits.          |
| `data.name`               | string   | The bait name, or "All baits" for the aggregate entry.                 |
| `data.date`               | string   | The month, in YYYY/MM format.                                          |
| `data.count_attempts`     | integer  | The number of login attempts.                                          |
| `data.count_targeted`     | integer  | The number of targeted attempts (existing accounts).                   |
| `data.count_leaked`       | integer  | The number of targeted attempts with a password found in public leaks. |
| `data.count_identical`    | integer  | The number of attempts using the real password.                        |
| `data.count_match_policy` | integer  | The number of attempts with a password matching the password policy.   |
| `data.count_sprayed`      | integer  | The number of password spraying attempts.                              |
| `data.count_variations`   | integer  | The number of attempts using a variation of the real password.         |
| `data.count_empty`        | integer  | The number of attempts with an empty password.                         |
| `data.count_whitelist`    | integer  | The number of whitelisted attempts.                                    |

### Output Example

`{"status":"active","message":"string","data":[{"id":123,"name":"Example Name","date":"2024-01-01T00:00:00Z","count_attempts":123,"count_targeted":123,"count_leaked":123,"count_identical":123,"count_match_policy":123,"count_sprayed":123,"count_variations":123,"count_empty":123,"count_whitelist":123}]}`

## Retrieve Monthly History Dates

Retrieve the earliest and latest months with available monthly login attempt history from MokN.

### Endpoint

- **URL:** `/api/v1/baits/dashboard/monthly/dates`
- **Method:** `GET`

### Input

| **Argument Name** | **Type** | **Required** | **Description**                                                               |
| ----------------- | -------- | ------------ | ----------------------------------------------------------------------------- |
| `parameters.id`   | array    | Optional     | Restrict the results to these bait IDs. When omitted, all baits are returned. |

### Input Example

`{"parameters":{"id":[101]}}`

### Output

| **Parameter**      | **Type** | **Description**                                 |
| ------------------ | -------- | ----------------------------------------------- |
| `status_code`      | number   | The HTTP status code of the response.           |
| `reason`           | string   | The HTTP reason phrase of the response.         |
| `status`           | string   | The status of the request (success or error).   |
| `message`          | string   | A message describing the result of the request. |
| `data`             | object   | The available monthly history range.            |
| `data.first_month` | string   | The first month with data, in YYYY/MM format.   |
| `data.last_month`  | string   | The last month with data, in YYYY/MM format.    |

### Output Example

`{"status":"active","message":"string","data":{"first_month":"string","last_month":"string"}}`

## Retrieve Short List of Agents

Retrieve a concise list of all MokN agents, including their IDs and names.

### Endpoint

- **URL:** `/api/v1/baits/agents/short`
- **Method:** `GET`

### Output

| **Parameter** | **Type** | **Description**                                 |
| ------------- | -------- | ----------------------------------------------- |
| `status_code` | number   | The HTTP status code of the response.           |
| `reason`      | string   | The HTTP reason phrase of the response.         |
| `status`      | string   | The status of the request (success or error).   |
| `message`     | string   | A message describing the result of the request. |
| `data`        | array    | The short list of agents.                       |
| `data.id`     | integer  | The unique identifier.                          |
| `data.name`   | string   | The display name.                               |

### Output Example

`{"status":"active","message":"string","data":[{"id":123,"name":"Example Name"}]}`

## Retrieve Short List of Baits

Retrieve a concise list of all MokN baits, including their IDs and names.

### Endpoint

- **URL:** `/api/v1/baits/baits/short`
- **Method:** `GET`

### Input

| **Argument Name**            | **Type** | **Required** | **Description**                       |
| ---------------------------- | -------- | ------------ | ------------------------------------- |
| `parameters.include_deleted` | boolean  | Optional     | Include deleted baits in the results. |

### Input Example

`{"parameters":{"include_deleted":false}}`

### Output

| **Parameter** | **Type** | **Description**                                 |
| ------------- | -------- | ----------------------------------------------- |
| `status_code` | number   | The HTTP status code of the response.           |
| `reason`      | string   | The HTTP reason phrase of the response.         |
| `status`      | string   | The status of the request (success or error).   |
| `message`     | string   | A message describing the result of the request. |
| `data`        | array    | The short list of baits.                        |
| `data.id`     | integer  | The unique identifier.                          |
| `data.name`   | string   | The display name.                               |

### Output Example

`{"status":"active","message":"string","data":[{"id":123,"name":"Example Name"}]}`

## Retrieve Targeting Countries Data

Retrieve the top countries of origin for login attempts across all baits and for each individual bait.

### Endpoint

- **URL:** `/api/v1/baits/dashboard/top/countries`
- **Method:** `GET`

### Input

| **Argument Name**        | **Type** | **Required** | **Description**                                                               |
| ------------------------ | -------- | ------------ | ----------------------------------------------------------------------------- |
| `parameters.id`          | array    | Optional     | Restrict the results to these bait IDs. When omitted, all baits are returned. |
| `parameters.start_month` | string   | Optional     | The first month of the period, in YYYY/MM format.                             |
| `parameters.end_month`   | string   | Optional     | The last month of the period, in YYYY/MM format.                              |
| `parameters.detail`      | boolean  | Optional     | Whether to include country-level details in the results.                      |

### Input Example

`{"parameters":{"id":[101],"start_month":"2026/01","end_month":"2026/10","detail":true}}`

### Output

| **Parameter**                 | **Type** | **Description**                                               |
| ----------------------------- | -------- | ------------------------------------------------------------- |
| `status_code`                 | number   | The HTTP status code of the response.                         |
| `reason`                      | string   | The HTTP reason phrase of the response.                       |
| `status`                      | string   | The status of the request (success or error).                 |
| `message`                     | string   | A message describing the result of the request.               |
| `data`                        | array    | The top countries per bait.                                   |
| `data.id`                     | integer  | The bait ID. Null for the aggregate entry covering all baits. |
| `data.name`                   | string   | The bait name, or "All baits" for the aggregate entry.        |
| `data.details`                | array    | The countries sorted by number of attempts.                   |
| `data.details.country`        | string   | The name of the country.                                      |
| `data.details.country_code`   | string   | The ISO country code.                                         |
| `data.details.total_attempts` | integer  | The number of login attempts from this country.               |

### Output Example

`{"status":"active","message":"string","data":[{"id":123,"name":"Example Name","details":[]}]}`

## Retrieve Threat Level

Retrieve the overall threat level for all baits and individual threat levels for each bait in MokN.

### Endpoint

- **URL:** `/api/v1/baits/dashboard/threat`
- **Method:** `GET`

### Input

| **Argument Name**        | **Type** | **Required** | **Description**                                                               |
| ------------------------ | -------- | ------------ | ----------------------------------------------------------------------------- |
| `parameters.id`          | array    | Optional     | Restrict the results to these bait IDs. When omitted, all baits are returned. |
| `parameters.start_month` | string   | Optional     | The first month of the period, in YYYY/MM format.                             |
| `parameters.end_month`   | string   | Optional     | The last month of the period, in YYYY/MM format.                              |
| `parameters.detail`      | boolean  | Optional     | Whether to include detailed threat-level results.                             |

### Input Example

`{"parameters":{"id":[101],"start_month":"2026/01","end_month":"2026/10","detail":true}}`

### Output

| **Parameter**       | **Type** | **Description**                                               |
| ------------------- | -------- | ------------------------------------------------------------- |
| `status_code`       | number   | The HTTP status code of the response.                         |
| `reason`            | string   | The HTTP reason phrase of the response.                       |
| `status`            | string   | The status of the request (success or error).                 |
| `message`           | string   | A message describing the result of the request.               |
| `data`              | array    | The threat level per bait.                                    |
| `data.id`           | integer  | The bait ID. Null for the aggregate entry covering all baits. |
| `data.name`         | string   | The bait name, or "All baits" for the aggregate entry.        |
| `data.threat_level` | string   | The threat level (Low, Medium, High or Critical).             |

### Output Example

`{"status":"active","message":"string","data":[{"id":123,"name":"Example Name","threat_level":"string"}]}`

## Retrieve Top Passwords

Retrieve the most frequently used passwords in login attempts across all baits and for each individual bait.

### Endpoint

- **URL:** `/api/v1/baits/dashboard/top/passwords`
- **Method:** `GET`

### Input

| **Argument Name**        | **Type** | **Required** | **Description**                                                               |
| ------------------------ | -------- | ------------ | ----------------------------------------------------------------------------- |
| `parameters.id`          | array    | Optional     | Restrict the results to these bait IDs. When omitted, all baits are returned. |
| `parameters.start_month` | string   | Optional     | The first month of the period, in YYYY/MM format.                             |
| `parameters.end_month`   | string   | Optional     | The last month of the period, in YYYY/MM format.                              |
| `parameters.limit`       | integer  | Optional     | The maximum number of entries returned for each bait.                         |
| `parameters.detail`      | boolean  | Optional     | Whether to include detailed password information.                             |

### Input Example

`{"parameters":{"id":[101],"start_month":"2026/01","end_month":"2026/10","limit":10,"detail":true}}`

### Output

| **Parameter**             | **Type** | **Description**                                                                   |
| ------------------------- | -------- | --------------------------------------------------------------------------------- |
| `status_code`             | number   | The HTTP status code of the response.                                             |
| `reason`                  | string   | The HTTP reason phrase of the response.                                           |
| `status`                  | string   | The status of the request (success or error).                                     |
| `message`                 | string   | A message describing the result of the request.                                   |
| `data`                    | array    | The top passwords per bait.                                                       |
| `data.id`                 | integer  | The bait ID. Null for the aggregate entry covering all baits.                     |
| `data.name`               | string   | The bait name, or "All baits" for the aggregate entry.                            |
| `data.passwords`          | object   | The most used passwords, mapped to their number of attempts.                      |
| `data.targeted_passwords` | object   | The most used passwords on existing accounts, mapped to their number of attempts. |

### Output Example

`{"status":"active","message":"string","data":[{"id":123,"name":"Example Name","passwords":{},"targeted_passwords":{}}]}`

## Retrieve Top Usernames

Retrieve the most frequently used usernames in login attempts across all baits and for each individual bait.

### Endpoint

- **URL:** `/api/v1/baits/dashboard/top/logins`
- **Method:** `GET`

### Input

| **Argument Name**        | **Type** | **Required** | **Description**                                                               |
| ------------------------ | -------- | ------------ | ----------------------------------------------------------------------------- |
| `parameters.id`          | array    | Optional     | Restrict the results to these bait IDs. When omitted, all baits are returned. |
| `parameters.start_month` | string   | Optional     | The first month of the period, in YYYY/MM format.                             |
| `parameters.end_month`   | string   | Optional     | The last month of the period, in YYYY/MM format.                              |
| `parameters.limit`       | integer  | Optional     | The maximum number of entries returned for each bait.                         |
| `parameters.detail`      | boolean  | Optional     | Whether to include detailed results.                                          |

### Input Example

`{"parameters":{"id":[101],"start_month":"2026/01","end_month":"2026/10","limit":10,"detail":true}}`

### Output

| **Parameter**         | **Type** | **Description**                                                          |
| --------------------- | -------- | ------------------------------------------------------------------------ |
| `status_code`         | number   | The HTTP status code of the response.                                    |
| `reason`              | string   | The HTTP reason phrase of the response.                                  |
| `status`              | string   | The status of the request (success or error).                            |
| `message`             | string   | A message describing the result of the request.                          |
| `data`                | array    | The top usernames per bait.                                              |
| `data.id`             | integer  | The bait ID. Null for the aggregate entry covering all baits.            |
| `data.name`           | string   | The bait name, or "All baits" for the aggregate entry.                   |
| `data.users`          | object   | The most used usernames, mapped to their number of attempts.             |
| `data.targeted_users` | object   | The most targeted existing accounts, mapped to their number of attempts. |

### Output Example

`{"status":"active","message":"string","data":[{"id":123,"name":"Example Name","users":{},"targeted_users":{}}]}`

## Retrieve Unique Targeted Accounts Data

Retrieve the count of unique targeted accounts across all baits and for each individual bait in MokN.

### Endpoint

- **URL:** `/api/v1/baits/dashboard/unique`
- **Method:** `GET`

### Input

| **Argument Name**        | **Type** | **Required** | **Description**                                                               |
| ------------------------ | -------- | ------------ | ----------------------------------------------------------------------------- |
| `parameters.id`          | array    | Optional     | Restrict the results to these bait IDs. When omitted, all baits are returned. |
| `parameters.start_month` | string   | Optional     | The first month of the period, in YYYY/MM format.                             |
| `parameters.end_month`   | string   | Optional     | The last month of the period, in YYYY/MM format.                              |
| `parameters.detail`      | boolean  | Optional     | Whether to include detailed results for each bait.                            |

### Input Example

`{"parameters":{"id":[101],"start_month":"2026/01","end_month":"2026/10","detail":true}}`

### Output

| **Parameter** | **Type** | **Description**                                               |
| ------------- | -------- | ------------------------------------------------------------- |
| `status_code` | number   | The HTTP status code of the response.                         |
| `reason`      | string   | The HTTP reason phrase of the response.                       |
| `status`      | string   | The status of the request (success or error).                 |
| `message`     | string   | A message describing the result of the request.               |
| `data`        | array    | The unique targeted accounts per bait.                        |
| `data.id`     | integer  | The bait ID. Null for the aggregate entry covering all baits. |
| `data.name`   | string   | The bait name, or "All baits" for the aggregate entry.        |
| `data.unique` | integer  | The number of unique targeted accounts.                       |

### Output Example

`{"status":"active","message":"string","data":[{"id":123,"name":"Example Name","unique":123}]}`

## Update an Agent

Update the configuration of an existing MokN agent using the specified agent ID and new settings.

### Endpoint

- **URL:** `/api/v1/baits/agents/{{agent_id}}`
- **Method:** `PUT`

### Input

| **Argument Name**          | **Type** | **Required** | **Description**                                                                               |
| -------------------------- | -------- | ------------ | --------------------------------------------------------------------------------------------- |
| `path_parameters.agent_id` | integer  | Required     | The unique identifier of the agent.                                                           |
| `name`                     | string   | Optional     | The display name of the agent.                                                                |
| `agent_type`               | string   | Optional     | The identity provider type the agent connects to.                                             |
| `recipients`               | array    | Optional     | The email addresses notified about this agent.                                                |
| `valid_username`           | string   | Optional     | A valid account username used to monitor the agent. Must be set together with Valid Password. |
| `valid_password`           | string   | Optional     | The password of the monitoring account.                                                       |
| `domain`                   | string   | Optional     | The domain of the identity provider (Active Directory and Okta agents).                       |
| `domains`                  | array    | Optional     | The email domains handled by the agent (Entra ID, Okta and Google agents).                    |
| `domain_controller`        | string   | Optional     | The host of the domain controller (Active Directory agents).                                  |
| `search_base`              | string   | Optional     | The LDAP search scope (Active Directory agents).                                              |
| `lockout_threshold`        | integer  | Optional     | The account lockout threshold, between 0 and 9999 (Active Directory agents).                  |
| `tls_ssl`                  | boolean  | Optional     | Whether LDAP connections use TLS/SSL (Active Directory agents).                               |
| `tls_ssl_verify`           | boolean  | Optional     | Whether the LDAP TLS certificate is verified (Active Directory agents).                       |
| `attributes`               | array    | Optional     | The directory attributes used to match usernames (Active Directory and Google agents).        |
| `tenant_id`                | string   | Optional     | The Microsoft Entra ID tenant ID (Entra ID agents).                                           |
| `client_id`                | string   | Optional     | The Microsoft Entra ID application client ID (Entra ID agents).                               |
| `client_secret`            | string   | Optional     | The Microsoft Entra ID application client secret value, not the secret ID (Entra ID agents).  |
| `is_fast_setup`            | boolean  | Optional     | Whether the Entra ID fast setup is used (Entra ID agents).                                    |
| `ssws_token`               | string   | Optional     | The Okta API token (Okta agents).                                                             |
| `tls_client_certificate`   | string   | Optional     | The PEM-encoded TLS client certificate (Google agents).                                       |
| `tls_client_private_key`   | string   | Optional     | The PEM-encoded TLS client private key (Google agents).                                       |

### Input Example

`{"json_body":{"name":"Corporate AD agent","agent_type":"AgentAD","recipients":["soc@example.com"],"domain":"corp.example.com","domain_controller":"dc01.corp.example.com","search_base":"DC=corp,DC=example,DC=com","lockout_threshold":0,"tls_ssl":true,"tls_ssl_verify":false,"attributes":["mail","samaccountname","userprincipalname"]},"path_parameters":{"agent_id":12}}`

### Output

| **Parameter**        | **Type** | **Description**                                                        |
| -------------------- | -------- | ---------------------------------------------------------------------- |
| `status_code`        | number   | The HTTP status code of the response.                                  |
| `reason`             | string   | The HTTP reason phrase of the response.                                |
| `status`             | string   | The status of the request (success or error).                          |
| `message`            | string   | A message describing the result of the request.                        |
| `data`               | object   | The agent details.                                                     |
| `data.id`            | integer  | The unique identifier of the agent.                                    |
| `data.name`          | string   | The display name of the agent.                                         |
| `data.agent_type`    | string   | The identity provider type the agent connects to.                      |
| `data.is_alive`      | boolean  | Whether the agent is currently alive and reporting to MokN.            |
| `data.is_reachable`  | boolean  | Whether the identity provider is reachable by the agent.               |
| `data.last_seen`     | string   | The date and time the agent last contacted MokN.                       |
| `data.date_created`  | string   | The date and time the agent was created.                               |
| `data.server`        | string   | The server the agent is installed on.                                  |
| `data.version`       | string   | The installed agent version.                                           |
| `data.recipients`    | array    | The email addresses notified about this agent.                         |
| `data.last_check_at` | string   | The date and time of the last credential check performed by the agent. |
| `data.today_checks`  | integer  | The number of credential checks performed today.                       |
| `data.total_checks`  | integer  | The total number of credential checks performed by the agent.          |
| `data.domain`        | string   | The domain the agent is attached to (Active Directory / Okta).         |
| `data.domains`       | array    | The email domains handled by the agent.                                |

### Output Example

`{"status":"active","message":"string","data":{"id":123,"name":"Example Name","agent_type":"string","is_alive":true,"is_reachable":true,"last_seen":"string","date_created":"string","server":"string","version":"string","recipients":["string"],"last_check_at":"string","today_checks":123,"total_checks":123,"domain":"string","domains":["string"]}}`

# Response Headers

| **Header**   | **Description**                                       | **Example**                   |
| ------------ | ----------------------------------------------------- | ----------------------------- |
| Content-Type | The media type of the resource                        | application/json              |
| Date         | The date and time at which the message was originated | Thu, 01 Jan 2024 00:00:00 GMT |
