Skip to content

Latest commit

 

History

History
2205 lines (1376 loc) · 42.1 KB

API.md

File metadata and controls

2205 lines (1376 loc) · 42.1 KB
Raw

3FA

Backend API for the 3FA service which interacts with the client application, admin dashboard, and motion devices.

Note the variables {{hostname}} and {{port}} are placeholders for the hostname and port of the server which are usually localhost or 192.192.168.137.1 and 5000 respectively.

Endpoints

Admin Dashboard API

1. Status Check

Check the API health

Endpoint:

Method: GET
Type: 
URL: {{hostname}}:{{port}}/health/

More example Requests/Responses:

I. Example Request: OK

Body: None

I. Example Response: OK

OK

Status Code: 200


2. Failed Events

Get a list of past failed login events

Endpoint:

Method: POST
Type: RAW
URL: {{hostname}}:{{port}}/api/dashboard/failed_events/

Body:

{
    "auth_session_id": "06c6466b-9c38-4fd3-91c4-73370c941118"
}

More example Requests/Responses:

I. Example Request: List (No Images)

Headers:

Key Value Description
Content-Type application/json

Body:

{
    "auth_session_id": "06c6466b-9c38-4fd3-91c4-73370c941118"
}

I. Example Response: List (No Images)

{
    "events": [
        {
            "date": "22/03/2023 14:39:54",
            "event": "Incorrect added motion sequence entered.",
            "id": "e1d2a58d-7c1f-4b96-bed7-6c5abf47a6e3",
            "photo": "None",
            "session_id": "feb41b52-a4c2-4726-91c2-9e2f6db631a7"
        },
        {
            "date": "22/03/2023 14:44:11",
            "event": "Incorrect added motion sequence entered.",
            "id": "465c0a88-5f36-4c6f-9f7c-896c612cdb3e",
            "photo": "None",
            "session_id": "d6f812a5-f734-4d06-afc4-f6cf24ba5459"
        },
        {
            "date": "22/03/2023 14:46:06",
            "event": "Incorrect added motion sequence entered.",
            "id": "dfca5fdb-ad63-437a-bf74-2fc97bb308ab",
            "photo": "None",
            "session_id": "2ee94d44-c746-4d08-881e-dae5b905bc17"
        },
        {
            "date": "22/03/2023 14:54:38",
            "event": "Incorrect added motion sequence entered.",
            "id": "81906246-f848-402a-85d5-7902ad024db1",
            "photo": "None",
            "session_id": "c8d71676-e81d-41e1-aa93-4ad5e372d6ac"
        },
        {
            "date": "22/03/2023 14:56:55",
            "event": "Incorrect added motion sequence entered.",
            "id": "07142526-7cbd-4e21-aa96-e7e899151fad",
            "photo": "None",
            "session_id": "9874352c-2052-4fe2-bfc6-4f9c7268afb6"
        },
        {
            "date": "22/03/2023 15:10:30",
            "event": "Incorrect added motion sequence entered.",
            "id": "ac4176c5-afe5-4d86-baf6-7769c2354bdc",
            "photo": "None",
            "session_id": "f3fa0429-741c-4e9e-acc1-2deabb3c4c4e"
        },
        {
            "date": "22/03/2023 15:13:48",
            "event": "Incorrect added motion sequence entered.",
            "id": "7b6608a7-8e31-46cc-9d23-b9286abba406",
            "photo": "None",
            "session_id": "e6cfdd0c-b997-4f24-b019-5ec603bc864e"
        },
        {
            "date": "22/03/2023 15:20:14",
            "event": "Incorrect added motion sequence entered.",
            "id": "6675ca84-747c-4f1d-9ac0-1ff1983b60ff",
            "photo": "None",
            "session_id": "74afbd1b-a193-43e0-a0f9-3e1cb95921f6"
        },
        {
            "date": "22/03/2023 15:21:46",
            "event": "Incorrect added motion sequence entered.",
            "id": "406849f1-b5b1-45e5-8392-1b6c5ed41ca3",
            "photo": "None",
            "session_id": "cb396d4b-b54c-4698-ac54-1ba807f0cdb6"
        },
        {
            "date": "22/03/2023 15:22:51",
            "event": "Incorrect added motion sequence entered.",
            "id": "0be7f5f9-964f-4aa0-962d-e6d7fd8b0fbb",
            "photo": "None",
            "session_id": "1ab2042e-6ce5-470a-9c55-6bd9150bec3c"
        }
    ],
    "msg": "Failed events retrieved.",
    "success": 1
}

Status Code: 200


II. Example Request: Email Specific

Headers:

Key Value Description
Content-Type application/json

Query:

Key Value Description
email all@email.com

Body:

{
    "auth_session_id": "06c6466b-9c38-4fd3-91c4-73370c941118"
}

II. Example Response: Email Specific

{
    "events": [
        {
            "date": "22/03/2023 14:39:54",
            "event": "Incorrect added motion sequence entered.",
            "id": "e1d2a58d-7c1f-4b96-bed7-6c5abf47a6e3",
            "photo": "None",
            "session_id": "feb41b52-a4c2-4726-91c2-9e2f6db631a7"
        },
        {
            "date": "22/03/2023 14:44:11",
            "event": "Incorrect added motion sequence entered.",
            "id": "465c0a88-5f36-4c6f-9f7c-896c612cdb3e",
            "photo": "None",
            "session_id": "d6f812a5-f734-4d06-afc4-f6cf24ba5459"
        },
        {
            "date": "22/03/2023 14:46:06",
            "event": "Incorrect added motion sequence entered.",
            "id": "dfca5fdb-ad63-437a-bf74-2fc97bb308ab",
            "photo": "None",
            "session_id": "2ee94d44-c746-4d08-881e-dae5b905bc17"
        },
        {
            "date": "22/03/2023 14:54:38",
            "event": "Incorrect added motion sequence entered.",
            "id": "81906246-f848-402a-85d5-7902ad024db1",
            "photo": "None",
            "session_id": "c8d71676-e81d-41e1-aa93-4ad5e372d6ac"
        },
        {
            "date": "22/03/2023 14:56:55",
            "event": "Incorrect added motion sequence entered.",
            "id": "07142526-7cbd-4e21-aa96-e7e899151fad",
            "photo": "None",
            "session_id": "9874352c-2052-4fe2-bfc6-4f9c7268afb6"
        },
        {
            "date": "22/03/2023 15:10:30",
            "event": "Incorrect added motion sequence entered.",
            "id": "ac4176c5-afe5-4d86-baf6-7769c2354bdc",
            "photo": "None",
            "session_id": "f3fa0429-741c-4e9e-acc1-2deabb3c4c4e"
        },
        {
            "date": "22/03/2023 15:13:48",
            "event": "Incorrect added motion sequence entered.",
            "id": "7b6608a7-8e31-46cc-9d23-b9286abba406",
            "photo": "None",
            "session_id": "e6cfdd0c-b997-4f24-b019-5ec603bc864e"
        },
        {
            "date": "22/03/2023 15:20:14",
            "event": "Incorrect added motion sequence entered.",
            "id": "6675ca84-747c-4f1d-9ac0-1ff1983b60ff",
            "photo": "None",
            "session_id": "74afbd1b-a193-43e0-a0f9-3e1cb95921f6"
        },
        {
            "date": "22/03/2023 15:21:46",
            "event": "Incorrect added motion sequence entered.",
            "id": "406849f1-b5b1-45e5-8392-1b6c5ed41ca3",
            "photo": "None",
            "session_id": "cb396d4b-b54c-4698-ac54-1ba807f0cdb6"
        },
        {
            "date": "22/03/2023 15:22:51",
            "event": "Incorrect added motion sequence entered.",
            "id": "0be7f5f9-964f-4aa0-962d-e6d7fd8b0fbb",
            "photo": "None",
            "session_id": "1ab2042e-6ce5-470a-9c55-6bd9150bec3c"
        }
    ],
    "msg": "Failed events retrieved.",
    "success": 1
}

Status Code: 200


III. Example Request: Session ID Specific

Headers:

Key Value Description
Content-Type application/json

Query:

Key Value Description
session_id feb41b52-a4c2-4726-91c2-9e2f6db631a7

Body:

{
    "auth_session_id": "06c6466b-9c38-4fd3-91c4-73370c941118"
}

III. Example Response: Session ID Specific

{
    "events": [
        {
            "date": "22/03/2023 14:39:54",
            "event": "Incorrect added motion sequence entered.",
            "id": "e1d2a58d-7c1f-4b96-bed7-6c5abf47a6e3",
            "photo": "None",
            "session_id": "feb41b52-a4c2-4726-91c2-9e2f6db631a7"
        }
    ],
    "msg": "Failed events retrieved.",
    "success": 1
}

Status Code: 200


3. Login

Login to the admin dashboard

Endpoint:

Method: POST
Type: RAW
URL: {{hostname}}:{{port}}/api/dashboard/login/

Body:

{
    "email": "email@domain.com",
    "password": "Password1"
}

More example Requests/Responses:

I. Example Request: Successful

Body:

{
    "email": "user@email.com",
    "password": "Password1"
}

I. Example Response: Successful

{
    "auth_session_id": "06c6466b-9c38-4fd3-91c4-73370c941118",
    "msg": "Login successful.",
    "success": 1
}

Status Code: 200


II. Example Request: Invalid Email / Password

Body:

{
    "email": "",
    "password": "Password1"
}

II. Example Response: Invalid Email / Password

{
    "msg": "Invalid email or password, please try again.",
    "success": 0
}

Status Code: 401


III. Example Request: Not Admin User

Body:

{
    "email": "hi@email.com",
    "password": "Password1"
}

III. Example Response: Not Admin User

{
    "msg": "You do not have permission to access the dashboard.",
    "success": 0
}

Status Code: 403


4. Login Sessions

Get a list of the current and past login sessions

Endpoint:

Method: POST
Type: RAW
URL: {{hostname}}:{{port}}/api/dashboard/login_sessions/

Body:

{
    "auth_session_id": "f57ab88c-04f0-4fe2-a026-c405da71d10a"
}

More example Requests/Responses:

I. Example Request: Successful

Body:

{
    "auth_session_id": "06c6466b-9c38-4fd3-91c4-73370c941118"
}

I. Example Response: Successful

{
    "msg": "Login sessions retrieved.",
    "sessions": [
        {
            "auth_stages": "{\"password\": true, \"motion_pattern\": true, \"face_recognition\": true}",
            "date": "29/03/2023 23:18:10",
            "login_photo": "b''",
            "motion_added_sequence": "[\"UP\", \"DOWN\", \"RIGHT\"]",
            "motion_completed": true,
            "session_id": "72fe10be-dead-4011-b61b-d44b1496974a",
            "user_email": "user@email.com",
            "user_id": "693e2954-6eb8-4ec6-8906-7b984e06e32e"
        },
        {
            "auth_stages": "{\"password\": true, \"motion_pattern\": true, \"face_recognition\": true}",
            "date": "29/03/2023 22:14:11",
            "login_photo": "b''",
            "motion_added_sequence": "[\"UP\", \"DOWN\", \"RIGHT\"]",
            "motion_completed": true,
            "session_id": "868643d8-cc42-425b-92dc-a17ad11ffd37",
            "user_email": "user@email.com",
            "user_id": "693e2954-6eb8-4ec6-8906-7b984e06e32e"
        },
        {
            "auth_stages": "{\"password\": true, \"motion_pattern\": true, \"face_recognition\": true}",
            "date": "29/03/2023 21:12:48",
            "login_photo": "b''",
            "motion_added_sequence": "[\"UP\", \"DOWN\", \"RIGHT\"]",
            "motion_completed": true,
            "session_id": "e5698965-8674-41c8-aa60-03712d739318",
            "user_email": "user@email.com",
            "user_id": "693e2954-6eb8-4ec6-8906-7b984e06e32e"
        },
        {
            "auth_stages": "{\"password\": true, \"motion_pattern\": true, \"face_recognition\": true}",
            "date": "29/03/2023 21:10:26",
            "login_photo": "b''",
            "motion_added_sequence": "[\"UP\", \"DOWN\", \"RIGHT\"]",
            "motion_completed": true,
            "session_id": "b62cd4ff-c6a7-42b9-a841-8b7f4abb1a2c",
            "user_email": "user@email.com",
            "user_id": "693e2954-6eb8-4ec6-8906-7b984e06e32e"
        },
        {
            "auth_stages": "{\"password\": true, \"motion_pattern\": true, \"face_recognition\": true}",
            "date": "29/03/2023 13:13:10",
            "login_photo": "b''",
            "motion_added_sequence": "[\"UP\", \"DOWN\", \"RIGHT\"]",
            "motion_completed": true,
            "session_id": "bcaf1f84-244d-493a-b953-34a2a3d9fa7c",
            "user_email": "user@email.com",
            "user_id": "693e2954-6eb8-4ec6-8906-7b984e06e32e"
        },
        {
            "auth_stages": "{\"password\": true, \"motion_pattern\": true, \"face_recognition\": true}",
            "date": "29/03/2023 10:43:28",
            "login_photo": "b''",
            "motion_added_sequence": "[\"UP\", \"DOWN\", \"RIGHT\"]",
            "motion_completed": true,
            "session_id": "654c01c0-e9f8-4f66-a6b3-ac46ba5afeda",
            "user_email": "user@email.com",
            "user_id": "693e2954-6eb8-4ec6-8906-7b984e06e32e"
        },
        {
            "auth_stages": "{\"password\": true, \"motion_pattern\": true, \"face_recognition\": true}",
            "date": "29/03/2023 10:11:39",
            "login_photo": "b''",
            "motion_added_sequence": "[\"UP\", \"DOWN\", \"RIGHT\"]",
            "motion_completed": true,
            "session_id": "de62b5ef-f5a2-43a8-89a2-ff578bd30dac",
            "user_email": "user@email.com",
            "user_id": "693e2954-6eb8-4ec6-8906-7b984e06e32e"
        },
        {
            "auth_stages": "{\"password\": true, \"motion_pattern\": true, \"face_recognition\": true}",
            "date": "24/03/2023 23:20:42",
            "login_photo": "b''",
            "motion_added_sequence": "[\"UP\", \"DOWN\", \"RIGHT\"]",
            "motion_completed": true,
            "session_id": "26005122-bf3f-468c-9b27-cc6307354c7c",
            "user_email": "user@email.com",
            "user_id": "693e2954-6eb8-4ec6-8906-7b984e06e32e"
        },
        {
            "auth_stages": "{\"password\": true, \"motion_pattern\": true, \"face_recognition\": true}",
            "date": "24/03/2023 23:15:34",
            "login_photo": "b''",
            "motion_added_sequence": "[\"UP\", \"DOWN\", \"RIGHT\"]",
            "motion_completed": true,
            "session_id": "e605cb8d-1661-4b5a-a8c2-1274a6db7f7c",
            "user_email": "user@email.com",
            "user_id": "693e2954-6eb8-4ec6-8906-7b984e06e32e"
        },
        {
            "auth_stages": "{\"password\": true, \"motion_pattern\": true, \"face_recognition\": false}",
            "date": "24/03/2023 23:07:01",
            "login_photo": "None",
            "motion_added_sequence": "[\"UP\", \"DOWN\", \"RIGHT\"]",
            "motion_completed": true,
            "session_id": "ecbfe6f8-3cf4-4914-93b7-7f07389e9623",
            "user_email": "user@email.com",
            "user_id": "693e2954-6eb8-4ec6-8906-7b984e06e32e"
        },
        {
            "auth_stages": "{\"password\": true, \"motion_pattern\": true, \"face_recognition\": false}",
            "date": "24/03/2023 22:56:08",
            "login_photo": "None",
            "motion_added_sequence": "[\"UP\", \"DOWN\", \"RIGHT\"]",
            "motion_completed": true,
            "session_id": "4f9f4b33-780d-4067-a2c2-9fc2dc3d2a20",
            "user_email": "user@email.com",
            "user_id": "693e2954-6eb8-4ec6-8906-7b984e06e32e"
        }
    ],
    "success": 1
}

Status Code: 200


II. Example Request: Count Param

Query:

Key Value Description
count 1

Body:

{
    "auth_session_id": "06c6466b-9c38-4fd3-91c4-73370c941118"
}

II. Example Response: Count Param

{
    "msg": "Login sessions retrieved.",
    "sessions": [
        {
            "auth_stages": "{\"password\": true, \"motion_pattern\": true, \"face_recognition\": true}",
            "date": "29/03/2023 23:18:10",
            "login_photo": "b''",
            "motion_added_sequence": "[\"UP\", \"DOWN\", \"RIGHT\"]",
            "motion_completed": true,
            "session_id": "72fe10be-dead-4011-b61b-d44b1496974a",
            "user_email": "user@email.com",
            "user_id": "693e2954-6eb8-4ec6-8906-7b984e06e32e"
        }
    ],
    "success": 1
}

Status Code: 200


Client API

1. Login

a. Email

Endpoint:

Method: POST
Type: RAW
URL: {{hostname}}:{{port}}/api/login/email/

Body:

{
    "data": "email@domain.com"
}

More example Requests/Responses:

I. Example Request: Successful

Body:

{
    "data": "postman@email.com"
}
I. Example Response: Successful
{
    "msg": "Login sequence initialized.",
    "next": "password",
    "session_id": "2c14bef0-6a82-4840-a0f8-3594ca10d141",
    "success": 1
}

Status Code: 200


II. Example Request: Email Doesn't Exist / Bad Formatting

Body:

{
    "data": "axoiwmk@lx.al"
}
II. Example Response: Email Doesn't Exist / Bad Formatting
{
    "msg": "Email not found, please try again.",
    "success": 0
}

Status Code: 401


b. Password

Login step with password entry

Endpoint:

Method: POST
Type: RAW
URL: {{hostname}}:{{port}}/api/login/password/

Body:

{
    "session_id": "4de606fb-fc13-4a79-afb4-19c5d09e416a",
    "data": "Password1"
}

More example Requests/Responses:

I. Example Request: Successful

Body:

{
    "session_id": "2c14bef0-6a82-4840-a0f8-3594ca10d141",
    "data": "Password1"
}
I. Example Response: Successful
{
    "auth_session_id": null,
    "msg": "Password validated.",
    "next": "motion_pattern",
    "success": 1
}

Status Code: 200


II. Example Request: Wrong Password

Body:

{
    "session_id": "130b4213-719c-4964-b852-e023d3eacccb",
    "data": "This1smypassword"
}
II. Example Response: Wrong Password
{
    "msg": "Invalid password, please try again.",
    "success": 0
}

Status Code: 401


c. Unique Pico ID

Check the uniqueness of a Pico ID generated

Endpoint:

Method: POST
Type: RAW
URL: {{hostname}}:{{port}}/api/login/motion_pattern/unique/

Body:

{
    "pico_id": "130b4213-719c-4964-b852-e023d3eacccb"
}

More example Requests/Responses:

I. Example Request: Unique

Body:

{
    "pico_id": "2c14bef0-6a82-4840-a0f8-3594ca10d141"
}
I. Example Response: Unique
{
    "msg": "Pico ID is unique.",
    "success": 1
}

Status Code: 200


II. Example Request: Non-Unique

Body:

{
    "pico_id": "130b4213-719c-4964-b852-e023d3eacccb"
}
II. Example Response: Non-Unique
{
    "msg": "Pico ID is not unique.",
    "success": 0
}

Status Code: 400


d. Motion Pattern Initialize

Initiate login step with motion device password

Endpoint:

Method: POST
Type: RAW
URL: {{hostname}}:{{port}}/api/login/motion_pattern/initialize/

Body:

{
    "session_id": "265f92ae-02e5-44d3-b5ae-b3a22d30f924",
    "pico_id": "100b4213-719c-4964-b852-e023d3eacccb",
    "data": [
        "UP", "DOWN"
    ]
}

More example Requests/Responses:

I. Example Request: Successful

Body:

{
    "session_id": "2c14bef0-6a82-4840-a0f8-3594ca10d141",
    "pico_id": "130b4213-719c-4964-b852-e023d3eacccb",
    "data": [
        "UP", "DOWN", "RIGHT"
    ]
}
I. Example Response: Successful
{
    "auth_session_id": null,
    "msg": "Motion pattern validated.",
    "next": "face_recognition",
    "success": 1
}

Status Code: 200


II. Example Request: Expired Session

Body:

{
    "session_id": "2c14bef0-6a82-4840-a0f8-3594ca10d141",
    "pico_id": "",
    "data": [
        "UP", "DOWN", "RIGHT"
    ]
}
II. Example Response: Expired Session
{
    "msg": "Session expired, please start a new login session.",
    "next": "email",
    "success": 0
}

Status Code: 401


III. Example Request: Wrong Stage

Body:

{
    "session_id": "25e2bf8f-ae6d-4f06-8c39-e48c887af856",
    "pico_id": "120b4213-719c-4964-b852-e023d3eacccb",
    "data": [
        "UP", "DOWN", "RIGHT"
    ]
}
III. Example Response: Wrong Stage
{
    "msg": "Wrong stage of login sequence, please go to specified stage.",
    "next": "password",
    "success": 0
}

Status Code: 400


IV. Example Request: Incorrect Pattern

Body:

{
    "session_id": "25e2bf8f-ae6d-4f06-8c39-e48c887af856",
    "pico_id": "120b4213-719c-4964-b852-e023d3eacccb",
    "data": [
        "UP", "DOWN", "RIGHT"
    ]
}
IV. Example Response: Incorrect Pattern
{
    "msg": "Motion pattern incorrect, please retry.",
    "success": 0
}

Status Code: 401


e. Motion Pattern Validate

Motion device password submission endpoint

Endpoint:

Method: POST
Type: RAW
URL: {{hostname}}:{{port}}/api/login/motion_pattern/validate/

Body:

{
    "pico_id": "100b4213-719c-4964-b852-e023d3eacccb",
    "data": [
        "LEFT", "RIGHT", "UP", "FLIP", "UP", "DOWN"
    ]
}

More example Requests/Responses:

I. Example Request: Incorrect Pattern

Body:

{
    "pico_id": "120b4213-719c-4964-b852-e023d3eacccb",
    "data": [
        "LEFT", "RIGHT", "UP", "DOWN", "UP", "DOWN"
    ]
}
I. Example Response: Incorrect Pattern
{
    "msg": "Incorrect motion pattern, please try again.",
    "success": 0
}

Status Code: 401


II. Example Request: Successful

Body:

{
    "pico_id": "110b4213-719c-4964-b852-e023d3eacccb",
    "data": [
        "LEFT", "RIGHT", "UP", "DOWN", "UP", "DOWN", "RIGHT"
    ]
}
II. Example Response: Successful
{
    "msg": "Motion pattern validated.",
    "success": 1
}

Status Code: 200


f. Face Recognition

Login step with face recognition

Endpoint:

Method: POST
Type: FORMDATA
URL: {{hostname}}:{{port}}/api/login/face_recognition/

Body:

Key Value Description
request {"session_id": "a8956a59-8759-408d-8b7f-e74cfe213083"}
photo

More example Requests/Responses:

I. Example Request: Successful

Body:

Key Value Description
request {"session_id": "2c14bef0-6a82-4840-a0f8-3594ca10d141"}
photo
I. Example Response: Successful
{
    "auth_session_id": "e78ace29-54c7-4dfa-baa9-815d6288e5c6",
    "msg": "Face recognition validated.",
    "next": null,
    "success": 1
}

Status Code: 200


II. Example Request: Missing Photo

Body:

Key Value Description
request {"session_id": "6f445663-3bc6-49b2-bf97-3fa0c5f5e2d9"}
II. Example Response: Missing Photo
{
    "msg": "No photo submitted, please try again.",
    "success": 0
}

Status Code: 400


2. Files

a. Upload File

Upload a file to the authenticated client's account

Endpoint:

Method: POST
Type: FORMDATA
URL: {{hostname}}:{{port}}/api/client/files/upload/

Body:

Key Value Description
request 
{
    "auth_session_id": "6a8dc068-f2da-4afe-bb0e-0b03ab899fe3",
    "file_name": "Example File"
}
file fileName.extension

More example Requests/Responses:

I. Example Request: Successful

Body:

Key Value Description
request 
{
    "auth_session_id": "3e2dd9ab-03dd-4f8f-9b0d-80e77c35fc78",
    "file_name": "picture"
}
file photo.jpg
I. Example Response: Successful
{
    "msg": "File upload successful.",
    "success": 1
}

Status Code: 200


II. Example Request: Invalid ID

Body:

Key Value Description
request 
{
    "auth_session_id": "b62cd4ff-c6a7-42b9-a841-8b7f4abb1a2c",
    "file_name": "picture"
}
file file.txt
II. Example Response: Invalid ID
{
    "msg": "Invalid auth_session_id, please try again.",
    "success": 0
}

Status Code: 401


III. Example Request: Wrong Body Type

Body:

{
    "auth_session_id": "3e2dd9ab-03dd-4f8f-9b0d-80e77c35fc78"
}
III. Example Response: Wrong Body Type
{
    "msg": "Missing multipart form data in request.",
    "success": 0
}

Status Code: 400


IV. Example Request: Duplicate File Name

Body:

Key Value Description
request 
{
    "auth_session_id": "3e2dd9ab-03dd-4f8f-9b0d-80e77c35fc78",
    "file_name": "picture"
}
file file.txt
IV. Example Response: Duplicate File Name
{
    "msg": "File name already exists.",
    "success": 0
}

Status Code: 400


b. List Files

List the files on the authenticated client's account

Endpoint:

Method: POST
Type: RAW
URL: {{hostname}}:{{port}}/api/client/files/list/

Body:

{
    "auth_session_id": "6a8dc068-f2da-4afe-bb0e-0b03ab899fe3"
}

More example Requests/Responses:

I. Example Request: Successful

Body: None

I. Example Response: Successful
{
    "json": [
        {
            "date": "2023-03-29 22:50:13",
            "file_name": "picture",
            "file_type": "image/jpeg",
            "id": "aa35b09c-ddec-425f-acf4-442ead625aeb",
            "size": 1859839
        },
        {
            "date": "2023-03-29 22:50:24",
            "file_name": "picture2",
            "file_type": "image/jpeg",
            "id": "7093be37-dd7e-48e4-b0bd-33da2731eb4b",
            "size": 1397795
        }
    ],
    "msg": "File fetch successful.",
    "success": 1
}

Status Code: 200


c. File Download

Download a file from the authenticated client's account

Endpoint:

Method: POST
Type: RAW
URL: {{hostname}}:{{port}}/api/client/files/download/

Body:

{
    "auth_session_id": "dcec7f7b-64ab-4581-911f-8c2e458c4269",
    "file_id": "aa56d109-ee59-401f-84dd-ac386d28c3ac"
}

d. Delete File

Delete a file on the authenticated client's account

Endpoint:

Method: POST
Type: RAW
URL: {{hostname}}:{{port}}/api/client/files/delete/

Body:

{
    "auth_session_id": "6a8dc068f2da4afebb0e0b03ab899fe3",
    "file_id": "aa35b09c-ddec-425f-acf4-442ead625aeb"
}

3. Index

Index route of the API

Endpoint:

Method: GET
Type: 
URL: {{hostname}}:{{port}}/api/

More example Requests/Responses:

I. Example Request: Success

Body: None

I. Example Response: Success

Hello, world!

Status Code: 200


4. Signup

Client sign-up endpoint

Endpoint:

Method: POST
Type: FORMDATA
URL: {{hostname}}:{{port}}/api/signup/

Body:

Key Value Description
request 
{
    "email": "email@domain.com",
    "password": "Password1",
    "motion_pattern": ["LEFT", "RIGHT", "UP", "DOWN"],
    "auth_methods": {
        "password": true,
        "motion_pattern": true,
        "face_recognition": true
    }
}
photo photo.png

More example Requests/Responses:

I. Example Request: Successful

Body:

Key Value Description
request 
{
    "email": "postman@email.com",
    "password": "Password1",
    "motion_pattern": ["LEFT", "RIGHT", "UP", "DOWN"],
    "auth_methods": {
        "password": true,
        "motion_pattern": true,
        "face_recognition": true
    }
}
photo photo.png

I. Example Response: Successful

{
    "msg": "User successfully created.",
    "success": 1
}

Status Code: 200


II. Example Request: Require An Auth Method

Body:

Key Value Description
request 
{
    "email": "postman-fail@email.com",
    "password": "Password1",
    "motion_pattern": ["LEFT", "RIGHT", "UP", "DOWN"],
    "auth_methods": {
        "password": false,
        "motion_pattern": false,
        "face_recognition": false
    }
}
photo photo.png

II. Example Response: Require An Auth Method

{
    "msg": "Error: At least one auth method must be enabled. User not created.",
    "success": 0
}

Status Code: 400


III. Example Request: Duplicate Email

Body:

Key Value Description
request 
{
    "email": "postman@email.com",
    "password": "Password1",
    "motion_pattern": ["LEFT", "RIGHT", "UP", "DOWN"],
    "auth_methods": {
        "password": false,
        "motion_pattern": true,
        "face_recognition": false
    }
}
photo

III. Example Response: Duplicate Email

{
    "msg": "Error: Provided email is already in use. User not created.",
    "success": 0
}

Status Code: 400


IV. Example Request: Missing Password (When Enabled)

Body:

Key Value Description
request 
{
    "email": "postman-fail@email.com",
    "motion_pattern": ["LEFT", "RIGHT", "UP", "DOWN"],
    "auth_methods": {
        "password": true,
        "motion_pattern": true,
        "face_recognition": true
    }
}
photo photo.png

IV. Example Response: Missing Password (When Enabled)

{
    "msg": "Error: Password not provided. User not created.",
    "success": 0
}

Status Code: 400


V. Example Request: Missing Motion Pattern (When Enabled)

Body:

Key Value Description
request 
{
    "email": "postman-fail@email.com",
    "password": "Password1",
    "auth_methods": {
        "password": true,
        "motion_pattern": true,
        "face_recognition": true
    }
}
photo photo.png

V. Example Response: Missing Motion Pattern (When Enabled)

{
    "msg": "Error: Motion pattern not provided. User not created.",
    "success": 0
}

Status Code: 400


VI. Example Request: Missing Photo (When Enabled)

Body:

Key Value Description
request 
{
    "email": "postman-fail@email.com",
    "password": "Password1",
    "motion_pattern": ["LEFT", "RIGHT", "UP", "DOWN"],
    "auth_methods": {
        "password": true,
        "motion_pattern": true,
        "face_recognition": true
    }
}
photo

VI. Example Response: Missing Photo (When Enabled)

{
    "msg": "Error: No photo submitted. User not created.",
    "success": 0
}

Status Code: 400


VII. Example Request: Invalid Motion Pattern

Body:

Key Value Description
request 
{
    "email": "postman-fail@email.com",
    "password": "Password1",
    "motion_pattern": ["left", "RIGHT", "UP", "DOWN"],
    "auth_methods": {
        "password": true,
        "motion_pattern": true,
        "face_recognition": false
    }
}
photo

VII. Example Response: Invalid Motion Pattern

{
    "msg": "Error: Invalid motion pattern. User not created.",
    "success": 0
}

Status Code: 400


5. Check Login

Check the validity of a session token

Endpoint:

Method: POST
Type: RAW
URL: {{hostname}}:{{port}}/api/client/validate/

Body:

{
    "auth_session_id": "121a9cd7e3b540f396c0936bd22a1a8c"
}

More example Requests/Responses:

I. Example Request: Invalid ID

Body:

{
    "auth_session_id": "a48b506f-c58d-4c72-b826-8b2db8376816"
}

I. Example Response: Invalid ID

{
    "msg": "Invalid auth_session_id, please try again.",
    "success": 0
}

Status Code: 401


II. Example Request: Valid ID

Body:

{
    "auth_session_id": "e78ace29-54c7-4dfa-baa9-815d6288e5c6"
}

II. Example Response: Valid ID

{
    "msg": "Auth session ID is valid.",
    "success": 1
}

Status Code: 200


III. Example Request: Expired Session / Logged Out

Body:

{
    "auth_session_id": "9122b7bbd56147b1a1a99c522c4350f0"
}

III. Example Response: Expired Session / Logged Out

{
    "msg": "Session expired, please start a new login session.",
    "next": "email",
    "success": 0
}

Status Code: 401


6. Logout

Logout the authenticated client

Endpoint:

Method: POST
Type: RAW
URL: {{hostname}}:{{port}}/api/client/logout

Body:

{
    "auth_session_id": "9522b7bbd56147b1a1a99c522c4350f0"
}

More example Requests/Responses:

I. Example Request: Successful

Body:

{
    "auth_session_id": "9122b7bbd56147b1a1a99c522c4350f0"
}

I. Example Response: Successful

{
    "msg": "Logout successful.",
    "success": 1
}

Status Code: 200


II. Example Request: Invalid ID

Body:

{
    "auth_session_id": "9522b7bbd56147b1a1a99c522c4350f0"
}

II. Example Response: Invalid ID

{
    "msg": "Invalid auth_session_id, please try again.",
    "success": 0
}

Status Code: 401


Pico API

API of the Pico device (not in the backend)

1. Set Pico ID

Set the unique identifier for the Pico's requests

Endpoint:

Method: POST
Type: RAW
URL: http://192.168.137.159/pico_id

Body:

{
    "pico_id": "9522b7bbd56147b1a1a99c522c4350f0"
}

Back to top