1.About OtpOne
OtpOne is an API used to provide an easy way to protect applications and web sites using a Smartphone, a Security Key, Windows Hello or a Certificate.
You can use the APi in any programmation language which supports web request. You can use OtpOne in Zapier, Microsoft Flow, WordPress plugin and in many other applications as well.
Was this helpful?2.Get API key
To get your API key, please ask us using our contact form or drop us an email: (BETA release)
https://www.otpone.com/contact or send us an email at [email protected]
Note: You need to have OtpOne configured on your Smartphone to login and to register.
2.1.API keys description
You will obtain two main keys for each API keys you will request:
The server key begins with SRV like SRV-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx. This key is used to request elements from the server side. This key don’t have a place in JavaScript or in a client application, you have to use it only on the server side for security reason. This key will gives you all necessary accesses to the server side requests.
The client key begins with JS like JS-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx. This key is used on the client side. On a web page the key will be used in JavaScript, on a desktop client/server application scenario this key will be used in the client application as well. This key will give you all necessary accesses to client requests.
2.2.Swagger help and testing tool
To simplify the implementation, we have documented our APi using Swagger description and testing tool.
You can get the swagger GUI for help and testing here:
https://api.otpone.com/swagger/ui/index
The Swagger JSON API description is here:
3.Request types
To use a Smartphone, a Security Key, Windows Hello, or a Certificate to validate a user request (Authentication, Workflow, Signature, etc…) you have to follow a simple process. The same simple process is used if you want to use the mobile picture and document scan or the mobile signature function.
You have three types of requests possible:
- Standard request type: The client sends the customer request, the server checks the answer after the customer validation.
- Ditributed request type: The server sends the customer request, the client gets the answer after the customer validation.
- Server only request type: The server sends the customer request and checks the answer after the customer validation.
3.1.Standard request description
In a standrard request like a login, a workflow validation or a user signature on a web page, the server requests a Transaction ID, and give it to the client. Then the client sends a validation request to the customer. The customer validate his identity in the client page. The client page receive a token. The token is send back to the server for validation.
Server side: Your web server. (Or your application server)
Client side: Your web page. (Or your client application)
Customer side: The Smartphone, Security Key or Certificate owned by the customer, who will confirm his identity.
The process :
- Get a Transaction ID. (Server side)
- Load the necessary HTML and JavaScript in your web page. (Client side)
- Customer confirm his Identity. (Customer side)
- Verify the received token. (Server side)
Note: In a desktop application you won’t download any HTML or JavaScript but use a component.
otpone api passwordless
3.1.1.Standard request implementation
1. Get a Transaction ID (Server side)
Create a getTransactionID request on the server. (GET or POST):
getTransactionID description and test
| Name | Description | Type | Additional information |
|---|---|---|---|
| SrvAPIKey | SRV-xxxxxx-xxxx-xxxx-xxxxxx | string | Required |
| UserMail | [email protected] | string | Required |
| requestype | Type of authentication | RequestTypes | Required |
| Message | Message to show on mobile | string | Required |
| privateToken | Not used | string | Required |
privateToken: is not used in this type of request.
You can define different type of request:
| Name | Value | Description |
|---|---|---|
| RequestWebSession | 0 | Authentication web |
| RequestComputerSession | 1 | Authentication to open a session |
| RequestFileScanImage | 2 | Request a mobile picture |
| RequestFileScanDocument | 3 | Request a document scan |
| RequestWorkFlowValidation | 4 | Request a Workflow validation |
| RequestApplicaitonAccess | 5 | Request an application validation |
| RequestSignDocument | 6 | Request a mobile signature |
2. Load the necessary HTML and JavaScript in your web page. (Client side)
The client web page needs some JavaScript, HTML and CSS to correctly send or valid the user identity. To simplify your code, you can use a function on the server side and write the result on your client web page.
Use GetHTML function to get the HTML, JavaScript and CSS needed.
GetHTML request description and test
| Name | Description | Type | Additional information |
|---|---|---|---|
| SrvAPIKey | SRV-xxxxxx-xxxx-xxxx-xxxxxx | string | Required |
| transactionid | Transaction id coming from gettransactionID | string | Required |
| pageType | Define request type script to load | PageType | Required |
| FormID | Form id to execute after the user validation | string | Required |
FormID : Enter you ID form you have defined in your website, the setting in used to send the token back after the user has valided the request.
Pagetype: Is used to define the type of validation or digitalization you want: Smartphone, Security Key, Certificate, etc…
| Name | Value | Description |
|---|---|---|
| RTRPhoneValidation |
0 |
Phone validation and digitalization functions |
| SecurityKeyValidation |
1 |
Secure key validation and Windows Hello |
| SecurityKeyRegistration |
2 |
Secure key registration on your domain |
| Certificate |
3 |
User entreprise certificate validation |
3. Customer confirm his identity. (Customer side)
The Customer (End user) has to confim his identity using the validation type used in the PageType.
4. Verify the received token. (Server side)
After the user has finished his action you will obtain a token if the user has valided the request. You HAVE to verify this token in order to close the request process.
VerifyToken description and test
The result has a lot of information depending on the type of the request you made.
Some important part in the function result :
| Name | Description | Type | Additional information |
|---|---|---|---|
| Message | Error message in case of | string | None. |
| UserValided | [email protected], must be the same as the initial request | string | None. |
| privateToken | Get the private token on the client | string | None. |
| isValid | MUST be true | boolean | None. |
Note: If the user doesn’t accept the request the request will be not redirected to your server.
3.2.Distributed request description
Distributed requests provides you a way to implement a Client/Server scenario. The client asks for a validation or a digitalization function on your server. Your server sends a request to the Customer. The Transaction ID is given back to the client. The client will receive the result when the user has complete the transaction.
Server side: Your web server or your application server.
Client side: Your client application.
Customer side: The Smartphone, Security Key or Certificate owned by the customer, who will confirm his Identity.
The process :
- Get a Transaction ID. (Server side)
- Verify if the transaction is complete using Transaction ID. (Client side)
- The Customer confirm his identity. (Customer side)
- Receive the result. (Client side)
Note: This type of request can be used to cover none Web-Client – Server scenario.
3.2.1.Ditributed request implementation
Create a getTransactionID request on the server. (GET or POST):
getTransactionID description and test
| Name | Description | Type | Additional information |
|---|---|---|---|
| SrvAPIKey | SRV-xxxxxx-xxxx-xxxx-xxxxxx | string | Required |
| UserMail | [email protected] | string | Required |
| requestype | Type of authentication | RequestTypes | Required |
| Message | Message to show on mobile | string | Required |
| privateToken | Save a private token to send it to the distributed client | string | Required |
privateToken: is used to send an private information like a key, a password, a unique information, etc, from the server to the client after a user validation. If the user doesn’t accept the request the client will not receive the private token.
You can define different type of requests:
| Name | Value | Description |
|---|---|---|
| RequestWebSession | 0 | Authentication web |
| RequestComputerSession | 1 | Authentication to open a session |
| RequestFileScanImage | 2 | Request a mobile picture |
| RequestFileScanDocument | 3 | Request a document scan |
| RequestWorkFlowValidation | 4 | Request a Workflow validation |
| RequestApplicaitonAccess | 5 | Request an application validation |
| RequestSignDocument | 6 | Request a mobile signature |
2. Client get and use transactionID. (Client side)
On the client, side use isFinish as client web request with a timer to check regulary if the Customer (End user) has valided the request.
IsFinish client request description and test
When the result is true, customer has completed the request, use GetResult function to get the user action result.
GetResult client request description and test
Both functions need a transactionID and a JS API Key. (JS-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx)
3. Customer confirm his Identity. (Customer side)
The Customer (End user) have to confim his identity using the validation type used in the PageType.
4. Receive the result. (Client side)
The result has a lot of information depending of the type for request you have made.
Some important part in the function result :
| Name | Description | Type | Additional information |
|---|---|---|---|
| Message | Message in case of error | string | None. |
| UserValided | [email protected], must be the same as the initial request | string | None. |
| privateToken | Get the private token on the client | string | None. |
| isValid | Must be true | boolean | None. |
3.3. Server only request description
In some cases you may want to request a phone validation directly from the server side without client interaction. This kind of request can be used when the cient is not compatible with JavaScript or not compatible with a client component. For example, a server only request is used for Zapier and Microsoft flow integration.
Server side: Your web server or your application server.
Client side: – not client side.
Customer side: The mobile phone validation who will confirm his Identity. (Currently, only the phone validation is supported in a server only request).
The process :
- Request a serverOnlyRequest. (Server side)
- Customer confirm his Identity. (Customer side)
Note: This type of request is limited but in some case very helpfull.
3.3.1.Server only implementation
1. Get a Transaction ID. (Server side)
Create a SendRequest request on the server (GET or POST):
SendRequest description and test
| Name | Description | Type | Additional information |
|---|---|---|---|
| SrvAPIKey | SRV-xxxxxx-xxxx-xxxx-xxxxxx | string | Required |
| UserMail | [email protected] | string | Required |
| requestype | Type of authentication | RequestType | Required |
| Message | Message to show on mobile | string | Required |
| userIP | IP of the requester. You can use Header information: HTTP_X_FORWARDED_FOR or REMOTE_ADDR | string | Required |
| OSType | You can use Plateform.JS to get more information | string | Required |
| NavigatorOrAPPName | Define your appname | string | Required |
You can define different type of request:
| Name | Value | Description |
|---|---|---|
| RequestWebSession | 0 | Authentication web |
| RequestComputerSession | 1 | Authentication to open a session |
| RequestFileScanImage | 2 | Request a mobile picture |
| RequestFileScanDocument | 3 | Request a document scan |
| RequestWorkFlowValidation | 4 | Request a Workflow validation |
| RequestApplicaitonAccess | 5 | Request an application validation |
| RequestSignDocument | 6 | Request a mobile signature |
2. Customer confirm his Identity. (Customer side)
The Customer (End user) have to confim his validation using the validation type used in the PageType.
3. The result must be controled.
The result has a lot of information depending of the type for request you have made.
Some important part in the function result :
| Name | Description | Type | Additional information |
|---|---|---|---|
| Message | Error message in case of | string | None. |
| UserValided | [email protected], MUST be the same as the initial request | string | None. |
| privateToken | Get the private token on the client | string | None. |
| isValid | MUST be true | boolean | None. |
Note: This type of request can timeout if the customer (End user) doesn’t respond fast enougth. (2 min).
