Token Web API
GET /token?id={app-id}&bcid={BCID}
Requests a BWS
token to be used for authorization with most of the other BWS Web APIs. The issued token will be assigned to the specified user and has a very short lifetime, i.e. it expires after about ten minutes as it is typically only used for one biometric task like verification or enrollment (including retries).
Request Information
Parameters
id | Required. The App-ID of the registered BWS Client App calling the API. |
---|---|
bcid | Required. The Biometric Class ID (BCID) of the person for whom the token shall be issued, i.e. the user that is going to perform a biometric task using this token. Not required for |
task | Optional, defaults to verify . A string that specifies the task the issued token shall be used for: Currently the tasks verify (default), identify, enroll and livenessdetection are defined. Tokens created for the task verify are intended to be used together with the Verify Web API, identify-tokens are used with the Identify Web API, enroll-tokens with the Enroll Web API and livenessdetection-tokens with the LivenessDetection Web API. With all kind of tokens access to the Upload Web API is allowed of course. |
maxtries | Optional, defaults to 3 . An non-zero integer value up to 15 that specifies the maximum number of tries an application or a user is allowed to perform with the issued token. The default is 3 attempts. |
livedetection | Optional, defaults to true . A boolean parameter to switch off live data detection. When set to true (the default), liveness detection is required and the intended task shall fail, as soon as it cannot undoubtedly determine that the given data is live data. When set to false , live data detection is not required (except for the livenessdetection task that always performs a liveness detection of course). |
challenge | Optional, defaults to Note: You don't need to enable this option if you are only interested in using liveness detection. |
challenges | Optional, defaults to 3 . An integer value between 2 and 7 that specifies the number of challenges that shall be embedded in the token in case that liveness detection with challenge response is enabled. |
autoenroll | Optional, defaults to false . A boolean parameter used in conjunction with the verify task that if set to true and the verification succeeded it allows to automatically enroll the uploaded samples. This ensures, that the biometric template of the person is automatically adapted and always assembled from current samples. When set to false (the default), no automatic enrollment will be performed. |
traits | Optional, defaults to Face,Periocular . The traits that shall be used for the biometric operation. |
Authentication
This API call requires Basic Authentication, i.e. you have to provide an HTTP authorization header using the authorization method Basic and the base64 encoded string App-ID:App-Secret (therefore the transport is secured using TLS/SSL). To receive the necessary BWS Web API access data (App-ID and App-Secret) you have to register your application on the BWS Portal first. This requires a valid BWS subscription.
Response Information
The Token Web API returns a string containing the issued BWS token.The BWS uses a JSON Web Token (JWT) to represent the issued claims as a JSON object. The object is encoded as JSON Web Signature (JWS) which means that the claims are digitally signed (HMACed), base64url encoded and finally joined with a period.
Response Body Format
Sample Token:
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbmlkIjoiM2M2ZjgyYzctNzEyYi00ZWQ5LTk3MzYtNmZkNjFlMjIyNTUyIiwiY2xudCI6IkJXUy1UZXN0IG9uIE11bHRpdGVuYW50IiwiYXBwIjoiMTk1NTM0MzMxMS45MjA0LmFwcC5iaW9pZC5jb20iLCJiY2lkIjoiYndzLzExMi8xMjM0NSIsInRyYWl0cyI6MywidGFzayI6MjU5LCJpc3MiOiJCV1MiLCJhdWQiOiJodHRwczovL2J3cy5iaW9pZC5jb20iLCJleHAiOjE1MTUwNjIzNTYsIm5iZiI6MTUxNTA2MTc1Nn0.e96xFIZRri76oyunCUo-TUSNEE_wmczX7WrzwrC2MP4
Decoded sample token:
Header | {"typ":"JWT","alg":"HS256"} |
---|---|
Claims | {"tokenid":"3c6f82c7-712b-4ed9-9736-6fd61e222552", "clnt":"BWS-Test on Multitenant", "app":"1955343311.9204.app.bioid.com", "bcid":"bws/112/12345", "traits":3, "task":259, "iss":"BWS", "aud":"https://bws.bioid.com", "exp":1515062356, "nbf":1515061756} |
Signature | 7BDEB1148651AE2EFAA32BA7094A3E4D448D104FF099CCD7ED6AF3C2B0B630FE |
Claims encoded in a BWS token:
tokenid | A unique identifier for the issued token. |
---|---|
iss | The issuer of the token (typically BWS). |
aud | The audience for this token, i.e. the URL of the BWS instance that accepts this token. |
nbf | The token is not accepted before this timestamp. |
exp | The expiration time on after which the token is not accepted any more. |
bcid | The Biomatric Class ID of the user the token belongs to. |
clnt | The BWS client that requested the token. |
app | The application that requested the token. |
task | The task this token is issued for. This is the logical combination of various flags that describe the task this token is intended to be used for. |
challenge | An optional array (max tries) of string arrays that shall be used to challenge the user during the recording of face images. |
traits | The traits that shall be used with the specified task. |
Possible values encoded into the 'task'-claim:
Verify (0) | The token is intended to be used for verification. |
---|---|
Identify (0x10) | The token is intended to be used for identification. |
Enroll (0x20) | The token is intended to be used for enrollment. |
LiveOnly (0x80) | The token is intended to be used for liveness detection only. |
MaxTriesMask (0x0F) | These four bits are used to encode the number of maximum tries a user is allowed to perform. |
LiveDetection (0x100) | Liveness detection is required. |
ChallengeResponse (0x200) | Challenge-response is required (the 'challenge'-claim is available). |
AutoEnroll (0x1000) | Automatic enrollment is switched on. |
Response HTTP Status Codes
Return values of API calls are standard HTTP status codes. With the success code (200) you receive the issued BWS token in the body text. With error codes a Message field within the body text describing the error is returned. The most commonly return codes are:
200 OK | The response body contains the issued BWS token string. |
---|---|
400 Bad Request | An invalid BCID has been specified. |
401 Unauthorized | No or an invalid authentication header has been specified, Basic Authentication is required. |
403 Forbidden | Access has been denied (typically due to a wrong or invalid app-id or BCID). |
500 Internal Server Error | A server side exception occurred. |
Sample Code
const string APP_IDENTIFIER = ""; const string APP_SECRET = ""; const string ENDPOINT = "https://bws.bioid.com/extension/"; const string STORAGE = ""; const int PARTITION = 0; const int CLASSID = 0; static string bcid = STORAGE + "." + PARTITION + "." + CLASSID; public enum TokenFor { verify, identify, enroll, livenessdetection } private static async Task<string> TokenAsync(string bcid, TokenFor forTask = TokenFor.verify) { using (var client = new HttpClient()) { client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes($"{APP_IDENTIFIER}:{APP_SECRET}"))); Console.Write("Get BWS token: "); using (var response = await client.GetAsync(ENDPOINT + $"token?id={APP_IDENTIFIER}&bcid={bcid}&task={forTask}")) { if (response.StatusCode == HttpStatusCode.OK) { Console.WriteLine("succeeded"); return await response.Content.ReadAsStringAsync(); } else { Console.WriteLine(response.StatusCode.ToString()); return ""; } } } }
// using OkHttpClient from the OkHttp library HttpUrl url = HttpUrl.parse("https://bws.bioid.com/extension/token").newBuilder() .addQueryParameter("id", APP_IDENTIFIER) .addQueryParameter("bcid", STORAGE + "." + PARTITION + "." + CLASS_ID) .build(); Request request = new Request.Builder() .url(url) .addHeader("Authorization", Credentials.basic(APP_IDENTIFIER, APP_SECRET)) .build(); OkHttpClient client = new OkHttpClient(); Response response = client.newCall(request).execute(); String token = response.body().string(); if (response.code() == 200) { System.out.println("token=" + token); } return token;