<aside> ❗ Use this guide to start with Suprema CLUe APIs and make your integration simple & easy. The APIs work with Suprema CLUe web portal settings, so if you don’t have a CLUe web portal account, please request one first.

</aside>

Before Start

What is API Key?

API key is necessary to call CLUe API. And it can be obtained from the place group admin menu. CLUe requests API Token as mandory for its request header as bearer token. canThis API key can be issued and managed from CLUe Webportal. https://clue.moon.supremainc.com/login

In order to sign up, you need to be invited by an upper-level admin or an admin user from the same place group.

<aside> 💡

What is Place & Place Group?

Since CLUe supports a multi-tenant system, a Place refers to each independent unit, such as a company or branch, while a Place Group is a higher-level concept that manages a group of multiple Places.

</aside>

How to issue a API Key?

After logging in, the place group panel is shown as below according to your admin level. Please click a place group to move, and click the more button on the top right.

Then, you can see the below, and click “Settings” to move to the “Place Group Setting Menu”.

Among the menu, please choose “Admin” as below.

At the admin menu, check “Manage API Keys” menu and click “+Add new api key”

Then, you can set validity period from 1/2/3 Year or up to 365,000 days. And click “Add” button to issue a new API key.

Then, the new API key is generated. You can click “Copy” button and use it as bearer token to call CLUe APIs.

<aside> ❗

If you are not allowed to access the content of the “Place Group” admin menu, you must have branch or distribution admin-level permissions. Due to privacy protection laws, access to personal data is restricted by default.

Therefore, it’s necessary to be invited as a “Place Group Admin.” However, since this can mean that the customer opens its API key to your side, it should be done only when absolutely necessary, with the customer's acknowledgment and approval.

Suprema is not liable for any misuse of the API key resulting from this approach.

</aside>

CLUe API Basic

Base URL

The base URL for sending all API requests is https://api.moon.supremainc.com/v1 All API requests must be made over HTTPS.

The CLUe API follows RESTful principles as much as possible, performing most operations through GET, POST, PATCH, and DELETE requests for page and database resources. The request and response bodies are encoded in JSON.

API Success Response

In the case of a successful response, the following status is returned.

Http status code

200

API Fail Response

In the case of a failed response, one of the following statuses is returned.

Http status code

400

500

General Error Code

API Limit

<aside> ⚠️

CLUe has a API call traffic limit for 300 per 5 minutes for each APIs. This is per source base. But, when it comes to add faces, it’s recommened to give some sleep time between calls considering time-needed tasks such as template extraction and creation.

</aside>

How to create a user and manage a face

In order to enroll faces, a face-supported Suprema device must be added to your place, and a door must be configured for use through the CLUe web portal.

After that, you can call the face enrollment API, targeting a placeId with the appropriate “auth” details.

• “user” refers to CLUe’s internal management for global user administration.
• “auth” includes credentials such as face images and card IDs, which are specific to the given place.

For API usage, only "auth" is typically used, following the place-specific user management concept.

User Create & Face Enroll API

curl --location POST '<https://api.moon.supremainc.com/v1/places/{{placeId}>}/auths'\\
--header 'Content-Type: application/json' \\
--header 'Authorization: Bearer {{apiKey}}\\
--data '{
    "user": {
		"key": "{{uniqueKey for each user}}" 
// this is required for your internal name, and this should be globally unique. Please input your company initial as prefix. 
// Please follow the user key restriction rule! 
// length: 1 ~ 64 or less
// letters: Combination of lowercase English letters and numbers
// Allowed Special letters:   -, _ , @, . 
},
    "auth": {
        "startTime": 1690853501093,  // Access allow start period 
        "endTime": 2147353200000, // Access allow end period. Please do not exceed this value since the device has max time limit, Feb 2038. 
        "doorAccessType": "ALL_DOOR", //if specific door sync required, please set “SPECIFIC” and add doorId key value like “doorIds” : [1, 2], 
        "scheduleType": "ALWAYS", //if specific weekday schedule limit required, please remove this field and create schedule from webportal and set like “scheduleId” : 1 
        "credentials": {
            "name": "test12345678" //if name is entered, it will be shown on the device display. 
            "faceImages": [
             "{{base64 encoded face image}}" //Up to two faces allowed 
            ],
        },
        "activeStatus": "ACTIVE" //this field is mandatory. If you want to disable, you can change it inactive
    }
}'

• Header request

• Path parameters

| --- | --- |

<aside> ❗

</aside>

• Response

{
    "code": 200,
    "status": true,
    "message": "OK",
    "data": {
        "authId": 48363,  // this will be used for auth modify/delete case
        "lastModifiedAt": 1700721664157,
        "user": {
            "userId": 44285, 
            "key": "yourcompanyname.1234",
            "name": "test12345678",
            "realNameAuthStatusType": "REAL_NAME_AUTH_BEFORE"
        },
        "auth": {
            "startTime": 1690853501093,
            "endTime": 2147353200000,
            "doorAccessType": "ALL_DOOR",
            "scheduleType": "ALWAYS",
            "credentials": {
                "modes": ["FACE"],
                "name": "test12345678",
								"faceImages": ["{{faceImageData}}"]
            },
            "activeStatus": "ACTIVE"
        }
    }
}

<aside> ❗

</aside>

• Error Response

{
    "errors": [
        {
            "code": "f1000",
            "message": "",
        }
    ]
}

| --- | --- |

How to check duplicated Face before enroll to the CLUe server.

<aside> ⚠️

</aside>

Get FaceMatching Support Device List from the place

GET /v1/devices/face-matchable?placeId={{placeId}} HTTP/1.1
Host: [api.moon.supremainc.com](<http://api.moon.supremainc.com/>)
Authorization: Bearer {{apiKey}}

• Response

{
    "code": 200,
    "status": true,
    "message": "OK",
    "data": [
        {
            "deviceId": 1454,
            "deviceName": "BS3_APWB-538159106",
            "deviceSerial": "538159106",
            "deviceType": "BioStation3"
        }
    ]
}

Device FaceMatching Request

Ask to the sever to arrange the designated device to conduct a face matching.

POST /v1/devices/{{deviceId}}/match-face HTTP/1.1
Host: [api.moon.supremainc.com](<http://api.moon.supremainc.com/>)
Content-Type: application/json
Authorization: Bearer {{apiKey}}
{
  "base64Image": "base64_converted_facephoto"
}