Device Bans API
Manage and enforce hardware-level device bans for your project. Ban malicious devices by their
hardware-bound unique ID, and revoke bans when necessary.
?? Critical Developer Disclaimer
Bans are a one-time receipt: Developers are required to keep track of the returned
ban-id values on their own database if they wish to revoke (unban) a device in the
future. The ban-id is returned only once at the time of ban execution and cannot be
retrieved from Kubian's server later. All bans are made to expired after 7 days (168
hours) from the time they are executed. Unless the ban_time_in_hours is
set to a higher or lower value from the ban request.
1. Ban Device
Bans a specific device from accessing your application. The device's unique_id must exist in
your project's associated device list before a ban can be placed.
Endpoint
POST /platform_integrity/ban_device
Headers
| Header |
Value |
Description |
Authorization |
OA|{project-app-id}|{project-app-secret} |
OAuth style authorization for your project combining the prefix OA, your App Id, and your App
Secret separated by a pipe character. |
Content-Type |
application/json |
Must be set to JSON. |
JSON Body
| Field |
Type |
Description |
unique_id |
string |
The unique device identifier generated by the client and returned in attestation responses. |
ban_time_in_hours |
int |
(optional) The duration of the ban in hours (default is 168 hours, or 7 days if
ban_time_in_hours is not provided in request). Ban duration is capped at 1 year (365 days, or
8760 hours). unique_ids rotate every 60 days. Once the unique_id has been rotated, the ban will
be effectively lifted to protect user privacy. |
Responses
| Status |
Scenario |
Response Body |
| 200 OK |
Success |
{
"message": "Device Device-Unique-ID: has been banned",
"ban-id": "ban_id_12345678abcdef"
} |
| 400 Bad Request |
Missing or invalid JSON body, or missing unique_id. |
{"message": "Missing unique_id"} or {"message": "Missing JSON body"}
|
| 401 Unauthorized |
Missing or incorrect Authorization header details. |
{"message": "Unable to find project. Please make sure the Authorization header has the correct project credentials."}
|
| 404 Not Found |
The device unique ID is not associated with this project. |
{"message": "Failed to ban Device-Unique-ID: Unique ID not found in project list"}
|
| 409 Conflict |
The device is already banned under an active policy. |
{"message": "Device Device-Unique-ID is already banned"} |
2. Unban Device
Revokes an active ban on a device. Requires both the device's unique_id and the unique
ban_id receipt generated when the ban was created.
Endpoint
POST /platform_integrity/unban_device
Headers
| Header |
Value |
Description |
Authorization |
OA|{project-app-id}|{project-app-secret} |
OAuth style authorization for your project combining the prefix OA, your App Id, and your App
Secret separated by a pipe character. |
Content-Type |
application/json |
Must be set to JSON. |
JSON Body
| Field |
Type |
Description |
unique_id |
string |
The unique device identifier being unbanned. |
ban_id |
string |
The one-time ban receipt ID (with or without the ban_id_ prefix). |
Responses
| Status |
Scenario |
Response Body |
| 200 OK |
Success |
{
"message": "Device Device-Unique-ID: has been unbanned",
"purged-ban-id": "ban_id_12345678abcdef"
} |
| 400 Bad Request |
Missing required fields (unique_id or ban_id). |
{"message": "Missing ban_id"} or {"message": "Missing unique_id"} |
| 401 Unauthorized |
Missing or incorrect Authorization header details. |
{"message": "Unable to find project. Please make sure the Authorization header has the correct project credentials."}
|
| 403 Forbidden |
The provided unique_id does not match the record associated with that
ban_id. |
{"message": "Failed to unban Device-Unique-ID: unique_id does not match the provided ban_id"}
|
| 404 Not Found |
The ban record or project was not found. |
{"message": "Failed to unban Device-Unique-ID: ban_id not found"} |
3. List Banned Devices
Retrieves an object containing all currently active hardware bans linked to your project. Expired bans
are automatically omitted during retrieval. For data exposure minimization, the generated
ban-id values are securely masked to their first 5 hex characters.
Endpoint
POST /platform_integrity/user/list_bans
Headers
| Header |
Value |
Description |
Authorization |
OA|{project-app-id}|{project-app-secret} |
OAuth style authorization for your project combining the prefix OA, your App Id, and your App
Secret separated by a pipe character. |
Content-Type |
application/json |
Must be set to JSON. |
JSON Body
No request body parameters are necessary for this query.
Responses
| Status |
Scenario |
Response Body |
| 200 OK |
Success |
{
"entries": {
"unique-id-example-1": {
"ban-id": "ban_id_12345...",
"ban_time_remaining": 167.95
}
}
} |
| 401 Unauthorized |
Missing or incorrect Authorization header details. |
{"message": "Unable to find project. Please make sure the Authorization header has the correct project credentials."}
|
4. Device Ban Status
Queries the operational ban state of a hardware unique ID within your project environment. If the device
has an active restriction, details regarding deployment timestamps and precise hour timelines remaining
are parsed dynamically.
Endpoint
POST /platform_integrity/user/device_ban_status
Headers
| Header |
Value |
Description |
Authorization |
OA|{project-app-id}|{project-app-secret} |
OAuth style authorization for your project combining the prefix OA, your App Id, and your App
Secret separated by a pipe character. |
Content-Type |
application/json |
Must be set to JSON. |
JSON Body
| Field |
Type |
Description |
unique_id |
string |
The hardware unique device identifier to search against active policy registers. |
Responses
| Status |
Scenario |
Response Body |
| 200 OK |
Success (Device cleanly authorized) |
{
"banned": false,
"message": "Device Device-Unique-ID: No active bans found for this Unique ID.",
"success": true
} |
| 200 OK |
Success (Device matching active ban policy) |
{
"details": {
"ban_id": "ban_id_12345",
"ban_time_remaining_hours": 167.95,
"banned_at": "2026-05-21T16:53:27",
"expires_at": "2026-05-28T16:53:27",
"unique_id": "Device-Unique-ID"
},
"banned": true,
"success": true
} |
| 400 Bad Request |
Missing request validation components or missing unique_id parameter. |
{"message": "Missing unique_id"} or {"message": "Missing JSON body"}
|
| 401 Unauthorized |
Faulty or missing core Authorization header. |
{"message": "Missing Authorization header"} or
{"message": "Unable to find project. Please make sure the Authorization header has the correct project credentials."}
|
| 404 Not Found |
Unique ID context or project assignment maps to nothing in records. |
{"message": "Failed to find ban status for Device-Unique-ID: Unique ID does not match any of the associated devices with this project"}
|
5. Get Ban Details
Queries granular tracking metrics and timestamps associated with a specific restriction record. To
guarantee alignment with Section 3 of the Privacy Policy (Administrative Isolation & Masking), this
endpoint strictly requires the exact, full unmasked ban receipt ID. Masked or truncated
entries will be rejected to eliminate lookup guessing or reverse-engineering exposures.
Endpoint
POST /platform_integrity/user/ban_details
Headers
| Header |
Value |
Description |
Authorization |
OA|{project-app-id}|{project-app-secret} |
OAuth style authorization for your project combining the prefix OA, your App Id, and your App
Secret separated by a pipe character. |
Content-Type |
application/json |
Must be set to JSON. |
JSON Body
| Field |
Type |
Description |
ban_id |
string |
The exact, full unmasked ban identifier token received upon initial creation (e.g.,
ban_id_12345678abcdef). Partial strings or 5-character masked tokens are strictly
rejected. |
Responses
| Status |
Scenario |
Response Body |
| 200 OK |
Success (Ban profile found successfully) |
{
"success": true,
"details": {
"unique_id": "Device-Unique-ID",
"ban_id_masked": "ban_id_12345",
"ban_id_full": "ban_id_12345678abcdef",
"banned_at": "2026-05-21T16:53:27",
"expires_at": "2026-05-28T16:53:27",
"is_active": true,
"ban_time_remaining_hours": 167.95
}
} |
| 400 Bad Request |
Missing JSON body parameter or missing ban_id field. |
{"message": "Missing ban_id"} or {"message": "Missing JSON body"} |
| 401 Unauthorized |
Invalid or missing core project tokens inside Authorization header. |
{"message": "Unable to find project. Please make sure the Authorization header has the correct project credentials."}
|
| 404 Not Found |
No active ban record matches the provided unmasked identifier within the project space. |
{"success": false, "message": "Failed to find ban details: Invalid or unrecognized ban_id for this project."}
|