API Whitelist

Introduction

The Lucy API operates as a RESTful web service, characterized by its stateless nature, meaning it does not maintain the client's state. As such, all API requests can be executed in any order without dependency on the sequence.

Navigate to Settings -> Common System Settings -> API Whitelist

Here, you will be required to specify the remote IP addresses that are permitted to communicate with the API, ensuring controlled and secure access to the service.

Requirements

• The service exclusively utilizes JSON as the data interchange format. All responses from the API are provided in JSON, and it is expected that most request parameters are also conveyed in JSON.

• Every request made to the API must include a "Content-Type" header that is set to "application/json" to ensure proper handling and interpretation of the request data.

• All requests must be made strictly over the HTTPS protocol. Any requests sent to the API using plain HTTP will be rejected by the server.

Authentication

Lucy API employs JWT (JSON Web Tokens) for authentication. To initiate any operations, a token must first be obtained by sending an Authentication request. This initial step is critical before proceeding with any further requests. Below are details regarding the Authentication request:

• Obtaining the Token: Send an Authentication request to the Lucy API. The specific details of this request, including the endpoint and required credentials (typically a username and password), are outlined in the API documentation.

• Using the Token: Once the token is obtained, it should be included in the "Authorization" HTTP header as part of the "Bearer" scheme for all subsequent API requests. This step is essential for authenticating your identity with the API.

• Request Format: All other requests, aside from the authentication request, must include this token. An example of including the token in a request header is as follows:

Authorization: Bearer <your_token_here>

It's important to note that the authentication request is the only exception that does not require a token. Every other request to the API must include the obtained token for successful authentication and authorization.

The client should locally store the JWT token obtained from the authentication request and retain it until its expiration. The expiration date and time of the token are specified within the token's header, providing a clear indication of its valid usage period.

To understand the structure of a JWT token and to access libraries for handling JWT in various programming languages, you can visit https://jwt.io/.

Resources

When interacting with the Lucy API, "resources" refer to the data you either retrieve from the API or the objects you create or modify through it. The structure of these resources remains consistent, regardless of the type of action you are performing. This uniformity ensures that the representation of an object does not change whether you are fetching information about it or creating it anew.

Take "campaigns" as an example: the data structure you receive when listing all campaigns or querying a single campaign remains the same as what the server expects when you submit a request to create a new campaign. The primary distinction lies in the handling of links. During POST or PUT operations (creating or updating resources), the server does not expect any links within the request body and will ignore them if they are included. These links are utilized solely in GET requests to delineate relationships between resources.

To define relationships with other existing objects in the system, it is recommended to use integer IDs. This approach simplifies the association process between different resources within Lucy's API, ensuring clarity and consistency across various operations.

API record Return Limit

When querying Lucy API endpoints that return a list of resources, the default behavior is to return a maximum of 100 records per request. However, if you need to retrieve more or fewer records in a single request, you can customize this by using the LIMIT and OFFSET request parameters.

The maximum number of records you can request using the LIMIT parameter is "1000". If you specify a LIMIT value greater than 1000, the API will still return a maximum of 1000 records to ensure performance and system stability. This limit ensures that the API can handle requests efficiently without compromising the server's responsiveness.

To illustrate how you can customize the number of records returned, consider the following example:

GET /api/campaigns?sort=-created_at&offset=10&limit=10

In this example, the sort parameter orders the campaigns by their creation date in descending order (-created_at). The offset parameter is used to skip the first 10 records, effectively starting the list from the 11th record. The limit parameter then limits the number of returned records to 10. This configuration is particularly useful for implementing pagination or retrieving specific segments of data from Lucy's API.

Example Usage

1. Authenticate to Obtain a Token:

   • Request:

     POST /api/auth HTTP/1.1
     Host: phish.local
     Content-Type: application/json
     Cache-Control: no-cache
     
     {"email":"[e-mail]","password":"123"}

   • Response:

     {"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9..."}

     Use this token in the "Authorization" header for all subsequent requests.

2. Create a Recipient Group:

   • Request:

     PUT /api/recipient-groups/ HTTP/1.1
     Host: phish.local
     Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9...
     Content-Type: application/json
     Cache-Control: no-cache
     
     {"name":"test recipient group"}

   • Response:

     {"recipient-group":{"id":262,"name":"test recipient group","usb_attack":false,"links":[{"rel":"self","href":"/api/recipient-groups/262"}]}}

3. Add a Recipient to the Group:

   • Request:

     PUT /api/recipient-groups/262/recipients HTTP/1.1
     Host: phish.local
     Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9...
     Content-Type: application/json
     Cache-Control: no-cache
     
     {"email":"[e-mail]","name":"Support Test"}

   • Response:

     {"recipient":{"email":"[e-mail]","phone":null,"name":"Support Test"}}

This sequence demonstrates the basic operations to authenticate, create a recipient group, and add a recipient to that group within the Lucy platform using its API. Remember to replace the token, email addresses, names, and other details with your actual data when making these requests.

Detailed Documentation and Endpoints

Each Lucy server includes a Swagger client, enabling administrators to explore and test endpoints. To access the Swagger client, navigate to Settings -> Common System Settings -> API Whitelist section, and choose API Documentation.

A Swagger API client is a software library or tool generated from a Swagger specification, designed to facilitate communication with a web API that is described by that specification. Swagger, now known as OpenAPI, is a widely used framework for API development, offering a set of tools for designing, building, documenting, and consuming RESTful web services.

General API End-points as a reference guide

Please be aware that utilizing the Swagger client for testing and inspecting the endpoints detailed below is strongly recommended. This list is intended to serve as a broad reference to the endpoints available.

№	End Point	HTTP Verb	Description
1	/api/auth	POST	Client authentication
2	/api/languages	GET	Get a list of languages
3	/api/clients	GET	Get a list of clients
4	/api/clients	PUT	Create a client
5	/api/clients/:id	GET	Get client
6	/api/clients/:id	POST	Save client
7	/api/clients/:id	DELETE	Delete client
8	/api/recipient-groups	GET	Get a list of recipient groups
9	/api/recipient-groups	POST	Create a recipient group
10	/api/recipient-groups/:id	GET	Get recipient group
11	/api/recipient-groups/:id	POST	Save recipient group
12	/api/recipient-groups/:id	DELETE	Save recipient group
13	/api/recipient-groups/:id/recipients	GET	Get a list of recipients in group
14	/api/recipient-groups/:id/recipients	PUT	Create a recipient
15	/api/recipients/:id	GET	Get recipient
16	/api/recipients/:id	POST	Save recipient
17	/api/recipients/:id	DELETE	Delete recipient
18	/api/recipient-custom-fields	GET	Get a list of recipient custom fields
19	/api/recipient-custom-fields	PUT	Create a recipient custom field
20	/api/recipient-custom-fields/:id	GET	Get recipient custom fields
21	/api/recipient-custom-fields/:id	POST	Save recipient custom field
22	/api/recipient-custom-fields/:id	DELETE	Delete recipient custom field
23	/api/scenario-templates	GET	Get a list of scenario templates
24	/api/scenario-templates/:id	GET	Get scenario template
25	/api/scenario-templates/:id	DELETE	Delete scenario template
26	/api/awareness-templates	GET	Get a list of awareness templates
27	/api/awareness-templates/:id	GET	Get awareness template
28	/api/awareness-templates/:id	DELETE	Delete awareness template
29	/api/attachment-templates	GET	Get a list of attachment templates
30	/api/attachment-templates/:id	GET	Get attachment template
31	/api/attachment-templates/:id	DELETE	Delete attachment template
32	/api/report-templates	GET	Get a list of report templates
33	/api/report-templates/:id	GET	Get report template
34	/api/campaigns/templates	GET	Get a list of campaign templates
35	/api/campaigns	GET	Get a list of campaigns
36	/api/campaigns	PUT	Create a campaign
37	/api/campaigns/:id	GET	Get campaign
38	/api/campaigns/:id	POST	Save campaign
39	/api/campaigns/:id	DELETE	Delete campaign
40	/api/campaigns/:id/recipient-groups	GET	Get a list of recipient groups in campaign
41	/api/campaigns/:id/recipient-groups	PUT	Add a recipient group to a campaign (recipients will be added to all scenarios in campaign)
42	/api/campaigns/:id/recipient-groups/:recipient_group_id	DELETE	Delete recipient group from campaign
43	/api/campaigns/:id/status	POST	Change campaign status. This endpoint is intended to run, stop or restart a campaign; therefore it supports only POST request and only three statuses
44	/api/campaigns/:id/copy	POST	Copy a campaign with all scenarios
45	/api/campaigns/:id/stats	GET	Get campaign statistics
46	/api/campaigns/:id/report	POST	Create a campaign report
47	/api/campaigns/:id/errors	GET	Get campaign errors
48	/api/campaigns/:id/victims	GET	Get campaign victims
49	/api/campaigns/victims/:victim_id/re-send/:message_type	POST	Resend email for the specified victim and message type
50	/api/campaigns/:id/scenarios	GET	Get a list of scenarios in campaign
51	/api/campaigns/:id/scenarios	PUT	Create scenario in campaign
52	/api/campaigns/:id/awareness	GET	Get a list of awareness in campaign
53	/api/campaigns/:id/awareness	PUT	Create awareness in campaign
54	/api/campaign-custom-fields	GET	Get a list of campaign custom fields
55	/api/campaign-custom-fields	PUT	Create a campaign custom field
56	/api/campaign-custom-fields/:id	GET	Get campaign custom fields
57	/api/campaign-custom-fields/:id	POST	Save campaign custom field
58	/api/campaign-custom-fields/:id	DELETE	Delete campaign custom field
59	/api/scenarios/:id	GET	Get scenario
60	/api/scenarios/:id	POST	Save scenario
61	/api/scenarios/:id	DELETE	Delete scenario from campaign
62	/api/scenarios/:id/recipient-groups	GET	Get a list of recipient groups in scenario
63	/api/scenarios/:id/recipient-groups	PUT	Add a recipient group to a scenario
64	/api/scenarios/:id/recipient-groups/:recipient_group_id	DELETE	Delete recipient group from a scenario
65	/api/scenarios/:id/victims	GET	Get scenario victims
66	/api/incidents	GET	Get a list of phishing incident reports
67	/api/incidents/:id	GET	Get incident
68	/api/incidents/:id	DELETE	Delete incident
69	/api/export/generate	POST	Export campaign data
70	/api/awareness-certificates/generate	POST	Request a certificate for victims
71	/api/awareness-certificates/:id	GET	Check awareness certificate status
72	/api/awareness-certificates/download/:id	GET	Download the archive with awareness certificates
73	/api/benchmarks	GET	Get a list of benchmarks
74	/api/benchmarks	PUT	Create a benchmark
75	/api/benchmarks/:id	GET	Get benchmark
76	/api/benchmarks/:id	POST	Save benchmark
77	/api/benchmarks/:id	DELETE	Delete benchmark
78	/api/domains	GET	Get a list of domains
79	/api/domains	PUT	Create a domain
80	/api/domains	DELETE	Delete domain
81	/api/export/:id	GET	Get an Export for the specified ID