IoT Access Control Gates (Web)

HTTP API (Convex HTTP Actions)

These endpoints are implemented in src/backend/http.ts using Convex HTTP Actions.

Common error format

Some endpoints return validation errors in the following shape:

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "..."
  }
}

Endpoints

POST /entry-access

Checks whether an RFID holder is allowed to pass a gate in a given direction, records an entry attempt, and (on success) updates the user status.

Request JSON body

{
  "rfid": "string",
  "gateIdentifier": "string",
  "direction": "in" | "out"
}

Responses

• 200 OK

  • Success:

    { "success": true }

• Error responses (shape):

  {
    "success": false,
    "error": {
      "code": "USER_NOT_FOUND" | "USER_BANNED" | "USER_ALREADY_IN" | "USER_ALREADY_OUT" | "GATE_NOT_FOUND" | "GATE_INACTIVE" | "BAD_REQUEST" | "...",
      "message": "string"
    }
  }

Status codes for known domain errors

• 404 for USER_NOT_FOUND, GATE_NOT_FOUND
• 403 for USER_BANNED
• 409 for USER_ALREADY_IN, USER_ALREADY_OUT
• 423 for GATE_INACTIVE
• 400 for request validation failures (BAD_REQUEST)
• 500 for unknown failures

GET /users/without-rfid

Lists users that do not have an RFID assigned.

Response

• 200 OK

{
  "users": [
    {
      "_id": "<convex doc id>",
      "_creationTime": 0,
      "name": "string",
      "status": "in" | "out",
      "isBanned": false
    }
  ]
}

Notes:

• Convex documents include system fields like _id and _creationTime.
• The rfid field is optional in the schema; when absent it will not be present in the JSON.

POST /users/assign-rfid

Assigns (or clears) an RFID value on a user.

Request JSON body

{
  "userId": "string",
  "rfid": "string"
}

Notes:

• userId is expected to be a Convex document id for the users table.
• If you pass an empty/whitespace rfid, it is normalized to undefined by the server; this can be used to clear the RFID depending on Convex patch semantics.

Responses

• 200 OK

{ "success": true }

• 400 Bad Request (validation error) uses the common error format.