BWSTools

BWSTools is a command-line tool for interacting with the BioID Web Service 3 (BWS 3). It includes:

• BWS CLI: A CLI tool for calling BWS 3 APIs.
• JWT: A helper tool to generate JWT tokens for BWS 3 authentication.

📋 Table of Contents

• BWS CLI
  • Usage
  • Commands
    • gRPC API
      • livedetect
      • videolivedetect
      • photoverify
    • Face Recognition API
      • enroll
      • verify
      • search
      • settags
      • gettemplate
      • deletetemplate
• JWT Tool

🧪 BWS CLI

This is a simple command-line tool for the BioID Web Service, designed to easily test BWS 3 installations. To use the BWS CLI tool and successfully call BWS APIs, you will need:

• the corresponding Client ID, and
• the base64-encoded client key (JWT Token).

If you do not already have these credentials, the JWT explains in detail how to generate a suitable token.

Usage

The general syntax for running the bws cli tool is:

bws [command] [options]

📚 Commands

The CLI tool supports the following commands:

• healthcheck: Call the health check API. The HealthCheck API provides real-time health status of the BWS service API.

  Options	Description	Required
  --host	URL of the BWS to call	✅ Yes
  --rest -r	Use RESTful API call (instead of gRPC)	❌ No
  --verbosity -v	The output verbosity mode [default: Normal] (Detailed, Diagnostic, Minimal, Normal, Quiet)	❌ No

  Examples:

  • gRPC healthcheck:

  bws healthcheck --host https://bwsapiendpoint

  • RESTful healthcheck:

  bws healthcheck --rest --host https://bwsapiendpoint

gRPC API (LivenessDetection, VideoLivenessDetection, PhotoVerify)

• livedetect

  Call the LivenessDetection API, requiring one (passive live detection) or two (active live detection) live images.

  Arguments	Description
  files	List of image files to process.

  Options	Description	Required
  --host	URL of the BWS to call	✅ Yes
  --clientid	Your BWS Client Identifier	✅ Yes
  --key	Your base64 encoded signing key	✅ Yes
  --challenge	Optional head motion direction for the challenge response liveness detection mode (right, left, up, down). Requires two live images	❌ No
  --rest -r	Use RESTful API call (instead of gRPC)	❌ No
  --deadline -d	Optional deadline for the call in milliseconds (gRPC only)	❌ No
  --verbosity -v	The output verbosity mode [default: Normal] (Detailed, Diagnostic, Minimal, Normal, Quiet)	❌ No

  Examples:
  

  • Passive liveness detection with diagnostic output level:

  bws livedetect --host https://bwsapiendpoint -v Diagnostic yourfilepath --clientid yourbwsclientid --key yourbwssecret

  • Active liveness detection via RESTful API:

  bws livedetect --host https://bwsapiendpoint --rest yourfilepath1 yourfilepath2 --clientid yourbwsclientid --key yourbwssecret

---

• videolivedetect

  Call the VideoLivenessDetection API to analyze a video file and detect if the content contains a live subject.

  Arguments	Description
  video	video file to process

  Options	Description	Required
  --host	URL of the BWS to call	✅ Yes
  --clientid	Your BWS Client Identifier	✅ Yes
  --key	Your base64 encoded signing key	✅ Yes
  --rest -r	Use RESTful API call (instead of gRPC)	❌ No
  --deadline -d	Optional deadline for the call in milliseconds (gRPC only)	❌ No
  --verbosity -v	The output verbosity mode [default: Normal] (Detailed, Diagnostic, Minimal, Normal, Quiet)	❌ No

  Examples:

  • videolivenessdetection:

  bws videolivedetect --host https://bwsapiendpoint yourfilepath --clientid yourbwsclientid --key yourbwssecret

---

• photoverify

  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.

  Arguments	Description
  files	List of image files to process.

  Options	Description	Required
  --host	URL of the BWS to call	✅ Yes
  --clientid	Your BWS Client Identifier	✅ Yes
  --key	Your base64 encoded signing key	✅ Yes
  --photo	ID photo input file	✅ Yes
  --disablelive	Disable liveness detection with PhotoVerify API	❌ No
  --challenge	Optional head motion direction for the challenge response liveness detection mode (right, left, up, down). Requires two live images	❌ No
  --rest -r	Use RESTful API call (instead of gRPC)	❌ No
  --deadline -d	Optional deadline for the call in milliseconds (gRPC only)	❌ No
  --verbosity -v	The output verbosity mode [default: Normal] (Detailed, Diagnostic, Minimal, Normal, Quiet)	❌ No

  Examples:

  • photoverify via RESTful API:

  bws photoverify --host https://bwsapiendpoint --rest yourfilepath1 yourfilepath2 --photo youridphotopath --clientid yourbwsclientid --key yourbwssecret

Face Recognition API (Enroll, Verify, Search, SetTemplateTags, GetTemplateStatus, GetClassCount, DeleteTemplate)

The FaceRecognition APIs, which compares the facial characteristics of a person with a stored version of those characteristics. It 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.

• enroll

  Call into the FaceEnrollment API with one or more images.

  Arguments	Description
  files	List of image files to process.

  Options	Description	Required
  --host	URL of the BWS to call	✅ Yes
  --clientid	Your BWS Client Identifier	✅ Yes
  --key	Your base64 encoded signing key	✅ Yes
  --classid -i	A unique class ID of the person associated with the biometric template	✅ Yes
  --rest -r	Use RESTful API call (instead of gRPC)	❌ No
  --deadline -d	Optional deadline for the call in milliseconds (gRPC only)	❌ No
  --verbosity -v	The output verbosity mode [default: Normal] (Detailed, Diagnostic, Minimal, Normal, Quiet)	❌ No

  Examples:

  • Biometric enrollment of a single class with diagnostic output level via RESTful API:

  bws --enroll yourfilepath --host https://bwsapiendpoint -v Diagnostic -r --clientid yourbwsclientid --key yourbwssecret --classid yourclassid

---

• verify

  Call into the FaceVerification API, providing a single image.

  Arguments	Description
  file	The image file to process.

  Options	Description	Required
  --host	URL of the BWS to call	✅ Yes
  --clientid	Your BWS Client Identifier	✅ Yes
  --key	Your base64 encoded signing key	✅ Yes
  --classid -i	A unique class ID of the person associated with the biometric template	✅ Yes
  --rest -r	Use RESTful API call (instead of gRPC)	❌ No
  --deadline -d	Optional deadline for the call in milliseconds (gRPC only)	❌ No
  --verbosity -v	The output verbosity mode [default: Normal] (Detailed, Diagnostic, Minimal, Normal, Quiet)	❌ No

  Examples:

  • One-to-one comparison of the uploaded face image with diagnostic output level via RESTful API:

  bws --verify yourfilepath --host https://bwsapiendpoint -v Diagnostic -r --clientid yourbwsclientid --key yourbwssecret --classid yourclassid

---

• search

  Call into the Face Search API, requires one or more images.

  Arguments	Description
  files	List of image files to process.

  Options	Description	Required
  --host	URL of the BWS to call	✅ Yes
  --clientid	Your BWS Client Identifier	✅ Yes
  --key	Your base64 encoded signing key	✅ Yes
  --tags	A list of tags associated with the biometric templates	❌ No
  --rest -r	Use RESTful API call (instead of gRPC)	❌ No
  --deadline -d	Optional deadline for the call in milliseconds (gRPC only)	❌ No
  --verbosity -v	The output verbosity mode [default: Normal] (Detailed, Diagnostic, Minimal, Normal, Quiet)	❌ No

  Examples:

  • One-to-many comparison of the uploaded face image with diagnostic output level via RESTful API:

  bws --search yourfilepath --host https://bwsapiendpoint -v Diagnostic -r --clientid yourbwsclientid --key yourbwssecret --tags yourtags

---

• settags

  Associate tags with a biometric template.

  Options	Description	Required
  --host	URL of the BWS to call	✅ Yes
  --clientid	Your BWS Client Identifier	✅ Yes
  --key	Your base64 encoded signing key	✅ Yes
  --classid -i	A unique class ID of the person associated with the biometric template	✅ Yes
  --tags	A list of tags to associate with the biometric template	❌ No
  --rest -r	Use RESTful API call (instead of gRPC)	❌ No
  --deadline -d	Optional deadline for the call in milliseconds (gRPC only)	❌ No
  --verbosity -v	The output verbosity mode [default: Normal] (Detailed, Diagnostic, Minimal, Normal, Quiet)	❌ No

  Examples:

  • Set tags to template with diagnostic output level via RESTful API:

  bws --settags --host https://bwsapiendpoint -v Diagnostic -r --clientid yourbwsclientid --key yourbwssecret --classid yourclassid --tags yourtags

---

• gettemplate

  Fetch the status of a biometric template (together with enrolled thumbs, if available).

  Options	Description	Required
  --host	URL of the BWS to call	✅ Yes
  --clientid	Your BWS Client Identifier	✅ Yes
  --key	Your base64 encoded signing key	✅ Yes
  --classid -i	A unique class ID of the person associated with the biometric template	✅ Yes
  --rest -r	Use RESTful API call (instead of gRPC)	❌ No
  --deadline -d	Optional deadline for the call in milliseconds (gRPC only)	❌ No
  --verbosity -v	The output verbosity mode [default: Normal] (Detailed, Diagnostic, Minimal, Normal, Quiet)	❌ No

  Examples:

  • Get status of face template with diagnostic output level via RESTful API:

  bws --gettemplate --host https://bwsapiendpoint -v Diagnostic -r --clientid yourbwsclientid --key yourbwssecret --classid yourclassid

---

• deletetemplate

  Delete a biometric template.

  Options	Description	Required
  --host	URL of the BWS to call	✅ Yes
  --clientid	Your BWS Client Identifier	✅ Yes
  --key	Your base64 encoded signing key	✅ Yes
  --classid -i	A unique class ID of the person associated with the biometric template	✅ Yes
  --rest -r	Use RESTful API call (instead of gRPC)	❌ No
  --deadline -d	Optional deadline for the call in milliseconds (gRPC only)	❌ No
  --verbosity -v	The output verbosity mode [default: Normal] (Detailed, Diagnostic, Minimal, Normal, Quiet)	❌ No

  Examples:

  • Deletes all information associated with the provided class ID:

  bws --deletetemplate --host https://bwsapiendpoint --clientid yourbwsclientid --key yourbwssecret --classid yourclassid

🔐 JWT - JSON Web Tokens

JSON Web Tokens are an open, industry-standard RFC 7519 method for securely representing claims between two parties. The JWT tool can be used to create JSON web tokens for authentication with various BWS 3 services:

• 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 under your user profile)
• 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 under your BWS 3 client)

Before you start, you need access to a BWS 3 client

If you do not have access, follow these steps

• You need a BioID Account with a confirmed email address. If you don’t have one, create a BioID account.
• Once you’ve created your BioID account, you can create a free trial subscription or the BioID Web Service (BWS 3).
• After signing in to the BWS Portal and creating the trial subscription using the wizard, you’ll need to create a BWS 3 client.
• The client can be created using the client creation wizard.

Technical information about

• BioID Web Service (BWS 3)