api []

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
===== LUCY REST API - Background Info =====

Lucy API is a RESTful web service. The API does not keep the client's state and all requests can be performed in any order. Within LUCY the API can be activated under settings/API. You will need to specify the remote IP(s) which is allowed to communicate with the API.

{{ api1.png?600 }}

===== Requirements =====

Some general requirements are:

  * The service uses JSON as the only data interchange format, all API responses are in JSON, most request parameters are expected to be in JSON. 
  * All requests to API should have a "Content-Type" header set to "application/json".
  * All requests should be performed strictly over HTTPS protocol. Plain HTTP requests to API will be rejected by server.


===== Authentication =====

Lucy API uses JWT (JSON web tokens) for authentication. The token should be obtained by sending an Authentication request before issuing any other requests (see Authentication request description below for details).
The obtained authentication token should be specified in the "Authorization" HTTP header with "Bearer" scheme, for all subsequent requests. The only request that doesn't require authentication is the authentication request itself, all other requests require a token. Example:


  Authorization: Bearer
  eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI
  6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONF
  h7HgQ

The client should store the token locally and keep it until the token expires. The expiration date and time is specified in the token header. Please check out https://jwt.io/ for JWT token formation description and libraries for various programming languages.

===== Resources =====
Resources are used when getting some data from Lucy API or creating/changing some objects in Lucy. Resource structure is always the same and does not depend on the type of action you do - whether you are getting information from Lucy or creating an object, the object representation doesn't change. For example, campaigns - when you get a list of campaigns or get a single campaign, the structure doesn't differ from what the
server expects when you are creating a new campaign. The only difference is links - when you are posting/putting something to API, the server does not expect any links (and ignores them if they are present in request). The links are only used for exposing relations in GET requests. For specifying relations with other existing objects in system, please use integer IDs.

===== API Records Return Limit =====

All endpoints returning a list of Resources, by default, can return only 100 records. If necessary, this can be changed using request parameters LIMIT and OFFSET.\\

The maximum LIMIT is "1000". Any LIMIT values exceeding 1000 will return maximum of 1000 records.\\

Example of limit customization:\\
  {GET /api/campaigns?sort=-created_at&offset=10&limit=10}

===== Example Usage =====

First you need to auth:

  POST /api/auth HTTP/1.1
  Host: phish.local
  Content-Type: application/json
  Cache-Control: no-cache
  
  {"email":"test@test.com","password":"123"}

You will get the token in response, use it in all subsequent requests:

{"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE1MDQ1OTI4OTksImp0aSI6Ik1QbktRTkxscDdrOHh6YzRxenp3ZlhWd085TjRCMFRIZ21UUXpwalFXdVE9IiwiaXNzIjoicGhpc2gubG9jYWwiLCJuYmYiOjE1MDQ1OTI5MDAsImV4cCI6MTUwNDY3OTMwMCwiZGF0YSI6eyJ1c2VySWQiOjIsInVzZXJOYW1lIjoidGVzdEB0ZXN0LmNvbSJ9fQ.2B0SafZcpF-kyN0RqscfAthojX0iaEtcCegAYfZeG6BuBVF3pUxnYgclYqpLUGj57WwEPTdapSc1dqgbwW6l2w"}

Then create a group for example:

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

You will get something like this in response:

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

Then you may create a recipient in that group:

  PUT /api/recipient-groups/262/recipients HTTP/1.1
  Host: phish.local
  Authorization: Bearer   eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE1MDQ1OTI4OTksImp0aSI6Ik1QbktRTkxscDdrOHh6YzRxenp3ZlhWd085TjRCMFRIZ21UUXpwalFXdVE9IiwiaXNzIjoicGhpc2gubG9jYWwiLCJuYmYiOjE1MDQ1OTI5MDAsImV4cCI6MTUwNDY3OTMwMCwiZGF0YSI6eyJ1c2VySWQiOjIsInVzZXJOYW1lIjoidGVzdEB0ZXN0LmNvbSJ9fQ.2B0SafZcpF-kyN0RqscfAthojX0iaEtcCegAYfZeG6BuBVF3pUxnYgclYqpLUGj57WwEPTdapSc1dqgbwW6l2w
  Content-Type: application/json
  Cache-Control: no-cache
  
  {"email":"oliver@test.com","name":"Oliver Test"}

You will get this response:

  {"recipient":{"email":"oliver@test.com","phone":null,"name":"Oliver   Test","staff_type":null,"location":null,"division":null,"comment":null,"link":null,"language_id":null,"recipient_group_id":262,"id":"158928","last_tested":null,"links":[{"rel":"self","href":"/api/recipients/158928"},  {"rel":"recipient_group","href":"/api/recipient-groups/262"}]}}

===== API End Points =====

A partial list of API End Points supported by LUCY can be found [[api_end_points|here]]. For a complete list consult the Swagger documentation in your workstation.

===== Detailed Documentation =====

The detailed documentation for LUCY REST API is available from within the LUCY web interface in the section Settings > API Whitelist > API Documentation.

{{ api_documentation.png?600 }}