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

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

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbmlkIjoiM2M2ZjgyYzctNzEyYi00ZWQ5LTk3MzYtNmZkNjFlMjIyNTUyIiwiY2xudCI6IkJXUy1UZXN0IG9uIE11bHRpdGVuYW50IiwiYXBwIjoiMTk1NTM0MzMxMS45MjA0LmFwcC5iaW9pZC5jb20iLCJiY2lkIjoiYndzLzExMi8xMjM0NSIsInRyYWl0cyI6MywidGFzayI6MjU5LCJpc3MiOiJCV1MiLCJhdWQiOiJodHRwczovL2J3cy5iaW9pZC5jb20iLCJleHAiOjE1MTUwNjIzNTYsIm5iZiI6MTUxNTA2MTc1Nn0.e96xFIZRri76oyunCUo-TUSNEE_wmczX7WrzwrC2MP4

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:

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;