{"id":22356190,"url":"https://github.com/bioid-gmbh/bwstools","last_synced_at":"2025-07-30T10:32:13.120Z","repository":{"id":263966158,"uuid":"871182013","full_name":"BioID-GmbH/BWSTools","owner":"BioID-GmbH","description":"BWS 3: Useful Tools for BWS (BWS command-line interface and JWT)","archived":false,"fork":false,"pushed_at":"2024-12-04T08:39:41.000Z","size":26,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-12-04T09:35:19.491Z","etag":null,"topics":["bioid","bws-3","cli","dotnet","jwt"],"latest_commit_sha":null,"homepage":"https://developer.bioid.com/bws/bwstools","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BioID-GmbH.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-11T12:38:53.000Z","updated_at":"2024-12-04T08:39:45.000Z","dependencies_parsed_at":"2024-11-21T10:15:29.200Z","dependency_job_id":null,"html_url":"https://github.com/BioID-GmbH/BWSTools","commit_stats":null,"previous_names":["bioid-gmbh/bwstools"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BioID-GmbH%2FBWSTools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BioID-GmbH%2FBWSTools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BioID-GmbH%2FBWSTools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BioID-GmbH%2FBWSTools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BioID-GmbH","download_url":"https://codeload.github.com/BioID-GmbH/BWSTools/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228124659,"owners_count":17873170,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bioid","bws-3","cli","dotnet","jwt"],"created_at":"2024-12-04T14:09:30.314Z","updated_at":"2025-07-30T10:32:13.109Z","avatar_url":"https://github.com/BioID-GmbH.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BWSTools\n\nBWSTools is a command-line tool for interacting with the **BioID Web Service 3 (BWS 3)**. It includes:\n\n- **BWS CLI**: A CLI tool for calling BWS 3 APIs.\n- **JWT**: A helper tool to generate JWT tokens for BWS 3 authentication.\n\n## 📋 Table of Contents\n\n- [BWS CLI](#bwscli)\n  - [Usage](#usage)\n  - [Commands](#commands)\n    - [gRPC API](#grpc)\n      - [livedetect](#livedetect)\n      - [videolivedetect](#videolivedetect)\n      - [photoverify](#photoverify)\n    - [Face Recognition API](#facerecognition)\n      - [enroll](#enroll)\n      - [verify](#verify)\n      - [search](#search)\n      - [settags](#settags)\n      - [gettemplate](#gettemplate)\n      - [deletetemplate](#deletetemplate)      \n- [JWT Tool](#jwt)\n\n\u003ch2 id=\"bwscli\"\u003e🧪 BWS CLI\u003c/h2\u003e\nThis is a simple command-line tool for the BioID Web Service, designed to easily test BWS 3 installations.\nTo use the BWS CLI tool and successfully call BWS APIs, you will need:\n\n- the corresponding **Client ID**, and\n- the **base64-encoded client key (JWT Token)**.\n\nIf you do not already have these credentials, the [JWT](#jwt) explains in detail how to generate a suitable token.\n\u003ch4 id=\"usage\"\u003eUsage\u003c/h4\u003e\n\nThe general syntax for running the bws cli tool is:\n```bash\nbws [command] [options]\n```\n\u003ch4 id=\"commands\"\u003e📚 Commands\u003c/h4\u003e\nThe CLI tool supports the following commands:\n\n- **`healthcheck`**: Call the health check API. The HealthCheck API provides real-time health status of the BWS service API.\n\n    | Options           | Description                                | Required |\n    |-------------------|--------------------------------------------|----------|\n    | `--host`          | URL of the BWS to call                     | ✅ Yes      |\n    | `--rest` `-r`     | Use RESTful API call (instead of gRPC)     | ❌ No       |\n    | `--verbosity` `-v`| The output verbosity mode [default: Normal] (Detailed, Diagnostic, Minimal, Normal, Quiet) | ❌ No       |\n\n    Examples:\n    + gRPC healthcheck:\n    ```bash\n    bws healthcheck --host https://bwsapiendpoint\n    ```\n    + RESTful healthcheck:\n    ```bash\n    bws healthcheck --rest --host https://bwsapiendpoint\n    ```\n\u003ch3 id=\"grpc\"\u003egRPC API (LivenessDetection, VideoLivenessDetection, PhotoVerify)\u003c/h3\u003e\n\n- \u003ch4 id=\"livedetect\"\u003elivedetect\u003c/h4\u003e\n\n   Call the LivenessDetection API, requiring one (passive live detection) or two (active live detection) live images.\n\n    | Arguments         | Description                                                                         |\n    |-------------------|-------------------------------------------------------------------------------------|\n    | `files`           | List of image files to process.\n\n    | Options           | Description                                                              | Required |\n    |-------------------|--------------------------------------------------------------------------|----------|\n    | `--host`          | URL of the BWS to call                                                   | ✅ Yes      |\n    | `--clientid`      | Your BWS Client Identifier                                               | ✅ Yes      |\n    | `--key`           | Your base64 encoded signing key                                          | ✅ Yes      |\n    | `--challenge`     | Optional head motion direction for the challenge response liveness detection mode (right, left, up, down). Requires two live images  | ❌ No       |\n    | `--rest` `-r`     | Use RESTful API call (instead of gRPC)                                   | ❌ No       |\n    | `--deadline` `-d` | Optional deadline for the call in milliseconds (gRPC only)               | ❌ No       |\n    | `--verbosity` `-v`| The output verbosity mode [default: Normal] (Detailed, Diagnostic, Minimal, Normal, Quiet) | ❌ No       |\n\n      Examples:\n    + Passive liveness detection with *diagnostic* output level:\n    ```bash\n    bws livedetect --host https://bwsapiendpoint -v Diagnostic yourfilepath --clientid yourbwsclientid --key yourbwssecret\n    ```\n    + Active liveness detection via RESTful API:\n    ```bash\n    bws livedetect --host https://bwsapiendpoint --rest yourfilepath1 yourfilepath2 --clientid yourbwsclientid --key yourbwssecret\n    ```\n---\n- \u003ch4 id=\"videolivedetect\"\u003evideolivedetect\u003c/h4\u003e\n\n    Call the VideoLivenessDetection API to analyze a video file and detect if the content contains a live subject.\n\n    | Arguments       | Description                                                                       |\n    |-----------------|-----------------------------------------------------------------------------------|\n    | `video`         | video file to process\n   \n    | Options           | Description                                                          | Required |\n    |-------------------|----------------------------------------------------------------------|----------|\n    | `--host`          | URL of the BWS to call                                               | ✅ Yes      |\n    | `--clientid`      | Your BWS Client Identifier                                           | ✅ Yes      |\n    | `--key`           | Your base64 encoded signing key                                      | ✅ Yes      |\n    | `--rest` `-r`     | Use RESTful API call (instead of gRPC)                               | ❌ No       |\n    | `--deadline` `-d` | Optional deadline for the call in milliseconds (gRPC only)           | ❌ No       |\n    | `--verbosity` `-v`| The output verbosity mode [default: Normal] (Detailed, Diagnostic, Minimal, Normal, Quiet) | ❌ No       |\n\n    Examples:\n    + videolivenessdetection:\n    ```bash\n    bws videolivedetect --host https://bwsapiendpoint yourfilepath --clientid yourbwsclientid --key yourbwssecret\n    ```\n---\n- \u003ch4 id=\"photoverify\"\u003ephotoverify\u003c/h4\u003e\n\n    Calls the PhotoVerify API, which requires one or two live images and one ID photo, to verify whether the given photo matches a specific verification criterion.\n\n    | Arguments       | Description                                                                           |\n    |-----------------|---------------------------------------------------------------------------------------|\n    | `files`         | List of image files to process.\n\n    | Options           | Description                                                              | Required |\n    |-------------------|--------------------------------------------------------------------------|----------|\n    | `--host`          | URL of the BWS to call                                                   | ✅ Yes      |\n    | `--clientid`      | Your BWS Client Identifier                                               | ✅ Yes      |\n    | `--key`           | Your base64 encoded signing key                                          | ✅ Yes      |\n    | `--photo`         | ID photo input file                                                      | ✅ Yes      |\n    | `--disablelive`   | Disable liveness detection with PhotoVerify API                          | ❌ No       |\n    | `--challenge`     | Optional head motion direction for the challenge response liveness detection mode (right, left, up, down). Requires two live images  | ❌ No       |\n    | `--rest` `-r`     | Use RESTful API call (instead of gRPC)                                   | ❌ No       |\n    | `--deadline` `-d` | Optional deadline for the call in milliseconds (gRPC only)               | ❌ No       |\n    | `--verbosity` `-v`| The output verbosity mode [default: Normal] (Detailed, Diagnostic, Minimal, Normal, Quiet) | ❌ No       |\n\n    Examples:\n    + photoverify via RESTful API:\n    ```bash\n    bws photoverify --host https://bwsapiendpoint --rest yourfilepath1 yourfilepath2 --photo youridphotopath --clientid yourbwsclientid --key yourbwssecret\n    ```\n\n\u003ch3 id=\"facerecognition\"\u003eFace Recognition API (Enroll, Verify, Search, SetTemplateTags, GetTemplateStatus, GetClassCount, DeleteTemplate)\u003c/h3\u003e\n\nThe FaceRecognition APIs, which compares the facial characteristics of a person with a stored version of those characteristics.\nIt can compare against a single biometric template for user verification purposes or against multiple templates to search for a specific user within a set of persons.\n \n- \u003ch4 id=\"enroll\"\u003eenroll\u003c/h4\u003e\n\n    Call into the FaceEnrollment API with one or more images.\n\n    | Arguments       | Description                                                                           |\n    |-----------------|---------------------------------------------------------------------------------------|\n    | `files`         | List of image files to process.\n\n    | Options           | Description                                                              | Required |\n    |-------------------|--------------------------------------------------------------------------|----------|\n    | `--host`          | URL of the BWS to call                                                   | ✅ Yes      |\n    | `--clientid`      | Your BWS Client Identifier                                               | ✅ Yes      |\n    | `--key`           | Your base64 encoded signing key                                          | ✅ Yes      |\n    | `--classid` `-i`  | A unique class ID of the person associated with the biometric template   | ✅ Yes      |\n    | `--rest` `-r`     | Use RESTful API call (instead of gRPC)                                   | ❌ No       |\n    | `--deadline` `-d` | Optional deadline for the call in milliseconds (gRPC only)               | ❌ No       |\n    | `--verbosity` `-v`| The output verbosity mode [default: Normal] (Detailed, Diagnostic, Minimal, Normal, Quiet) | ❌ No       |\n\n    Examples:\n    + Biometric enrollment of a single class with *diagnostic* output level via RESTful API:\n    ```bash\n    bws --enroll yourfilepath --host https://bwsapiendpoint -v Diagnostic -r --clientid yourbwsclientid --key yourbwssecret --classid yourclassid\n    ```\n---\n- \u003ch4 id=\"verify\"\u003everify\u003c/h4\u003e\n\n    Call into the FaceVerification API, providing a single image.\n\n    | Arguments       | Description                                                                           |\n    |-----------------|---------------------------------------------------------------------------------------|\n    | `file`          | The image file to process.\n\n\n    | Options           | Description                                                              | Required |\n    |-------------------|--------------------------------------------------------------------------|----------|\n    | `--host`          | URL of the BWS to call                                                   | ✅ Yes      |\n    | `--clientid`      | Your BWS Client Identifier                                               | ✅ Yes      |\n    | `--key`           | Your base64 encoded signing key                                          | ✅ Yes      |\n    | `--classid` `-i`  | A unique class ID of the person associated with the biometric template   | ✅ Yes      |\n    | `--rest` `-r`     | Use RESTful API call (instead of gRPC)                                   | ❌ No       |\n    | `--deadline` `-d` | Optional deadline for the call in milliseconds (gRPC only)               | ❌ No       |\n    | `--verbosity` `-v`| The output verbosity mode [default: Normal] (Detailed, Diagnostic, Minimal, Normal, Quiet) | ❌ No       |\n\n    Examples:\n    + One-to-one comparison of the uploaded face image with *diagnostic* output level via RESTful API:\n    ```bash\n    bws --verify yourfilepath --host https://bwsapiendpoint -v Diagnostic -r --clientid yourbwsclientid --key yourbwssecret --classid yourclassid\n    ```\n---\n- \u003ch4 id=\"search\"\u003esearch\u003c/h4\u003e\n\n    Call into the Face Search API, requires one or more images.\n\n    | Arguments       | Description                                                                           |\n    |-----------------|---------------------------------------------------------------------------------------|\n    | `files`         | List of image files to process.\n\n\n    | Options           | Description                                                              | Required |\n    |-------------------|--------------------------------------------------------------------------|----------|\n    | `--host`          | URL of the BWS to call                                                   | ✅ Yes      |\n    | `--clientid`      | Your BWS Client Identifier                                               | ✅ Yes      |\n    | `--key`           | Your base64 encoded signing key                                          | ✅ Yes      |\n    | `--tags`          | A list of tags associated with the biometric templates                   | ❌ No       |\n    | `--rest` `-r`     | Use RESTful API call (instead of gRPC)                                   | ❌ No       |\n    | `--deadline` `-d` | Optional deadline for the call in milliseconds (gRPC only)               | ❌ No       |\n    | `--verbosity` `-v`| The output verbosity mode [default: Normal] (Detailed, Diagnostic, Minimal, Normal, Quiet) | ❌ No       |\n\n    Examples:\n    + One-to-many comparison of the uploaded face image with *diagnostic* output level via RESTful API:\n    ```bash\n    bws --search yourfilepath --host https://bwsapiendpoint -v Diagnostic -r --clientid yourbwsclientid --key yourbwssecret --tags yourtags\n    ```\n---\n- \u003ch4 id=\"settags\"\u003esettags\u003c/h4\u003e\n \n    Associate tags with a biometric template.\n\n    | Options           | Description                                                              | Required |\n    |-------------------|--------------------------------------------------------------------------|----------|\n    | `--host`          | URL of the BWS to call                                                   | ✅ Yes      |\n    | `--clientid`      | Your BWS Client Identifier                                               | ✅ Yes      |\n    | `--key`           | Your base64 encoded signing key                                          | ✅ Yes      |\n    | `--classid` `-i`  | A unique class ID of the person associated with the biometric template   | ✅ Yes      |\n    | `--tags`          | A list of tags to associate with the biometric template                  | ❌ No       |\n    | `--rest` `-r`     | Use RESTful API call (instead of gRPC)                                   | ❌ No       |\n    | `--deadline` `-d` | Optional deadline for the call in milliseconds (gRPC only)               | ❌ No       |\n    | `--verbosity` `-v`| The output verbosity mode [default: Normal] (Detailed, Diagnostic, Minimal, Normal, Quiet) | ❌ No       |\n\n    Examples:\n    + Set tags to template with *diagnostic* output level via RESTful API:\n    ```bash\n    bws --settags --host https://bwsapiendpoint -v Diagnostic -r --clientid yourbwsclientid --key yourbwssecret --classid yourclassid --tags yourtags\n    ```\n---\n- \u003ch4 id=\"gettemplate\"\u003egettemplate\u003c/h4\u003e\n\n    Fetch the status of a biometric template (together with enrolled thumbs, if available).\n\n    | Options           | Description                                                              | Required |\n    |-------------------|--------------------------------------------------------------------------|----------|\n    | `--host`          | URL of the BWS to call                                                   | ✅ Yes      |\n    | `--clientid`      | Your BWS Client Identifier                                               | ✅ Yes      |\n    | `--key`           | Your base64 encoded signing key                                          | ✅ Yes      |\n    | `--classid` `-i`  | A unique class ID of the person associated with the biometric template   | ✅ Yes      |\n    | `--rest` `-r`     | Use RESTful API call (instead of gRPC)                                   | ❌ No       |\n    | `--deadline` `-d` | Optional deadline for the call in milliseconds (gRPC only)               | ❌ No       |\n    | `--verbosity` `-v`| The output verbosity mode [default: Normal] (Detailed, Diagnostic, Minimal, Normal, Quiet) | ❌ No       |\n\n    Examples:\n    + Get status of face template with *diagnostic* output level via RESTful API:\n    ```bash\n    bws --gettemplate --host https://bwsapiendpoint -v Diagnostic -r --clientid yourbwsclientid --key yourbwssecret --classid yourclassid\n    ```\n---\n- \u003ch4 id=\"deletetemplate\"\u003edeletetemplate\u003c/h4\u003e\n\n    Delete a biometric template.\n\n    | Options           | Description                                                              | Required |\n    |-------------------|--------------------------------------------------------------------------|----------|\n    | `--host`          | URL of the BWS to call                                                   | ✅ Yes      |\n    | `--clientid`      | Your BWS Client Identifier                                               | ✅ Yes      |\n    | `--key`           | Your base64 encoded signing key                                          | ✅ Yes      |\n    | `--classid` `-i`  | A unique class ID of the person associated with the biometric template   | ✅ Yes      |\n    | `--rest` `-r`     | Use RESTful API call (instead of gRPC)                                   | ❌ No       |\n    | `--deadline` `-d` | Optional deadline for the call in milliseconds (gRPC only)               | ❌ No       |\n    | `--verbosity` `-v`| The output verbosity mode [default: Normal] (Detailed, Diagnostic, Minimal, Normal, Quiet) | ❌ No       |\n\n    Examples:\n    + Deletes all information associated with the provided class ID:\n    ```bash\n    bws --deletetemplate --host https://bwsapiendpoint --clientid yourbwsclientid --key yourbwssecret --classid yourclassid\n    ```\n\n\u003ch2 id=\"jwt\"\u003e🔐 JWT - JSON Web Tokens\u003c/h2\u003e\n\nJSON Web Tokens are an open, industry-standard RFC 7519 method for securely representing claims between two parties.\nThe JWT tool can be used to create JSON web tokens for authentication with various BWS 3 services:\n* BWS Management API: Use your username as subject and your personal API key as signing key (this information can be found in the [BWS Portal][BWSPortal] under your user profile)\n* BWS 3 Client: Use the desired client-ID as the subject and one of the client keys associated with this client as the signing key (this information can be found in the [BWS Portal][BWSPortal] under your BWS 3 client)\n\n## Before you start, you need access to a BWS 3 client\n\n\u003e #### If you do not have access, follow these steps\n\u003e\n\u003e - You need a **BioID Account** with a **confirmed** email address. If you don’t have one, [create a BioID account][bioidaccountregister].\n\u003e - Once you’ve created your BioID account, you can create a free [trial subscription][trial] or the BioID Web Service (BWS 3).\n\u003e - After signing in to the BWS Portal and creating the trial subscription using the wizard, you’ll need to create a ***BWS 3 client***.\n\u003e - The client can be created using the client creation wizard.\n\n### Technical information about\n- [**BioID Web Service (BWS 3)**][BWS3]\n\n[bioidaccountregister]: https://account.bioid.com/Account/Register \"Register a BioID account\"\n[BWSPortal]: https://bwsportal.bioid.com/\n[trial]: https://bwsportal.bioid.com/ \"Create a free trial subscription\"\n[BWS3]: https://developer.bioid.com/BWS/NewBws\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbioid-gmbh%2Fbwstools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbioid-gmbh%2Fbwstools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbioid-gmbh%2Fbwstools/lists"}