Confident Technologies Image based Authentication Serviceconfidenttech.com/files/Image-Based_Strong_Authentication_Web_A… · Confident Technologies Image-based Authentication Service

1 265 Santa Helena Drive, Suite 105 • Solana Beach, CA 92075 • (858) 345-5640 • www.ConfidentTechnologies.com

Confident Technologies Image-based Authentication Service

Confident ImageShield™ Image-Based, User Authentication for Websites and Applications Sample API

This is an example API and is being continuously improved and enhanced. We are adding and modifying resources, requests, representations, and documentation. Our goal is to help website and application developers make their systems more secure using our image-based user authentication technology.

Please email [email protected] to let us know how we can make your development tasks easier.

This document describes a sample of the Confident Technologies Web Service API for Confident ImageShield. Please contact [email protected] or (858) 345-5640 to get key credentials and the complete, up-to-date API for our web service.

Visit www.ConfidentTechnologies.com to view the APIs for our other image-based authentication offerings: mobile authentication, multi-factor authentication and CAPTCHA.

mailto:[email protected]

mailto:[email protected]

http://www.confidenttechnologies.com/


Table of Contents Overview ....................................................................................................................................................................3

Authentication ........................................................................................................................................................3

Authentication Errors .............................................................................................................................................3

Resource Name Requirements ...............................................................................................................................3

Internationalization .................................................................................................................................................4

The user_id Parameter .......................................................................................................................................4

Statistics ..................................................................................................................................................................4

Resources ....................................................................................................................................................................5

/vs/customers ..........................................................................................................................................................5

/vs/customers/{customer} ......................................................................................................................................6

/vs/customers/{customer}/sites ..............................................................................................................................7

/vs/customers/{customer}/sites/{site} ....................................................................................................................7

/vs/customers/{customer}/sites/{site}/resetcredentials ..........................................................................................8

/vs/customers/{customer}/sites/{site}/services ......................................................................................................9

/vs/customers/{customer}/sites/{site}/stats ......................................................................................................... 10

/vs/customers/{customer}/sites/{site}/stats/success ............................................................................................ 11

/vs/customers/{customer}/sites/{site}/stats/users ............................................................................................... 12

/vs/customers/{customer}/sites/{site}/services/imageshield............................................................................... 13

/vs/customers/{customer}/sites/{site}/services/imageshield/stats ...................................................................... 17

/vs/customers/{customer}/sites/{site}/services/imageshield/stats/success ......................................................... 18

/vs/customers/{customer}/sites/{site}/services/imageshield/stats/users ............................................................. 19

/vs/imageshields/{imageshield_id} ..................................................................................................................... 20

/vs/imageshields/{imageshield_id}/image .......................................................................................................... 22


Overview

Authentication

Many API calls are restricted to the owner of a resource. When a call is restricted, use HTTP Basic

Authentication (as described in RFC 2617, "HTTP Authentication: Basic and Digest Access

Authentication") to authenticate to the API, using the API username and the API password.

For these example values:

Customer ID

alice001

Site ID

site001

API username

QHW6aC7DsJKP

API password

g0OeLVS3I6ZE

the curl request for the site resource is: curl https://api.confidenttechnologies.com/vs/customers/alice001/sites/site001 --

user QHW6aC7DsJKP:g0OeLVS3I6ZE

the PHP equivalent is: <?php

$vs_user = "QHW6aC7DsJKP";

$vs_password = "g0OeLVS3I6ZE";

$curl =

curl_init("https://api.confidenttechnologies.com/vs/customers/alice001/sites/site00

1");

curl_setopt($curl,CURLOPT_USERPWD,$vs_user . ":" . $vs_password);

curl_exec($curl);

?>

Authentication Errors

When there is an authentication problem, the API responds with a "401 Unauthorized" status code and

a generic response body. Some possible causes are:

No username or password

Unknown username

Wrong password for username

Correct username and password, but the site is not the owner of the resource

Resource Name Requirements

The name of a resource, initially specified in a PUT request for the resource, must contain no more than

40 characters. The allowed characters are alphanumerics (a-z, A-Z, 0-9), hyphen (-), period (.), and

underscore (_).

http://tools.ietf.org/html/rfc2617


If a resource name does not meet these requirements when requesting to create the resource, the status

code of the response will be 400. The body of the response will describe the exact error.

Internationalization

Some resources contain messages meant to be shown directly to end-users. For example,

/vs/categories contains category names. Localized messages can be shown in any supported locale.

The following locales are supported:

English (United States) [en-us]

Japanese (Japan) [ja-jp]

By default, localized messages are shown in the English (United States) locale. To request a different

locale, use the Accept-Langauge header as documented in RFC 2616.

The user_id Parameter

All premium services require the user_id parameter. This parameter must uniquely identify your end-

users and must not exceed 100 characters. For your security and your end-users' privacy, this should not

be the actual usernames used on your site. A good alternative is to submit a salted hash of the username

or the primary key of the users table of your database.

Statistics

Statistics are a new feature that we expect to change rapidly in the coming weeks. Please send us

feedback on what you'd like from this feature.

Statistics requests have these parameters:

from: Statistics start at and include this date, given in ISO format (i.e. 2008-04-13T12:34).

Note: there are no statistics available before April 1st, 2009.

to: Statistics end at but do not include this date, given in ISO format (i.e. 2009-03-13T4:23).

granularity: The time granularity to aggregate statistics.

The granularity affects how the dates are interpreted. Not all granularities are allowed for every statistics

query.

Granularity Date Interpretation Statistics Returned

year Rounded down to given year Aggregated by year

month Rounded down to given year and month Aggregated by month

day Rounded down to given year, month, and day Aggregated by day

total Rounded down to given year, month, and day One row for the given date range

For example, given these dates:

http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.4


from=2008-12-30T08:13 to=2009-01-02T06:59

different values for granularity have different results:

granularity=year - Statistics for 2008.

granularity=month - Statistics for December 2008.

granularity=day - Statistics for December 30th 2008, December 31st 2008, and January 1st

2009.

granularity=total - Summed statistics from December 30th 2008 through January 1st 2009.

Resources

/vs/customers

The customers resource is a container for customer resources.

GET

This request returns the customer associated with the site API credentials.

Acceptable request representations:

Example:

GET /vs/customers

Available response representations:

Status Code 200 - application/xml (boca:customerURIs)

A list of customer URIs that can be managed using the authentication credentials.

Example:

Content-Type: application/xml

<customerURIs>

<customerURI>https://api.confidenttechnologies.com/vs/customers/cust001</cust

omerURI>

</customerURIs>

[Table of Contents]

https://api.confidenttechnologies.com/static/ws.html#customer


/vs/customers/{customer}

The customer resource holds data about a customer of the API.

GET

This request returns a representation of the specified customer, if it exists. This request must be

authenticated with the site API credentials.


Example:

GET /vs/customers/cust001


Status Code 200 - application/xml (boca:customer)

A representation of the customer, containing its name, email address, and phone number. The

admin_name is the friendly name of the administrating authority that manages this customer

account.

Example:


<customer>

<name>bob</name>

<email>[email protected]</email>

<phone>555555555</phone>

<sitesURI>https://api.confidenttechnologies.com/vs/customers/cust123/sites</s

itesURI>

<statsURI>https://api.confidenttechnologies.com/vs/customers/cust123/stats</s

tatsURI>

<admin_name>Confident</admin_name>

</customer>

Status Code 410

The customer has been deleted.

[Table of Contents]


/vs/customers/{customer}/sites

The sites resource is a container for site resources.

GET

This request returns a list of site URIs associated with the specified customer, if the customer exists.

This request must be authenticated with the site API credentials.


Example:

GET /vs/customers/cust001/sites


Status Code 200 - application/xml (boca:siteURIs)

A list of site URIs associated with the customer.

Example:


<siteURIs>

<siteURI

site_name="example.com">https://api.confidenttechnologies.com/vs/customers/cu

st001/sites/example.com001</siteURI>

</siteURIs>

[Table of Contents]

/vs/customers/{customer}/sites/{site}

The site resource holds data about a customer's site, used to access the authentication services of the

API.

GET

This request returns a representation of the specified site, if it exists. This request must be



https://api.confidenttechnologies.com/static/ws.html#site


Example:

GET /vs/customers/cust001/sites/example.com001


Status Code 200 - application/xml (boca:site)

A representation of the site, containing its name and a link to services.

Example:


<site>

<site_name>example.com</site_name>

<api_username>aLongRandomString</api_username>

<api_password>anotherLongRandomString</api_password>

<servicesURI>https://api.confidenttechnologies.com/vs/customers/cust001/sites

/example.com001/services</servicesURI>

<statsURI>https://api.confidenttechnologies.com/vs/customers/cust123/sites/ex

ample.com001/stats</statsURI>

</site>

[Table of Contents]

/vs/customers/{customer}/sites/{site}/resetcredentials

This request regenerates the API credentials for a site.

POST


Example:

POST vs/customers/cust001/sites/example.com001/resetcredentials


Status Code 200 - application/xml (boca:site)

The API credentials have been reset.

Example:



<site>

<site_name>example.com</site_name>

<api_username>aLongRandomString</api_username>

<api_password>anotherLongRandomString</api_password>

<servicesURI>https://api.confidenttechnologies.com/vs/customers/cust001/sites

/example.com001/services</servicesURI>


ample.com001/stats</statsURI>

</site>

Status Code 409

The site is has been previously deleted.

[Table of Contents]

/vs/customers/{customer}/sites/{site}/services

The services resource is a container for the API authentication services available for a site.

To enable services, send us an email through login.confidenttechnologies.com.

GET

This request returns the list of service URIs associated with the specified site. This request must be



Example:

GET /vs/customers/cust001/sites/example.com001/services


Status Code 200 - application/xml (boca:services)

A list of service URIs enabled for the specified site.

Example:


https://login.confidenttechnologies.com/


<services>

<service enabled="true" id="captcha">

https://api.confidenttechnologies.com/vs/customers/cust001/sites/example.com0

01/services/captcha</service>

<service enabled="false" id="smsotp">


01/services/smsotp</service>

<service enabled="false" id="voiceotp">


01/services/voiceotp</service>

<service enabled="false" id="voicepin">


01/services/voicepin</service>

<service enabled="false" id="voiceptl">


01/services/voiceptl</service>

<service enabled="false" id="imageshield">


01/services/imageshield</service>

</services>

[Table of Contents]

/vs/customers/{customer}/sites/{site}/stats

The site statistics resource is a container for the statistics available for a site.

GET

This request returns the list of statistics URIs associated with the specified site. This request must be



Example:

GET /vs/customers/cust001/sites/example.com001/stats



A list of statistics URIs available for the specified site.

Example:


<site_statistics>


<statsURI

id="success">https://api.confidenttechnologies.com/vs/customers/cust001/sites

/example.com001/stats/success</statsURI>

<statsURI

id="users">https://api.confidenttechnologies.com/vs/customers/cust001/sites/e

xample.com001/stats/users</statsURI>

</site_statistics>

[Table of Contents]

/vs/customers/{customer}/sites/{site}/stats/success

The site success statistics resource exposes statistics about service transactions. See the Statistics

section for more information about querying statistics.

GET

This request returns counts of transactions satisfying states over the specified time. The transaction

states are: created, authentication successful, authentication failed, authentication unattempted, delivery

refused, and delivery failed.


query parameters

parameter required description

from Yes

The starting date in ISO format. Statistics are reported starting at and

including this date. Note: there are no statistics available before April 1st,

2009.

to Yes The ending date in ISO format. Statistics are reported up to but not

including this date. It must be later than the from date.

granularity Yes Time period to aggregate statistics over. Permitted values are year,

month, and day.

Example:

GET /vs/customers/cust001/sites/example.com001/stats/users?from=2009-

03&to=2009-04&granularity=month


Status Code 200 - text/csv (boca:services)

A comma-separated values list of the specified statistics.

https://api.confidenttechnologies.com/static/ws.html#stats_doc


Example:

Content-Type: text/csv; charset=UTF-8

"Month","Service","Created","Authentication Successful","Authentication

Failed","Authentication Unattempted","Delivery Refused","Delivery Failed"

"2009-03","captcha",200,170,10,15,0,5

"2009-03","imageshield",150,120,30,5,0,5

"2009-03","smsotp",100,50,30,15,0,5

"2009-03","voiceotp",80,35,25,10,5,5

"2009-03","voicepin",90,44,33,0,0,13

"2009-03","voiceptl",100,80,15,0,0,5

[Table of Contents]

/vs/customers/{customer}/sites/{site}/stats/users

The site users statistics resource exposes statistics about the usage of premium services by site

users. See the Statistics section for more information about querying statistics.

GET

This request returns a count of users of a site's premium services over the specified time. If a user uses a

service multiple times during a time period, it is counted once.

It also returns the Combined count, which counts the unique users across premium services. If a user

uses several services multiple times during a time period, it is counted once.


query parameters


from Yes



2009.




month, and day.

Example:

GET /vs/customers/cust001/sites/example.com001/stats/users?from=2009-

03&to=2009-04&granularity=month






Example:


"Month","smsotp unique users","voiceotp unique users","voicepin unique

users","voiceptl unique users","imageshield unique users","site unique users"

"2009-03",35,3,0,15,76,82

[Table of Contents]

/vs/customers/{customer}/sites/{site}/services/imageshield

The ImageShield service allows a site to create ImageShield resources. This is a paid service, disabled

by default

GET

This request returns the list of ImageShield settings and stats. This request must be authenticated with

the site API credentials.


Example:

GET /vs/customers/cust001/sites/example.com001/services/imageshield


Status Code 200 - application/xml (boca:settings)

A list of settings for the ImageShield service.

Example:


<imageshield_service>

<settings/>


ample.com001/services/imageshield/stats</statsURI>

</imageshield_service>

Status Code 404

https://api.confidenttechnologies.com/static/ws.html#imageshield


The ImageShield service is not enabled for this site, contact Confident Technologies Sales to

enable it.

[Table of Contents]

POST

This request generates a new ImageShield. This request must be authenticated with the site API

credentials.


query parameters

parameter default required description

imageshield_length 2 No Number of categories that must be entered to

solve the ImageShield.

order_matters False No Whether the categories should be entered in

order.

width 3 No Width of the ImageShield in images. width

multiplied by height may not exceed 26.

height 3 No Height of the ImageShield in images. width

multiplied by height may not exceed 26.

image_code_color Red No

Color of the image code. Valid colors are:

White, Red, Orange, Yellow, Green, Teal,

Blue, Indigo, Violet, Gray

show_letters True No

Show the image code on the image, or make

it nearly invisible. Invisible image codes are

appropriate for clickable ImageShields.

use_category_images False No

Generate an ImageShield with the category

representative images. This can be used as an

optional practice step in an enrollment

process, so that the user can find the familiar

images. It should not be used during normal

authentication.

bundle N/A Yes

Colon-delimited list of category-ids. It must

be height * width elements in length. The

first imageshield_length category-ids are

used as the auth-categories.

user_id N/A Yes

Unique identifier for the end-user. Must not

exceed 100 characters. For more information,

see the user_id section above.

encrypt_config_with_passcode N/A No Encrypts the parameters with the given

passcode and user_id, and adds an element

https://api.confidenttechnologies.com/static/ws.html#user_ids


encrypted_config to the XML. The

encrypted string represents the

imageshield_length, order_matters,

width, height, image_code_color,

show_letters, and bundle, and is padded to

hide information about the bundle length. The

encrypted string can be used in future calls

with encrypted_config and

encrypted_passcode.

encrypted_config N/A No

Load the configuration in the encrypted

string, generated from a previous

ImageShield created with

encrypt_config_with_passcode. Must be

used with encrypted_passcode. When this

is used, the bundle and other parameters are

in the encrypted string and are no longer

required. However, user_id is still required

to decrypt the encrypted string.

encrypted_passcode N/A No

The passcode for the encrypted string, used

when generating a previous ImageShield with

encrypt_config_with_passcode. Must be

used with encrypted_config. When this is

used, the bundle and other parameters are in

the encrypted string and are no longer

required. However, user_id is still required

to decrypt the encrypted string.

Example:

Standard usage: POST vs/customers/cust001/sites/example.com001/services/imageshield

Content-Type: application/x-www-form-urlencoded

imageshield_length=3&order_matters=True&width=3&height=4&

image_code_color=Red&show_letters=true&bundle=food0001:clocks01:

wldanml1:dogs0001:insects1:skyscrp1:houses01:tysngms1:comptrs1:flowers1:

people01:stndgls1&user_id=hash_of_some_user_id

Example:

Generating encrypted config: POST vs/customers/cust001/sites/example.com001/services/imageshield


imageshield_length=3&order_matters=True&width=3&height=4&

image_code_color=Red&show_letters=true&bundle=food0001:clocks01:

wldanml1:dogs0001:insects1:skyscrp1:houses01:tysngms1:comptrs1:flowers1:

people01:stndgls1&user_id=hash_of_some_user_id&


encrypted_config_with_passcode=p@ssc0de

Example:

Using encrypted config: POST vs/customers/cust001/sites/example.com001/services/imageshield


user_id=hash_of_some_user_id&encrypted_config=YQNhYWFhYWFhYWFhYWFhY

Wh9wrGtedtSLBYE6zc3aC0wdgNI7JPYeLJU-xHnjcHjV5XlbA2mruUWZh_o2m2O8kJt

_L_IllNdn4-G0lyO7D6oBMDNnZQm0ROALPfXaWts8d5GNLF9Ve_-DTuiv7lwiA&

encrypted_passcode=p@ssc0de


Status Code 201 - application/xml (boca:imageshield)

The ImageShield has been created (Standard usage).

Example:


Location: https://api.confidenttechnologies.com/vs/imageshields/xyz890

<imageshield

uri="https://api.confidenttechnologies.com/vs/imageshields/xyz890">

<id>xyz890</id>

<imageshield_length>3</imageshield_length>

<order_matters>True</order_matters>

<width>3</width>

<height>4</height>

<letters>ABCDEFGHIJKL</letters>

<image_code_color>Red</image_code_color>

<imageURI

has_letters="true">https://api.confidenttechnologies.com/vs/imageshields/xyz8

90/image</imageURI>

<attempted>false</attempted>

<authenticated>false</authenticated>

</imageshield>


The ImageShield has been created (Generating encrypted config with

encrypted_config_with_passcode).

Example:


Location: https://api.confidenttechnologies.com/vs/imageshields/xyz890

<imageshield



<id>xyz890</id>



<width>3</width>

<height>4</height>



<imageURI


90/image</imageURI>



<encrypted_config>YQNhYWFhYWFhYWFhYWFhYWh9wrGtedtSLBYE6zc3aC0wd

gNI7JPYeLJU-xHnjcHjV5XlbA2mruUWZh_o2m2O8kJt_L_IllNdn4-G0lyO7D6oBM

DNnZQm0ROALPfXaWts8d5GNLF9Ve_-DTuiv7lwiA</encrypted_config>

</imageshield>

Status Code 404

The ImageShield service is not enabled for this site.

[Table of Contents]

/vs/customers/{customer}/sites/{site}/services/imageshield/stats

The imageshield statistics resource is a container for the statistics available for imageshield.

GET

This request returns the list of statistics URIs associated with imageshield. This request must be



Example:

GET /vs/customers/cust001/sites/example.com001/services/imageshield/stats



A list of statistics URIs available for the imageshield.

Example:


<imageshield_statistics>


<statsURI

id="success">https://api.confidenttechnologies.com/vs/customers/cust001/sites

/example.com001/services/imageshield/stats/success</statsURI>

<statsURI

id="users">https://api.confidenttechnologies.com/vs/customers/cust001/sites/e

xample.com001/services/imageshield/stats/users</statsURI>

</imageshield_statistics>

[Table of Contents]

/vs/customers/{customer}/sites/{site}/services/imageshield/stats/success

The ImageShield success statistics resource exposes statistics about ImageShield transactions.

See the Statistics section for more information about querying statistics.

GET

This request returns counts of ImageShield transactions satisfying states over the specified time. The

transaction states are: created, authentication successful, authentication failed, authentication

unattempted, delivery refused, and delivery failed.


query parameters


from Yes



2009.




month, and day.

Example:

GET

/vs/customers/{customer}/sites/{site}/services/imageshield/stats/success?from

=2009-03&to=2009-04&granularity=month






Example:


"Month","Service","Created","Authentication Successful","Authentication

Failed","Authentication Unattempted","Delivery Refused","Delivery Failed"

"2009-03","imageshield",150,120,30,5,0,5

[Table of Contents]

/vs/customers/{customer}/sites/{site}/services/imageshield/stats/users

The imageshield users statistics resource exposes statistics about the usage of imageshield by

site users. See the Statistics section for more information about querying statistics.

GET

This request returns a count of users of the imageshield service over the specified time. If a user uses a

service multiple times during a time period, it is counted once.


query parameters


from Yes



2009.




month, day, hour, and total.

Example:

GET

/vs/customers/cust001/sites/example.com001/services/imageshield/stats/users?f

rom=2009-03&to=2009-04&granularity=month






Example:


"Month","imageshield unique users"

"2009-03",154

[Table of Contents]

/vs/imageshields/{imageshield_id}

The ImageShield resource holds a ImageShield for a site's user. The resource is publicly available so

that a web browser can make requests without authentication.

GET

Returns the specified ImageShield. This request does not need to be authenticated.


Example:

GET /vs/imageshields/xyz890



The ImageShield's id, and imageURI are included in the response.

Example:


<imageshield


<id>xyz890</id>



<width>3</width>

<height>4</height>



<imageURI


90/image</imageURI>




</imageshield>

Status Code 410

This ImageShield has expired.

[Table of Contents]

POST

This request verifies that the code is correct for the specified ImageShield. This request does not need

to be authenticated.


query parameters


code Yes Code to verify.

Example:

POST /vs/imageshields/xyz890


code=xyz


Status Code 200

Authentication was successful.

Status Code 409

This ImageShield has already been attempted, and cannot be attempted again.

Status Code 410


Status Code 430

Authentication failed because the code is incorrect, the image has not been fetched, or the

submission occurred too soon after fetching the image.

[Table of Contents]


/vs/imageshields/{imageshield_id}/image

The ImageShield image resource holds a ImageShield image for a site's user. The resource is publicly

available so that a web browser can make requests without authentication.

GET

Returns the image for the specified ImageShield. This request does not have to be authenticated.


Example:

GET /vs/imageshield/xyz890/image


Status Code 200 - image/jpeg

Status Code 410


[Table of Contents]

Confident Technologies Image based Authentication Serviceconfidenttech.com/files/Image-Based_Strong_Authentication_Web_A… · Confident Technologies Image-based Authentication Service

Documents