Documentation Powered by Redocly

DOUBLECheck API (1.2.13)

Download OpenAPI specification:Download

E-mail: info@doublesecuritytechnologies.com URL: https://double-check.es/contact License: Condiciones Generales de Uso del Servicio de DOUBLECheck Terms of Service

DOUBLECheck is a Web Service provided by Double Security Technologies S.L. that enables a multi-factor authentication solution available for every organization of any size with a simple and economic approach.

Authentication

client-certificate

DOUBLECheck Certificates issued to clients of the service. All client requests are required to be presented with a valid Client Certificate.

Security Scheme Type mutualTLS

Introduction

The DOUBLECheck service is a REST based Web Service that enables application owners to increase the level of security of their applications.

The use of Two-Factor Authentication (2FA) allows applications to have more than one element to authenticate its users. Usually, applications authenticate its users through some password that only the user knows. With 2FA, the application may ask for an additional element of authentication that only the correct user can provide.

DOUBLECheck provides applications with a device that can produce a nearly impossible to guess password that can only be used one time, and is only valid for a very short period of time, so that it can only be obtained with the enabled device. This allows applications to validate users that have the designated device, thus authenticating the user through an additional means; the user must know his password and must have his device.

REST Web Service Interface

This web service follows the REST principles; there are specific resources that can be acted upon through the HTTP actions (GET, POST, PUT, DELETE). The main resource is Account. Other resources are part of the system too, such as Token and Certificate. The resources are identified through the use of URIs and have a representation through the use of XML or JSON objects.

Access Control with Certificates

You need a Client Certificate to make every call to the system. The authentication and security of the system is handled by a 2-way certificate HTTPS 1.1/TLS 1.2 communication, also known as Mutual TLS. You need at the very least (not recommended to handle all communications) your Master Client Certificate, which can only be obtained through the DOUBLECheck Web Service's Portal. Once you have your master certificate, you can request a client certificate that you should be using to handle all communications from your client application.

If you call the service's end-points from your different applications, you may request different client certificates for each of them. This is not required, although it is recommended because you can handle independently your Private Keys for each of the client certificates.

The certificates used by the system are X.509 v3 compliant (as defined in [RFC5280]) so they can be used without problems in standard HTTP/TLS communications with the server, meaning you can use your programming language's usual support for HTTPS Communications with Mutual TLS. The Certificate Authority for these certificates belongs to the system, so these certificates will not be recognized elsewhere.

In order to request a Client Certificate from the system, you need to create a standard PKCS#10 Certificate Sign Request (CSR, as defined in [RFC2986]). There are tools available that can help you with this task such as openssl req (recommended, see examples). By generating your own sets of Key Pairs, you have the absolute guarantee that your Private Keys are kept secret in your own systems.

Account

Account is a concept, not an entity. Your system's users are mapped to the User entity, and they can be grouped by Application entities which represent one of your own systems or applications. All of your elements will be uniquely related to your Tenant in the web service. Collectively, we refer to this combination of elements as Account.

By this concept, all of the operations that are requested from the system using the Account resource, will be identified by the account keyword followed by some or all of the components that identify the part of the account resource that you are working with. The components will be the Tenant, Application, and User identifiers with the standard separator between them:

account/{TenantIdfr}/{ApplicationIdfr}/{UserIdfr}

By relating your system's users to the web service's User element, you may refer to them when creating the token and when validating the password challenge.

If you may not want to distinguish between applications, or making any grouping of users, you would be using the default Generic Application represented throughout by the * identifier.

You can also define the characteristics of all the tokens that belong to each of your applications as well as the conditions to create and manage them at the Application level using Application Settings.

HTTP End-point

https://api.double-check.es/v1/account/{TenantIdfr}/{ApplicationIdfr}/{UserIdfr}

This end-point exposes 6 operations:

OperationDescription
List Tokens of AccountRetrieve the List of Tokens corresponding with the specified Account.
Create Token for AccountAdd a new Token to the specified Account.
Provision Token for AccountPrepare a new Token within the specified Account to be synchronized with the user's device.
Verify PasswordVerify a proposed Password for the specified Account.
Send SMSSend an SMS with a One-time Password to the specified Account.
Obtain a Bypass PasswordObtain a Bypass Password for the specified Account.

Business Operations

At the Account level, the majority of the main business operations of the DOUBLECheck web service are dispatched. The idea of organizing everything around the account is that later, the authentication operations will be requested from the system by referencing de desired user's account.

All of the Tokens generated in the system are always assigned to a single user. The token is the element that allows the client to make a positive authentication of themself if properly configured and used.

The system allows for a lot of flexibility into how the users may be organized, and how the assigned tokens behave. The tokens may be configured in many ways and their life-cycle can be as simple or as complex as the client's needs are.

List Tokens of Account

Retrieve the List of Tokens corresponding with the specified Account.

GET /v1/account/{tenantIdfr}/{applicationIdfr}/{userIdfr}/tokens

The account is determined by its full Account Identifier:

Each user can have as many tokens as it needs, keeping in mind that all of the ACTIVE tokens will be used to authenticate the user.

Authorizations:
client-certificate (
  • account/listTokens
)
path Parameters
tenantIdfr
required
string
Example: TEST

Identifier of the Tenant. It is asigned to each client at creation time by the system. It usually consists of 3 to 8 capital letters resembling the name of the client company.

applicationIdfr
required
string
Example: WEB

Identifier of the Application. An acronim or word (without spaces) preferably in capital letters that resembles the name of the real application (or grouping). It has to be unique within the tenant. The default application is always available and can be identified with *.

userIdfr
required
string
Example: jdoe@test.com

Identifier of the User. It has to be unique within the application (or tenant). The identifier that was selected for the specified user at creation time. The client is free to use any format to identify its users.

Responses

Response samples

Content type
application/json
application/json
application/xml
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Create Token for Account

Add a new Token to the specified Account.

POST /v1/account/{tenantIdfr}/{applicationIdfr}/{userIdfr}/createToken

The account is determined by its full Account Identifier:

Only tokens of types DEFAULT, SMS, and BYPASS, can be created using this operation, since only these token types can be completely created correctly with this single operation. The other types of token (TOTP, and HOTP) should be prepared for creation using Provision Token instead.

A new token will be created and associated to the specified user. The token will be in a CREATED state and will not be ACTIVE until explicitly activating it, or unless it is configured to be activated at creation, and the type of token allows for immediate activation.

Each user may have as many tokens as it needs, keeping in mind that all ACTIVE tokens will be used to authenticate the user, with the overhead it adds to the calculations time.

Authorizations:
client-certificate (
  • account/createToken
)
path Parameters
tenantIdfr
required
string
Example: TEST

Identifier of the Tenant. It is asigned to each client at creation time by the system. It usually consists of 3 to 8 capital letters resembling the name of the client company.

applicationIdfr
required
string
Example: WEB

Identifier of the Application. An acronim or word (without spaces) preferably in capital letters that resembles the name of the real application (or grouping). It has to be unique within the tenant. The default application is always available and can be identified with *.

userIdfr
required
string
Example: jdoe@test.com

Identifier of the User. It has to be unique within the application (or tenant). The identifier that was selected for the specified user at creation time. The client is free to use any format to identify its users.

query Parameters
tokenType
string
Example: tokenType=SMS

The type of the Token to be created. At creation time, all the characteristics of the token will be applied from the Settings defined for the corresponding Token Type.

Valid values are: SMS, BYPASS, and DEFAULT.

Default is DEFAULT.

Responses

Response samples

Content type
application/json
application/json
application/xml
{
  • "tokenIdfr": "TEST18273645",
  • "type": "DEFAULT",
  • "status": "CREATED",
  • "algorithm": "HMacSHA1",
  • "numDigits": 6,
  • "period": "30s"
}

Provision Token for Account

Prepare a new Token within the specified Account to be synchronized with the user's device.

POST /v1/account/{tenantIdfr}/{applicationIdfr}/{userIdfr}/provisionToken

The account is determined by its full Account Identifier:

A new token will be provisioned, associated to the specified user. The token will be in a PROVISIONED state. The system will be ready for the user's device to request the synchronization with the prepared token.

The system will only wait for a determined period of time. If the device does not request the token within the alloted time (Default is 5 min), then the token will go to an EXPIRED state. After the token has expired, it CANNOT go back to a useful state and SHOULD be DELETED and a new token be provisioned.

Each user may have as many tokens as it needs, keeping in mind that all ACTIVE tokens will be used to authenticate the user.

Authorizations:
client-certificate (
  • account/provisionToken
)
path Parameters
tenantIdfr
required
string
Example: TEST

Identifier of the Tenant. It is asigned to each client at creation time by the system. It usually consists of 3 to 8 capital letters resembling the name of the client company.

applicationIdfr
required
string
Example: WEB

Identifier of the Application. An acronim or word (without spaces) preferably in capital letters that resembles the name of the real application (or grouping). It has to be unique within the tenant. The default application is always available and can be identified with *.

userIdfr
required
string
Example: jdoe@test.com

Identifier of the User. It has to be unique within the application (or tenant). The identifier that was selected for the specified user at creation time. The client is free to use any format to identify its users.

Responses

Response samples

Content type
application/json
application/json
application/xml
{
  • "tokenIdfr": "TEST18273645",
  • "type": "DEFAULT",
  • "status": "PROVISIONED",
  • "algorithm": "HMacSHA1",
  • "numDigits": 6,
  • "period": "30s"
}

Verify Password

Verify a proposed Password for the specified Account.

POST /v1/account/{tenantIdfr}/{applicationIdfr}/{userIdfr}/verifyPassword

The account is determined by its full Account Identifier:

This is the most important function of the web service. The verification is done for a specific user and its related tokens. This method locates all the tokens related to the user and calculates the value for the current password so it can be compared with the provided value. Any of the tokens related to the user may be the one that matches the proposed password.

Only ACTIVE tokens MAY be used to verify a password.

A successful verification DOES NOT imply a correct match of the password. After receiving a successful return code from the web service, the client application MUST check the contents of the Verification Response to see the result of the verification. Possible outcomes of the verification process include, of course, a successful verification, and also, an incorrect proposed password. But other situations may arise from the execution of the method in the system. See the following table for a reference of the possible return codes.

Password Verification Return Codes

CodeResultReason
000SUCCESSVerification OK
010USED PASSWORDPassword already used
100TOKEN ERROR, GENERICGeneric token problem
101TOKEN ERROR, NOT FOUNDToken not found
102TOKEN ERROR, NOT ACTIVEToken is not active
200ACCOUNT ERROR, GENERICGeneric account problem
201ACCOUNT ERROR, NO TOKENAccount without related tokens
500FAILWrong password
900SYSTEM ERRORSystem/Service problem
Authorizations:
client-certificate (
  • account/verifyPassword
)
path Parameters
tenantIdfr
required
string
Example: TEST

Identifier of the Tenant. It is asigned to each client at creation time by the system. It usually consists of 3 to 8 capital letters resembling the name of the client company.

applicationIdfr
required
string
Example: WEB

Identifier of the Application. An acronim or word (without spaces) preferably in capital letters that resembles the name of the real application (or grouping). It has to be unique within the tenant. The default application is always available and can be identified with *.

userIdfr
required
string
Example: jdoe@test.com

Identifier of the User. It has to be unique within the application (or tenant). The identifier that was selected for the specified user at creation time. The client is free to use any format to identify its users.

query Parameters
password
required
string
Example: password=123456

The proposed password to be verified for the specified user.

challenge
string
Example: challenge=CAzqgAwIBAgIUXxE/lef8vyAwPJP2mJXPRJajMa0

Value of the element to be used in the hash to obtain the one-time password in a hash-based generator (HOTP).

Responses

Response samples

Content type
application/json
application/json
application/xml
Example
Success
Success
Wrong Password
Used Password
{
  • "code": "000",
  • "result": "SUCCESS",
  • "reason": "Verification OK"
}

Send SMS

Send an SMS with a One-time Password to the specified Account.

POST /v1/account/{tenantIdfr}/{applicationIdfr}/{userIdfr}/sendSMS

The account is determined by its full Account Identifier:

An SMS will be sent to a mobile phone based on the provided phoneNumber query parameter, or the phoneNumber in record for the corresponding user. The given parameter to the method takes precedence over the phone number in record.

DOUBLECheck does not recommend the use of SMS as a means to authenticate users due to the lack of security that this method poses. This method is only recommended as an alternative when a user cannot make use of a better token, or to make a second validation upon activation of the token.

Authorizations:
client-certificate (
  • account/sendSMS
)
path Parameters
tenantIdfr
required
string
Example: TEST

Identifier of the Tenant. It is asigned to each client at creation time by the system. It usually consists of 3 to 8 capital letters resembling the name of the client company.

applicationIdfr
required
string
Example: WEB

Identifier of the Application. An acronim or word (without spaces) preferably in capital letters that resembles the name of the real application (or grouping). It has to be unique within the tenant. The default application is always available and can be identified with *.

userIdfr
required
string
Example: jdoe@test.com

Identifier of the User. It has to be unique within the application (or tenant). The identifier that was selected for the specified user at creation time. The client is free to use any format to identify its users.

query Parameters
phoneNumber
string
Example: phoneNumber=%2B34812543976

Important: It has to be URL encoded. This means that the + sign has to be represented by the %2B escape sequence.

A mobile phone number in in a valid E.164 format to be used. If not present, phone number on record will be used.

The phoneNumber has to be in a valid E.164 format (ITU-T E.164 - The international public telecommunication numbering plan). This phone number format allows phone calls and text messages can be correctly routed to individual phones in different countries. E.164 numbers are formatted: [+] [country code] [subscriber number including area code] no spaces, and can have a maximum of fifteen digits.

Responses

Response samples

Content type
text/plain
Not a valid phone number: 34-8X25X3976

Obtain a Bypass Password

Obtain a Bypass Password for the specified Account.

POST /v1/account/{tenantIdfr}/{applicationIdfr}/{userIdfr}/bypass

The account is determined by its full Account Identifier:

A One-time password will be generated that can then be provided to the user through a secure channel of communications, so that the user can enter it to your application and be able to conduct his business.

This method SHOULD ONLY be used as a last resort when a user that has been duly authenticated through other means, and he or she has no access to the DOUBLECheck token, and needs to conduct some activity on your system that requires the verification of a token generated one-time password.

DOUBLECheck does not recommend the use of the Bypass Password if your organization is not capable of fully authenticating a user through other means such as a support center applying a questionnaire, and after that process, be able to communicate the bypass password to the user in a secure fashion.

This method is only recommended as an alternative when a user cannot make use of a better token.

Authorizations:
client-certificate (
  • account/bypass
)
path Parameters
tenantIdfr
required
string
Example: TEST

Identifier of the Tenant. It is asigned to each client at creation time by the system. It usually consists of 3 to 8 capital letters resembling the name of the client company.

applicationIdfr
required
string
Example: WEB

Identifier of the Application. An acronim or word (without spaces) preferably in capital letters that resembles the name of the real application (or grouping). It has to be unique within the tenant. The default application is always available and can be identified with *.

userIdfr
required
string
Example: jdoe@test.com

Identifier of the User. It has to be unique within the application (or tenant). The identifier that was selected for the specified user at creation time. The client is free to use any format to identify its users.

Responses

Response samples

Content type
text/plain
123456

Tenant

A Tenant represents the client of the DOUBLECheck Web Service, it is your organization or institution.

Once the tenant has enrolled with the web service, a record will remain to keep track of everything the tenant has and does. It holds the identity of the tenant, including material such as your logo and the Issuer Certificate to sign Certificate Sign Requests. It also contains all the elements that will conform the service: Applications, Users, Tokens, Certificates, etc.

Every tenant is able to configure their service preferences and this entity is central to every activity in the system.

HTTP End-point

https://api.double-check.es/v1/account/{TenantIdfr}

This end-point exposes 7 operations:

OperationDescription
Get TenantRetrieve the specified Tenant object from the system.
Update TenantUpdate the specified Tenant object in the system.
Get Tenant LogoRetrieve the Logo image in record for the specified Tenant.
Load Tenant LogoUpload or update the Logo image in record for the specified Tenant.
List Applications of TenantRetrieve the List of Applications from the collection of the specified Tenant.
List Users of TenantRetrieve the List of Users corresponding to the specified Tenant.
Create ApplicationAdd a new Application to the Tenant's collection.

Get Tenant

Retrieve the specified Tenant object from the system.

GET /v1/account/{tenantIdfr}

This method returns the general information about your tenant record in the system.

You can only pull information about your own tenant from the system.

Authorizations:
client-certificate (
  • account/getTenant
)
path Parameters
tenantIdfr
required
string
Example: TEST

Identifier of the Tenant. It is asigned to each client at creation time by the system. It usually consists of 3 to 8 capital letters resembling the name of the client company.

Responses

Response samples

Content type
application/json
application/json
application/xml
{
  • "idfr": "TEST",
  • "name": "Test Corporation",
  • "domain": "testco.com",
  • "prefix": "TEST"
}

Update Tenant

Update the specified Tenant object in the system.

PATCH /v1/account/{tenantIdfr}

Only the pieces of information that will change are required in the body object, and the idfr property that MUST be identical to the Path Parameter tenantIdfr. Meaning, of course, that the identifier cannot be changed.

There are only specific pieces of information about the tenant that can be updated by the client.

Authorizations:
client-certificate (
  • account/updateTenant
)
path Parameters
tenantIdfr
required
string
Example: TEST

Identifier of the Tenant. It is asigned to each client at creation time by the system. It usually consists of 3 to 8 capital letters resembling the name of the client company.

Request Body schema:
application/json
application/json
application/xml
application/x-www-form-urlencoded

Tenant object, only with the changing properties to be updated on the corresponding tenant record. The idfr property MUST be identical to the Path Parameter tenantIdfr.

idfr
required
string

Identifier of the Tenant. Three to eight capital letters that resemble the name of the client organization. It is assigned by the system at creation time, and is unique to this tenant. It is used throughout the system to identify the tenant.

name
string

Formal name of the client's organization that the specified tenant represents. It is used as a label in several display moments to fully describe the tenant appropriately.

domain
string

Internet domain registered by the client organization or institution. This serves as a unique identifier not specific to the system. In some cases is used to locate your tenant in a user-friendly way (such as when your own users need to refer to your organization within the mobile app).

prefix
string

Three to eight capital letters that resemble the name of the organization, that are assigned at creation of the tenant object in the system. Usually are the same as the identifier of the tenant, but there are exceptions. This prefix is used while naming other objects in the system that are unique to this tenant (such as tokens and certificates).

Responses

Request samples

Content type
application/json
application/json
application/xml
application/x-www-form-urlencoded
{
  • "idfr": "TEST",
  • "domain": "testcorporation.com"
}

Response samples

Content type
text/plain
This functionality will be available in the future.

List Applications of Tenant

Retrieve the List of Applications from the collection of the specified Tenant.

GET /v1/account/{tenantIdfr}/applications

At least, the default Generic Application idfr = * will always be present.

Each tenant can have as many applications as it needs, keeping in mind that each user can be related to ONLY ONE application.

Authorizations:
client-certificate (
  • account/listApplications
)
path Parameters
tenantIdfr
required
string
Example: TEST

Identifier of the Tenant. It is asigned to each client at creation time by the system. It usually consists of 3 to 8 capital letters resembling the name of the client company.

Responses

Response samples

Content type
application/json
application/json
application/xml
[
  • {
    },
  • {
    }
]

List Users of Tenant

Retrieve the List of Users corresponding to the specified Tenant.

GET /v1/account/{tenantIdfr}/users

This will include all of the users related to this tenant regardless of the application that each user is related to.

Each tenant can have as many users as it needs, keeping in mind that each user can be related to ONLY ONE application.

Authorizations:
client-certificate (
  • account/listUsersOfTenant
)
path Parameters
tenantIdfr
required
string
Example: TEST

Identifier of the Tenant. It is asigned to each client at creation time by the system. It usually consists of 3 to 8 capital letters resembling the name of the client company.

Responses

Response samples

Content type
application/json
application/json
application/xml
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Create Application

Add a new Application to the Tenant's collection.

POST /v1/account/{tenantIdfr}/application

Each tenant can create as many applications as it needs, keeping in mind that each user can be related to ONLY ONE application.

Authorizations:
client-certificate (
  • account/createApplication
)
path Parameters
tenantIdfr
required
string
Example: TEST

Identifier of the Tenant. It is asigned to each client at creation time by the system. It usually consists of 3 to 8 capital letters resembling the name of the client company.

Request Body schema:
application/json
application/json
application/xml

Application object with the general contents to create a new application on the specified tenant.

idfr
required
string

Identifier of the Application. An acronim or word (without spaces) preferably in capital letters that resembles the name of the real application (or grouping). It has to be unique within the Tenant.

name
string

Formal name of the application (or grouping). It will be used in several display moments to reference the application, including the user's device.

description
string

A more complete description about the application. It can be used in display moments.

Responses

Request samples

Content type
application/json
application/json
application/xml
{
  • "idfr": "WEB",
  • "name": "Web Portal",
  • "description": "Web Portal Application for Test Corporation"
}

Response samples

Content type
application/json
application/json
application/xml
{
  • "idfr": "WEB",
  • "name": "Web Portal",
  • "description": "Web Portal Application for Test Corporation"
}

Application

An Application represents one of your own systems or applications for which you want that the DOUBLECheck Web Service to provide the MFA level security. It is any of your applications that require DOUBLECheck either to login or to perform any specific authentication verification functions, at which point the application will use the service to verify the user's authenticity.

If you decide to manage your applications with this service, then you will manage this kind of resource. If you don't need to distinguish between applications that use the service, then the Application object may remain generic Application = *. The Generic Application does not need to be created, it is automatically created for every client when the Tenant is created.

You may fancy to add a specific logo to each of your applications. If you don't, the application will be presented with your company logo (which must have been added at the tenant level).

HTTP End-point

https://api.double-check.es/v1/account/{TenantIdfr}/{ApplicationIdfr}

This end-point exposes 7 operations:

OperationDescription
Get ApplicationRetrieve the specified Application object object from the system.
Update ApplicationUpdate the specified Application object in the system.
Delete ApplicationDelete the specified Application object from the system.
Get Application LogoRetrieve the Logo image in record for the specified Tenant.
Load Application LogoUpload or update the Logo image in record for the specified Application.
List Users of ApplicationRetrieve the List of Users from the specified Application.
Create UserAdd a new User to the specified Application.

Get Application

Retrieve the specified Application object from the system.

GET /v1/account/{tenantIdfr}/{applicationIdfr}

This method returns the information about the application record in the system. You can only pull information about applications belonging to your own tenant from the system.

Authorizations:
client-certificate (
  • account/getApplication
)
path Parameters
tenantIdfr
required
string
Example: TEST

Identifier of the Tenant. It is asigned to each client at creation time by the system. It usually consists of 3 to 8 capital letters resembling the name of the client company.

applicationIdfr
required
string
Example: WEB

Identifier of the Application. An acronim or word (without spaces) preferably in capital letters that resembles the name of the real application (or grouping). It has to be unique within the tenant. The default application is always available and can be identified with *.

Responses

Response samples

Content type
application/json
application/json
application/xml
{
  • "idfr": "WEB",
  • "name": "Web Portal",
  • "description": "Web Portal Application for Test Corporation"
}

Update Application

Update the specified Application object in the system.

PATCH /v1/account/{tenantIdfr}/{applicationIdfr}

Only the pieces of information that will change are required in the body object, and the idfr property that MUST be identical to the Path Parameter applicationIdfr. Meaning, of course, that the identifier cannot be changed.

It is possible for the client to make changes to the properties of the default Generic Application * (although not recommended - it is preferable to create additional applications).

Authorizations:
client-certificate (
  • account/updateApplication
)
path Parameters
tenantIdfr
required
string
Example: TEST

Identifier of the Tenant. It is asigned to each client at creation time by the system. It usually consists of 3 to 8 capital letters resembling the name of the client company.

applicationIdfr
required
string
Example: WEB

Identifier of the Application. An acronim or word (without spaces) preferably in capital letters that resembles the name of the real application (or grouping). It has to be unique within the tenant. The default application is always available and can be identified with *.

Request Body schema:
application/json
application/json
application/xml
application/x-www-form-urlencoded

Application object, only with the changing properties to be updated on the corresponding application record. The idfr property MUST be identical to the Path Parameter applicationIdfr.

idfr
required
string

Identifier of the Application. An acronim or word (without spaces) preferably in capital letters that resembles the name of the real application (or grouping). It has to be unique within the Tenant.

name
string

Formal name of the application (or grouping). It will be used in several display moments to reference the application, including the user's device.

description
string

A more complete description about the application. It can be used in display moments.

Responses

Request samples

Content type
application/json
application/json
application/xml
application/x-www-form-urlencoded
{
  • "idfr": "WEB",
  • "description": "Internet Web Portal Application for Test Corporation. Public access."
}

Response samples

Content type
text/plain
This functionality will be available in the future.

Delete Application

Delete the specified Application object from the system.

DELETE /v1/account/{tenantIdfr}/{applicationIdfr}

Authorizations:
client-certificate (
  • account/deleteApplication
)
path Parameters
tenantIdfr
required
string
Example: TEST

Identifier of the Tenant. It is asigned to each client at creation time by the system. It usually consists of 3 to 8 capital letters resembling the name of the client company.

applicationIdfr
required
string
Example: WEB

Identifier of the Application. An acronim or word (without spaces) preferably in capital letters that resembles the name of the real application (or grouping). It has to be unique within the tenant. The default application is always available and can be identified with *.

Responses

Response samples

Content type
application/json
application/json
application/xml
{
  • "idfr": "WEB",
  • "name": "Web Portal",
  • "description": "Web Portal Application for Test Corporation"
}

List Users of Application

Retrieve the List of Users from the specified Application.

GET /v1/account/{tenantIdfr}/{applicationIdfr}/users

Each tenant can have as many users as it needs, keeping in mind that each user can be related to ONLY ONE application.

Authorizations:
client-certificate (
  • account/listUsersOfApplication
)
path Parameters
tenantIdfr
required
string
Example: TEST

Identifier of the Tenant. It is asigned to each client at creation time by the system. It usually consists of 3 to 8 capital letters resembling the name of the client company.

applicationIdfr
required
string
Example: WEB

Identifier of the Application. An acronim or word (without spaces) preferably in capital letters that resembles the name of the real application (or grouping). It has to be unique within the tenant. The default application is always available and can be identified with *.

Responses

Response samples

Content type
application/json
application/json
application/xml
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Create User

Add a new User to the specified Application.

POST /v1/account/{tenantIdfr}/{applicationIdfr}/user

Each tenant can create as many users as it needs, keeping in mind that each user can be related to ONLY ONE application.

Authorizations:
client-certificate (
  • account/createUser
)
path Parameters
tenantIdfr
required
string
Example: TEST

Identifier of the Tenant. It is asigned to each client at creation time by the system. It usually consists of 3 to 8 capital letters resembling the name of the client company.

applicationIdfr
required
string
Example: WEB

Identifier of the Application. An acronim or word (without spaces) preferably in capital letters that resembles the name of the real application (or grouping). It has to be unique within the tenant. The default application is always available and can be identified with *.

Request Body schema:
application/json
application/json
application/xml

User object with the general contents to create a new user on the specified application.

idfr
required
string

Identifier of the User. Any string that is unique to the user within the tenant (or application). The client is free to choose the format of the identifier, it may be the same identifier as the one it uses in its own system, or it can be any other thing as long as it is unique to each user. If it is a numeric identifier, keep in mind that it will be treated and stored as a string.

For security reasons or for privacy concerns, the client may choose to have a unique identifier in this system that is not related to any of the personal information of the user, that only the client's system may relate.

name
string

Formal name of the user. It will be used in several display moments to reference the user, including the user's device.

The client may choose not to keep the user's name in the system for security reasons or privacy concerns. It is NOT REQUIRED by the system to have the users' names, but when the users are referenced within the system (at display moments or in messages), the more cryptic user's identifier will be used.

phoneNumber
string

The mobile phone number of the user. It is ONLY used by the system if the SMS token type is defined for the application, and the client decides to keep the phone numbers in the user's record for simplicity. See the Send SMS method for reference.

The phoneNumber has to be in a valid E.164 format (ITU-T E.164 - The international public telecommunication numbering plan). This phone number format allows phone calls and text messages can be correctly routed to individual phones in different countries. E.164 numbers are formatted: [+] [country code] [subscriber number including area code] no spaces, and can have a maximum of fifteen digits.

If the client decides not to keep the phone number in the record, it can still use the SMS functionality by providing the mobile phone number to the service while requesting the Send SMS operation, in which case, the service will never store or keep in any way the user's phone number.

eMail
string

The e-mail address of the user. It is ONLY used by the system to send e-mail notifications regarding operations made in the system about the user, such as a failed verification. These notifications can be configured and selected individually.

No other use of the email is ever done by the system. the user is no otherwise contacted by means of this e-mail address.

If the client decides not to keep the e-mail address in the record, then no notifications will be sent, and no errors or other form of warning will be issued to the user.

Responses

Request samples

Content type
application/json
application/json
application/xml
{
  • "idfr": "jdoe@test.com",
  • "name": "Jane Doe"
}

Response samples

Content type
application/json
application/json
application/xml
{
  • "idfr": "jdoe@test.com",
  • "name": "Jane Doe"
}

User

A User represents a person that is a device holder (or token holder). It is a user of your application or system and there is some unique identifier within your system for them.

The User will be the main object to work with the DOUBLECheck service, since the tokens are always related to a user, and the operation of validating the user's identity using the token is the main purpose of the service. Almost all of the main business functions are related to a user.

Any given user will be related to exactly one tenant and exactly one application of that same tenant. The application may be the Generic Application.

Token objects will be related to only one user. But a user may have more than one associated token. If a user has more than one token, a password verification for a user will be done against all of their associated tokens. It is enough for one of their tokens to have a match during verification, for the verification to be successful.

HTTP End-point

https://api.double-check.es/v1/account/{TenantIdfr}/{ApplicationIdfr}/{UserIdfr}

This end-point exposes 6 operations:

OperationDescription
Get UserRetrieve the specified User object from the system.
Update UserUpdate the specified User object in the system.
Delete UserDelete the specified User object from the system.
Get User PropertyRetrieve the Property assigned to the specified User.
Set User PropertySet or update a Property object assigned to the specified User.
Delete User PropertyDelete a Property object assigned to the specified User.

User Properties

Each user may have client defined Properties associated that may be used by the client's logic in any way it sees fit.

The idea behind this design, is to allow the client to store any related piece of information about the user that may be helpful later as provided by the DOUBLECheck system. This is a strictly convenience feature for the client and is totally up to the client to help themself with this feature. The DOUBLECheck system does not make use of any piece of information kept in the users' properties.

The properties are stored in a tag-value format where the tag is any string defined by the client and is identified by the tag keyword. It is sugested that the tags are formed as the sequence of needed words to give meaning to the property, separated by dots. The properties' tag attribute is case sensitive. And the value assigned to each property is identified by the value attribute of the Property object.

Get User

Retrieve the specified User object from the system.

GET /v1/account/{tenantIdfr}/{applicationIdfr}/{userIdfr}

This method returns the information in the user record. You can only pull information about users belonging to your own tenant from the system.

Authorizations:
client-certificate (
  • account/getUser
)
path Parameters
tenantIdfr
required
string
Example: TEST

Identifier of the Tenant. It is asigned to each client at creation time by the system. It usually consists of 3 to 8 capital letters resembling the name of the client company.

applicationIdfr
required
string
Example: WEB

Identifier of the Application. An acronim or word (without spaces) preferably in capital letters that resembles the name of the real application (or grouping). It has to be unique within the tenant. The default application is always available and can be identified with *.

userIdfr
required
string
Example: jdoe@test.com

Identifier of the User. It has to be unique within the application (or tenant). The identifier that was selected for the specified user at creation time. The client is free to use any format to identify its users.

Responses

Response samples

Content type
application/json
application/json
application/xml
{
  • "idfr": "jdoe@test.com",
  • "name": "Jane Doe"
}

Update User

Update the specified User object in the system.

PATCH /v1/account/{tenantIdfr}/{applicationIdfr}/{userIdfr}

Only the pieces of information that will change are required in the body object, and the idfr property that MUST be identical to the Path Parameter userIdfr. Meaning, of course, that the identifier cannot be changed.

Authorizations:
client-certificate (
  • account/updateUser
)
path Parameters
tenantIdfr
required
string
Example: TEST

Identifier of the Tenant. It is asigned to each client at creation time by the system. It usually consists of 3 to 8 capital letters resembling the name of the client company.

applicationIdfr
required
string
Example: WEB

Identifier of the Application. An acronim or word (without spaces) preferably in capital letters that resembles the name of the real application (or grouping). It has to be unique within the tenant. The default application is always available and can be identified with *.

userIdfr
required
string
Example: jdoe@test.com

Identifier of the User. It has to be unique within the application (or tenant). The identifier that was selected for the specified user at creation time. The client is free to use any format to identify its users.

Request Body schema:
application/json
application/json
application/xml
application/x-www-form-urlencoded

User object, only with the changing properties to be updated on the corresponding user record.

The idfr property MUST be present and be identical to the Path Parameter userIdfr.

idfr
required
string

Identifier of the User. Any string that is unique to the user within the tenant (or application). The client is free to choose the format of the identifier, it may be the same identifier as the one it uses in its own system, or it can be any other thing as long as it is unique to each user. If it is a numeric identifier, keep in mind that it will be treated and stored as a string.

For security reasons or for privacy concerns, the client may choose to have a unique identifier in this system that is not related to any of the personal information of the user, that only the client's system may relate.

name
string

Formal name of the user. It will be used in several display moments to reference the user, including the user's device.

The client may choose not to keep the user's name in the system for security reasons or privacy concerns. It is NOT REQUIRED by the system to have the users' names, but when the users are referenced within the system (at display moments or in messages), the more cryptic user's identifier will be used.

phoneNumber
string

The mobile phone number of the user. It is ONLY used by the system if the SMS token type is defined for the application, and the client decides to keep the phone numbers in the user's record for simplicity. See the Send SMS method for reference.

The phoneNumber has to be in a valid E.164 format (ITU-T E.164 - The international public telecommunication numbering plan). This phone number format allows phone calls and text messages can be correctly routed to individual phones in different countries. E.164 numbers are formatted: [+] [country code] [subscriber number including area code] no spaces, and can have a maximum of fifteen digits.

If the client decides not to keep the phone number in the record, it can still use the SMS functionality by providing the mobile phone number to the service while requesting the Send SMS operation, in which case, the service will never store or keep in any way the user's phone number.

eMail
string

The e-mail address of the user. It is ONLY used by the system to send e-mail notifications regarding operations made in the system about the user, such as a failed verification. These notifications can be configured and selected individually.

No other use of the email is ever done by the system. the user is no otherwise contacted by means of this e-mail address.

If the client decides not to keep the e-mail address in the record, then no notifications will be sent, and no errors or other form of warning will be issued to the user.

Responses

Request samples

Content type
application/json
application/json
application/xml
application/x-www-form-urlencoded
{
  • "idfr": "jdoe@test.com",
  • "phoneNumber": "+34912345678"
}

Response samples

Content type
application/json
application/json
application/xml
{
  • "idfr": "jdoe@test.com",
  • "name": "Jane Doe",
  • "phoneNumber": "+34912345678"
}

Delete User

Delete the specified User object from the system.

DELETE /v1/account/{tenantIdfr}/{applicationIdfr}/{userIdfr}

Authorizations:
client-certificate (
  • account/deleteUser
)
path Parameters
tenantIdfr
required
string
Example: TEST

Identifier of the Tenant. It is asigned to each client at creation time by the system. It usually consists of 3 to 8 capital letters resembling the name of the client company.

applicationIdfr
required
string
Example: WEB

Identifier of the Application. An acronim or word (without spaces) preferably in capital letters that resembles the name of the real application (or grouping). It has to be unique within the tenant. The default application is always available and can be identified with *.

userIdfr
required
string
Example: jdoe@test.com

Identifier of the User. It has to be unique within the application (or tenant). The identifier that was selected for the specified user at creation time. The client is free to use any format to identify its users.

Responses

Response samples

Content type
application/json
application/json
application/xml
{
  • "idfr": "jdoe@test.com",
  • "name": "Jane Doe"
}

Get User Property

Retrieve the Property assigned to the specified User.

GET /v1/account/{tenantIdfr}/{applicationIdfr}/{userIdfr}/property

If tag parameter is present; you get the specific Property object with its current value in the system. If tag parameter is absent; you get a List of Properties that contains all of the properties associated with the specified user.

Authorizations:
client-certificate (
  • account/getUserProperties
)
path Parameters
tenantIdfr
required
string
Example: TEST

Identifier of the Tenant. It is asigned to each client at creation time by the system. It usually consists of 3 to 8 capital letters resembling the name of the client company.

applicationIdfr
required
string
Example: WEB

Identifier of the Application. An acronim or word (without spaces) preferably in capital letters that resembles the name of the real application (or grouping). It has to be unique within the tenant. The default application is always available and can be identified with *.

userIdfr
required
string
Example: jdoe@test.com

Identifier of the User. It has to be unique within the application (or tenant). The identifier that was selected for the specified user at creation time. The client is free to use any format to identify its users.

query Parameters
tag
string
Example: tag=some.property

The name of the requested property. If the parameter is missing, then a list of all the properties associated to the user will be returned.

Responses

Response samples

Content type
application/json
application/json
application/xml
Example
One property
One property
List of all properties
{
  • "tag": "some.property",
  • "value": "SomeValue"
}

Set User Property

Set or update a Property object assigned to the specified User.

PUT /v1/account/{tenantIdfr}/{applicationIdfr}/{userIdfr}/property

Establish the desired value for specific property assigned to the specified user.

Authorizations:
client-certificate (
  • account/setUserProperties
)
path Parameters
tenantIdfr
required
string
Example: TEST

Identifier of the Tenant. It is asigned to each client at creation time by the system. It usually consists of 3 to 8 capital letters resembling the name of the client company.

applicationIdfr
required
string
Example: WEB

Identifier of the Application. An acronim or word (without spaces) preferably in capital letters that resembles the name of the real application (or grouping). It has to be unique within the tenant. The default application is always available and can be identified with *.

userIdfr
required
string
Example: jdoe@test.com

Identifier of the User. It has to be unique within the application (or tenant). The identifier that was selected for the specified user at creation time. The client is free to use any format to identify its users.

query Parameters
tag
required
string
Example: tag=some.property

The name of the Property. Each property is assigned to a specified user according to the client's logic and usage of the properties.

value
required
string
Example: value=SomeValue

The contents that describe the desired value of the associated property.

Responses

Response samples

Content type
application/json
application/json
application/xml
{
  • "tag": "some.property",
  • "value": "SomeValue"
}

Delete User Property

Delete a Property object assigned to the specified User.

DELETE /v1/account/{tenantIdfr}/{applicationIdfr}/{userIdfr}/property

Eliminate one of the properties currently assigned to the user.

Authorizations:
client-certificate (
  • account/deleteUserProperties
)
path Parameters
tenantIdfr
required
string
Example: TEST

Identifier of the Tenant. It is asigned to each client at creation time by the system. It usually consists of 3 to 8 capital letters resembling the name of the client company.

applicationIdfr
required
string
Example: WEB

Identifier of the Application. An acronim or word (without spaces) preferably in capital letters that resembles the name of the real application (or grouping). It has to be unique within the tenant. The default application is always available and can be identified with *.

userIdfr
required
string
Example: jdoe@test.com

Identifier of the User. It has to be unique within the application (or tenant). The identifier that was selected for the specified user at creation time. The client is free to use any format to identify its users.

query Parameters
tag
required
string
Example: tag=some.property

The name of the Property to eliminate.

Responses

Response samples

Content type
application/json
application/json
application/xml
{
  • "tag": "some.property",
  • "value": "SomeValue"
}

Token

A Token in the system represents a single engine capable of generating one-time passwords. Although the mobile apps available from DOUBLECheck for users have the capability of handling multiple tokens or password generators on each device, each one of these password generators correspond to a different single token in the system.

You may identify the token in the mobile app by looking into its properties and finding the identifier. It is composed by a prefix of 3 to 8 capital letters that correspond to your tenant's prefix in the system (or the Generic Tenant Identifier identified by the prefix LOCAL), and a series of 8 numeric digits that are unique to this token in the system. This Token Identifier is assigned to each token in the system by the server at creation time, and never changes for any given token. This identifier is unique and used throughout the system to reference the token.

The supported types of token in the DOUBLECheck system are: TOTP, HOTP, DEFAULT, SMS, and BYPASS.

Tokens may change their state based on the different life-cycle status that they may go through. This feature regulates what can be done with the token at the specific point in time.

HTTP End-point

https://api.double-check.es/v1/token

This end-point exposes 6 operations:

OperationDescription
Get TokenRetrieve the specified Token object from the system.
Delete TokenDelete the specified Token object from the system.
Activate TokenSet a Token to an ACTIVE state.
Inactivate TokenSet a Token to an INACTIVE state.
Cancel TokenSet a Token to an CANCELED state.
Verify PasswordVerify a proposed Password for the specified Token.

Token Life-cycle

Any given token in the system evolves through its life-cycle in a predictive way.

Figure: State-Transition Diagram for the Token Life-cycle Status.

Get Token

Retrieve the specified Token object from the system.

GET /v1/token/{tokenIdfr}

This method returns all the descriptive information about a token. You can only pull information about tokens belonging to your own tenant from the system.

Authorizations:
client-certificate (
  • token/getToken
)
path Parameters
tokenIdfr
required
string
Example: TEST95739604

Identifier of the Token. There is a unique identifier throughout the system for each token.

The identifier that was created for the specified token at creation time. It is composed of the prefix of the corresponding tenant followed by eight unique numeric digits for each token.

Responses

Response samples

Content type
application/json
application/json
application/xml
{
  • "tokenIdfr": "TEST95739604",
  • "type": "DEFAULT",
  • "status": "ACTIVE",
  • "algorithm": "HMacSHA1",
  • "numDigits": 6,
  • "period": "30s"
}

Delete Token

Delete the specified Token object from the system.

DELETE /v1/token/{tokenIdfr}

The specified token will be set to a DELETED state, considering that its current state allows deletion. The token is then scheduled for complete removal from the system. If it was already DELETED, then the method will return a 404 NOT FOUND status code.

Only tokens that are in the following states CAN be deleted:

  • CANCELED
  • EXPIRED

If the current definitions for the corresponding application allow for it, then also tokens that are in the following states COULD be deleted:

  • PROVISIONED
  • CREATED
  • ACTIVE
  • INACTIVE

Deletion of tokens MAY occur immediately in the system's database, or it may happen later, based on a purge process controlled by the system. In any case, DELETED tokens CANNOT be recovered from the system in any way once the deletion method returns.

Authorizations:
client-certificate (
  • token/deleteToken
)
path Parameters
tokenIdfr
required
string
Example: TEST95739604

Identifier of the Token. There is a unique identifier throughout the system for each token.

The identifier that was created for the specified token at creation time. It is composed of the prefix of the corresponding tenant followed by eight unique numeric digits for each token.

Responses

Response samples

Content type
application/json
application/json
application/xml
{
  • "tokenIdfr": "TEST95739604",
  • "type": "DEFAULT",
  • "status": "DELETED",
  • "algorithm": "HMacSHA1",
  • "numDigits": 6,
  • "period": "30s"
}

Activate Token

Set a Token to an ACTIVE state.

POST /v1/token/{tokenIdfr}/activate

The specified token will be set to an ACTIVE state, considering that its current state allows such activation. If it is already ACTIVE, then the method will return silently with a SUCCESS status code.

Only tokens that are in the following states CAN be activated:

  • CREATED
  • INACTIVE

Tokens that are created and their definition allows for immediate activation will be created and immediately set to an ACTIVE state. There is no need to activate tokens that have immediate activation.

Only tokens that are ACTIVE CAN be used for Password Verification.

Authorizations:
client-certificate (
  • token/activateToken
)
path Parameters
tokenIdfr
required
string
Example: TEST95739604

Identifier of the Token. There is a unique identifier throughout the system for each token.

The identifier that was created for the specified token at creation time. It is composed of the prefix of the corresponding tenant followed by eight unique numeric digits for each token.

query Parameters
password
string
Example: password=123456

Password provided by the user in order to conditionally activate the token.

If this parameter is present, then the token will only be activated if, and only if, the provided password matches a correct password for this token.

This is useful if the activation is done in a moment when the user is requesting the activation, and this allows for the client application to have control over the activated tokens.

Responses

Response samples

Content type
application/json
application/json
application/xml
{
  • "tokenIdfr": "TEST95739604",
  • "type": "DEFAULT",
  • "status": "ACTIVE",
  • "algorithm": "HMacSHA1",
  • "numDigits": 6,
  • "period": "30s"
}

Inactivate Token

Set a Token to an INACTIVE state.

POST /v1/token/{tokenIdfr}/inactivate

The specified token will be set to an INACTIVE state, considering that its current state allows such inactivation. If it is already INACTIVE, then the method will return silently with a SUCCESS status code.

Only tokens that are in the following states CAN be inactivated:

  • ACTIVE

Only tokens that are ACTIVE CAN be used for Password Verification.

Authorizations:
client-certificate (
  • token/inactivateToken
)
path Parameters
tokenIdfr
required
string
Example: TEST95739604

Identifier of the Token. There is a unique identifier throughout the system for each token.

The identifier that was created for the specified token at creation time. It is composed of the prefix of the corresponding tenant followed by eight unique numeric digits for each token.

Responses

Response samples

Content type
application/json
application/json
application/xml
{
  • "tokenIdfr": "TEST95739604",
  • "type": "DEFAULT",
  • "status": "INACTIVE",
  • "algorithm": "HMacSHA1",
  • "numDigits": 6,
  • "period": "30s"
}

Cancel Token

Set a Token to a CANCELED state.

POST /v1/token/{tokenIdfr}/cancel

The specified token will be set to a CANCELED state, considering that its current state allows such cancellation. If it is already CANCELED, then the method will return silently with a SUCCESS status code.

Only tokens that are in the following states CAN be canceled:

  • PROVISIONED
  • CREATED
  • ACTIVE
  • INACTIVE

Cancellation of tokens indicate a client's desire to remove from operation the specified token. Once a token has been canceled, it CANNOT be taken back to a useful state, and SHOULD be deleted later on. Tokens in a CANCELED state will remain in the system for a defined period of time, after which, the system itself will delete them for housekeeping reasons.

Only tokens that are ACTIVE CAN be used for Password Verification.

Authorizations:
client-certificate (
  • token/cancelToken
)
path Parameters
tokenIdfr
required
string
Example: TEST95739604

Identifier of the Token. There is a unique identifier throughout the system for each token.

The identifier that was created for the specified token at creation time. It is composed of the prefix of the corresponding tenant followed by eight unique numeric digits for each token.

Responses

Response samples

Content type
application/json
application/json
application/xml
{
  • "tokenIdfr": "TEST95739604",
  • "type": "DEFAULT",
  • "status": "CANCELED",
  • "algorithm": "HMacSHA1",
  • "numDigits": 6,
  • "period": "30s"
}

Verify Password

Verify a proposed Password for the specified Token.

POST /v1/token/{tokenIdfr}/verifyPassword

This is the most important function of the web service. The verification is done for a specific token only. This method locates the specified token and calculates the value for the current password so it can be compared with the provided value.

Since it is likely (and recommended) that you are managing your users with the Account structure, it is also likely that you don’t have the required tokenIdfr to verify the password with this function. There is an equivalent function in the Account resource which you can use instead.

Unlike the password verification operation using the account to identify the user instead of the token (account/verifyPassword), here, the token status is irrelevant, and any token in any status can be used to complete the verification. This has important security consequences, if you want to rely on the token life-cycle status for some reaason you have to make sure to be using the account operation instead. This one helps during the creation process of certain use-cases of the token.

A successful verification DOES NOT imply a correct match of the password. After receiving a successful return code from the web service, the client application MUST check the contents of the Verification Response to see the result of the verification. Possible outcomes of the verification process include, of course, a successful verification, and also, an incorrect proposed password. But other situations may arise from the execution of the method in the system. See the following table for a reference of the possible return codes.

Password Verification Return Codes

CodeResultReason
000SUCCESSVerification OK
010USED PASSWORDPassword already used
100TOKEN ERROR, GENERICGeneric token problem
101TOKEN ERROR, NOT FOUNDToken not found
102TOKEN ERROR, NOT ACTIVEToken is not active
200ACCOUNT ERROR, GENERICGeneric account problem
201ACCOUNT ERROR, NO TOKENAccount without related tokens
500FAILWrong password
900SYSTEM ERRORSystem/Service problem
Authorizations:
client-certificate (
  • token/verifyPassword
)
path Parameters
tokenIdfr
required
string
Example: TEST95739604

Identifier of the Token. There is a unique identifier throughout the system for each token.

The identifier that was created for the specified token at creation time. It is composed of the prefix of the corresponding tenant followed by eight unique numeric digits for each token.

query Parameters
password
required
string
Example: password=123456

The proposed password to be verified for the specified token.

challenge
string
Example: challenge=CAzqgAwIBAgIUXxE/lef8vyAwPJP2mJXPRJajMa0

Value of the element to be used in the hash to obtain the one-time password in a hash-based generator (HOTP).

Responses

Response samples

Content type
application/json
application/json
application/xml
Example
Success
Success
Wrong Password
Used Password
{
  • "code": "000",
  • "result": "SUCCESS",
  • "reason": "Verification OK"
}

Token Service

The token-service end-point supports some additional functions aimed to have a complete experience with the DOUBLECheck service, particularly the support needed for the mobile devices that will hold tokens and for the client's web applications.

  • A mobile app may request to synchronize a token from the device with the service. Following a specific protocol to complete this synchronization including a secure key exchange, over the public network.

  • The mobile app that implements a token to produce passwords will want to delete those tokens from the system at a later time, to leave the host clean of tokens that have been removed from the device.

  • A logo may be requested to add the image of the corresponding client's Application and be a part of the image presented in the device.

  • Obtain a QR Code with the info of a provisioned token from a client's web application for the benefit of the user, of course, without the need of authentication or certificate from the user's web browser.

These functions operate separately, as support functions in a different end-point token-service, because they may call the service without the need to authenticate, or to use a certificate.

HTTP End-point

https://api.double-check.es/v1/token-service

This end-point exposes 4 operations:

OperationDescription
Request TokenRequest the creation or synchronization of a token into the system.
Delete TokenDelete the specified Token object from the system.
Get Token LogoRetrieve the Logo image in record for the specified Token.
Get Token QR CodeObtain an image representation in QR code format of the identifying information about a token.

Request Token

Request the creation or synchronization of a token into the system.

POST /v1/token-service/request

The device that will hold a token needs to request the synchronization of the security data to correctly complete the process of a token creation.

Request Body schema:
application/json
application/json
application/xml

Token Request object with the general contents to create or synchronize a new token in the system.

tokenIdfr
string

Identifier of the Token. When the token has been previously provisioned or created, then the identifier of the token suffices to continue with the process. If tokenIdfr is provided, then the account identifiers (T/A/U) will be ignored.

tenantIdfr
string

Identifier of the Tenant. When a new token is to be added to an existing account and has not been previously created or provisioned in the system, then the identifier of the account should be provided (this is the tenant portion)

appIdfr
string

Identifier of the Application. When a new token is to be added to an existing account and has not been previously created or provisioned in the system, then the identifier of the account should be provided (this is the application portion)

userIdfr
string

Identifier of the User. When a new token is to be added to an existing account and has not been previously created or provisioned in the system, then the identifier of the account should be provided (this is the user portion)

cltKcomp
required
string

Property that holds the Client Component of the Key (public part of the Diffie-Hellman keypair).

paramSpecId
required
string

Property that identifies the Parameter Specs for the Diffie-Hellman key interchange.

Responses

Request samples

Content type
application/json
application/json
application/xml
Example
Request Created/Provisioned Token
Request Created/Provisioned Token
Request Owner Account of New Token
{
  • "tokenIdfr": "TEST05140344",
  • "cltKcomp": "F113508BF5EA9BF3B52B47B438AC5AF6A0CA0D297EA45237D9734A0F451AB9C90EB62071B14BB98BE7B41A29EAF612BEF257FE204A94425084CFD1B0554E13B3",
  • "paramSpecId": "TEST77216231"
}

Response samples

Content type
application/json
application/json
application/xml
{
  • "tokenIdfr": "TEST05140344",
  • "name": "Mobile App",
  • "type": "TOTP",
  • "algorithm": "HMacSHA1",
  • "numDigits": 8,
  • "period": "30s",
  • "srvKcomp": "9734A0F451AB9C90EB62071B14BB98BE7B41A29EAF612BEF257FE204A94425084CFD1B0554E13B3F113508BF5EA9BF3B52B47B438AC5AF6A0CA0D297EA45237D"
}

Delete Token

Delete the specified Token object from the system.

DELETE /v1/token-service/{tokenIdfr}

The specified token will be set directly to a DELETED state, regardless of its current status (since it will be most likely ACTIVE). The token is then scheduled for complete removal from the system. If it was already DELETED, then the method will return a 404 NOT FOUND status code.

When a device is about to delete a previously created token from itself, it may notify the service host to make sure that it is also removed from the host. This is useful to keep the account clean, and also to eliminate the need in the host to keep calculating passwords that will never be needed again.

A self-generated password is provided to make sure that a valid device that actually owns the token is making the request. This is intended to be used only by a current device with a token.

Deletion of tokens MAY occur immediately in the system's database, or it may happen later, based on a purge process controlled by the system. In any case, DELETED tokens CANNOT be recovered from the system in any way once the deletion method returns.

path Parameters
tokenIdfr
required
string
Example: TEST95739604

Identifier of the Token. There is a unique identifier throughout the system for each token.

The identifier that was created for the specified token at creation time. It is composed of the prefix of the corresponding tenant followed by eight unique numeric digits for each token.

query Parameters
password
required
string
Example: password=123456

A self-generated password to be verified for the specified token, to make sure that a valid device that actually owns the token is making the request.

Responses

Response samples

Content type
application/json
application/json
application/xml
{
  • "tokenIdfr": "TEST95739604",
  • "type": "DEFAULT",
  • "status": "DELETED",
  • "algorithm": "HMacSHA1",
  • "numDigits": 6,
  • "period": "30s"
}

Get Token QR Code

Obtain an image representation in QR code format of the identifying information about a token.

GET /v1/token-service/{tokenIdfr}/qrCode

To display in web sites or equivalent client applications, that allow the device to scan and easily get the identifying information about the token. Usually to be used to make the request to create the token.

An image to be used to display to the user on-screen that can be easily scanned by a device.

path Parameters
tokenIdfr
required
string
Example: TEST95739604

Identifier of the Token. There is a unique identifier throughout the system for each token.

The identifier that was created for the specified token at creation time. It is composed of the prefix of the corresponding tenant followed by eight unique numeric digits for each token.

Responses

Response samples

Content type
text/plain
Token not found: [TEST95739604]

Parameter

The parameter endpoint supports a very specific functionality needed by the mobile devices that will synchronize DOUBLECheck tokens with the system.

When a device requests a token, it has to handle a Key Exchange protocol. In this case, the DOUBLECheck system uses an Ephemeral Diffie-Hellman (EDH) Key Exchange Protocol. The system is compliant with the IETF RFC2631 - Diffie-Hellman Key Agreement Method which requires the need to use a DH Parameter Specification (parameter) during the key exchange protocol. Furthermore, in order to be ephemeral, it proposes to use different parameters as exchanges are made in time with the web service to enable Forward-secrecy (ephemeral behavior).

Through these operations, clients that intend to implement mobile device apps that handle DOUBLECheck tokens may get the required parameters to handle the key exchange protocol. The operation of getting the parameters is an off-line operation, meaning that the client should get the parameter they will need to embed in their mobile app at any moment in time prior to the development of the app, and then use the obtained information in the app during development. As the client generates newer versions of their app, they can get new parameters to embed in the app, thus enabling the previously mentioned ephemeral behavior, which is highly recommended.

The DOUBLECheck team will support its clients with all of the considerations to build the mobile device app, including libraries and source code with the key exchange functionality.

HTTP End-point

https://api.double-check.es/v1/parameter

This end-point exposes 2 operations:

OperationDescription
Create ParameterRequests the system the creation of a new `parameter` specific for a given tenant.
Get ParameterRetrieve the specified Parameter object from the system.

Create Parameter

Requests the system the creation of a new parameter specific for a given tenant.

POST /v1/parameter/{tenantIdfr}/create

The device that will hold a token needs to incorporate into the app development the inclusion of the DH Parameter Specification obtained through this operation.

Authorizations:
client-certificate (
  • parameter/createParameter
)
path Parameters
tenantIdfr
required
string
Example: TEST

Identifier of the Tenant. It is asigned to each client at creation time by the system. It usually consists of 3 to 8 capital letters resembling the name of the client company.

Responses

Response samples

Content type
application/json
application/json
application/xml
{
  • "paramIdfr": "TEST09983198",
  • "base": 2,
  • "length": 512,
  • "prime": "E7B41A29EAF612BEF257FE204A94425084CFD1B0554E13B3F113508BF5EA9BF3B52B47B438AC5AF6A0CA0D297EA45237D9734A0F451AB9C90EB62071B14BB98B"
}

Get Parameter

Retrieve the specified Parameter object from the system.

GET /v1/parameter/{tenantIdfr}/{paramIdfr}

The device that will hold a token needs to incorporate into the app development the inclusion of the DH Parameter Specification obtained through this operation.

Authorizations:
client-certificate (
  • parameter/getParameter
)
path Parameters
tenantIdfr
required
string
Example: TEST

Identifier of the Tenant. It is asigned to each client at creation time by the system. It usually consists of 3 to 8 capital letters resembling the name of the client company.

paramIdfr
required
string
Example: TEST09983198

Identifier of the Parameter. There is a unique identifier throughout the system for each parameter.

The identifier that was created for the specified tenant to be used by the development of mobile device apps that implement the token functionality. It is composed of the prefix of the corresponding tenant followed by eight unique numeric digits for each parameter.

Responses

Response samples

Content type
application/json
application/json
application/xml
{
  • "paramIdfr": "TEST09983198",
  • "base": 2,
  • "length": 512,
  • "prime": "E7B41A29EAF612BEF257FE204A94425084CFD1B0554E13B3F113508BF5EA9BF3B52B47B438AC5AF6A0CA0D297EA45237D9734A0F451AB9C90EB62071B14BB98B"
}