Mi-Token API

Interface Specification

Mi-Token version 4.3.8. Document version 3, January 2016.

© 2016 Mi-Token Inc. All rights reserved.
2 Mi-Token API Interface Specification © 2016
Mi-Token API Interface Specification.

© 2016 Mi-Token Inc.

All rights reserved. No parts of this work may be reproduced in any form or by any
means – graphic, electronic, or mechanical, including photocopying, recording, taping, or
information storage and retrieval systems – without the written permission of the publisher.
Products that are referred to in this document may be either trademarks and/or registered
trademarks of the respective owners. The publisher and the author make no claim to these
trademarks.
While every precaution has been taken in the preparation of this document, the publisher
and the author assume no responsibility for errors or omissions, or for damages resulting
from the use of information contained in this document or from the use of programs and
source code that may accompany it. In no event shall the publisher and the author be liable
for any loss of profit or any other commercial damage caused or alleged to have been
caused directly or indirectly by this document.
Mi-Token version 4.3.8. Document version 3, January 2016.
Published: January 2016 in Austin, Texas, United States of America.

© 2016 Mi-Token API Interface Specification 3

Table of contents

Mi-Token API Interface Specification. ..................................................................................................... 3

Table of contents .................................................................................................................................... 4
1. Introduction....................................................................................................................................... 5
1.1 API Service overview ..................................................................................................................... 5
1.2 API Service deployment ................................................................................................................ 5
1.3 API Service security ....................................................................................................................... 5
1.4 API Service work modes ................................................................................................................ 6
2. API Calls ............................................................................................................................................. 7
2.1 GetChallenge ................................................................................................................................. 7
2.2 NewSession ................................................................................................................................... 7
2.3 VerifyOtp ....................................................................................................................................... 8
2.4 AssignToken .................................................................................................................................. 9
2.5 UnassignToken ............................................................................................................................ 10
2.6 EnableToken ................................................................................................................................ 11
2.7 DisableToken ............................................................................................................................... 11
2.8 CreateSoftToken.......................................................................................................................... 12
2.9 DeleteToken ................................................................................................................................ 13
2.10 ListUserTokens .......................................................................................................................... 14
2.11 ListUnassignedHardtokens ........................................................................................................ 15
2.12 DeleteUnassignedSoftTokens ................................................................................................... 16
2.13 DeleteUser................................................................................................................................. 17

4 Mi-Token API Interface Specification © 2016

1. Introduction

1.1 API Service overview

The API Service makes Mi-Token administration and authentication related functionality
available via a set of API calls. It is written in .NET, makes use of WCF and is configured to
use WebHttpBinding supporting UTF-8 encoded requests. The requests are sent over HTTPS
using the GET and POST methods. The responses are formatted using JSON with non-
significant whitespace subject to change.

1.2 API Service deployment

The API Service is installed on a central server. Windows 2012 R2 (any edition) is
recommended. The API Service can be installed on more than one server for scalability and
fault tolerance.
Mi-Token has 2 decision-making components: Radius Plugin and API Service. Installers for
these components create a local instance of AD LDS database where all Mi-Token data is
stored. The first server in a domain where a decision-making component is installed
becomes the primary Mi-Token server.
During all subsequent installations of decision-making components on other machines the
installer needs to be configured to create a replica of the existing Mi-Token instance. This is
achieved by pointing the installer to the primary Mi-Token server. After the installer
finishes, the newly created instance of AD LDS database starts bi-directionally replicating
with the primary database instance (and all the replica database instances if any), there are
no additional tweaks required for the replication to become operational. The API Service
itself also becomes ready to take the workload immediately after the installation, there are
no post-install configuration adjustments required for it to start functioning.
The AD LDS replication makes for High Availability provided multiple API clients are
configured to use different instances of the API Service. It is desirable for the API client to be
able to automatically switch to another instance of the API Service should the currently used
instance becomes unavailable.

1.3 API Service security

The API Service is configured to use WCF Transport security e.g. HTTPS. The certificates are
not checked, rather a custom security solution is employed which restricts access to the API
Service so that only API clients configured to use the API keys are able to call it. The keys are
generated using Mi-Token management interface (called AD UI), stored in the AD LDS

© 2016 Mi-Token API Interface Specification 5

database and read by the API Service. Each API client must have access to a key as well (as a
part of its configuration data).
At run time API client calls GetChallenge API to get a challenge (random data) from the API
Service. Then the client hashes the challenge using HMAC-SHA1 algorithm and the API key.
Subsequently to that the client calls NewSession API, presents the calculated hash and gets
back a session ID which must be supplied as a part of any other API call.
The session ID is valid for 15 minutes. When it expires the API Service returns HTTP status
code 403 ‘Forbidden’ with the body of the response set to:
{ “result” : “unauthorized”, “details” : “session is invalid” }

In this case the client should get another challenge and use it to obtain new session (as
described above), then retry the API call which failed. This should be performed by the low
level API client code so that the component using the API client is shielded from the security
related activities.
The requirement to have sessions can be turned off using a Registry setting. This is not
recommended unless there is an alternative security arrangement, for instance a firewall on
the API Service server restricting callers to a whitelisted set of API clients with firewalls on
the API client machines optionally further restricting the ability to make outbound calls to a
known process hosting the API client.

1.4 API Service work modes

The API Service supports two modes of operation: AD Mode and Raw Mode. In AD Mode
the username argument passed to some APIs refers to an Active Directory username. The
Raw Mode operates with arbitrary usernames having no references to the Active Directory.
This version of the document covers the Raw Mode only.

6 Mi-Token API Interface Specification © 2016

2. API Calls

2.1 GetChallenge
The API returns a random challenge. The challenge should be hashed and the hash value
used to call the NewSession API. See section 1.3 for further information.

Request URL:
https://<address>/mi-token/api/authentication/v4/RawHttpWithSSL/getchallenge
Request Method: GET
Request version: HTTP/1.1
Response content type: text/plain
Response content: { 'result' : <result>, 'details' : <challenge> }
<result> : 'success'
<challenge> : 32-byte random challenge encoded as Base64 string.

Sample Output:
{ "result" : "success",
"details" : "LloSgmkp1KDbllkgeWGwZXLDSTuarafaEV1wf2o/0AY=" }

2.2 NewSession
The API is used to present the calculated hash of the challenge returned by the
GetChallenge API and obtain a session ID.

Request URL:
https://<address>/mi-token/api/authentication/v4/RawHttpWithSSL/newsession
Request Method: POST
Request version: HTTP/1.1
Request content type: application/x-www-form-urlencoded
Posted form variable:
response: <hash>
Response content type: text/plain
Response content: { 'result' : <result>, 'details' : <details> }
<result> : 'success' | 'error'

© 2016 Mi-Token API Interface Specification 7

 <details> : the session ID encoded as string in case of 'success' or an
error in case of 'error'.

Sample C# code to calculate a hash:

private static string CalculateHash(string challenge, byte[] key)

{
byte[] binaryChallenge = System.Convert.FromBase64String(challenge);
HMACSHA1 hmac = new HMACSHA1(key);
byte[] hash = hmac.ComputeHash(binaryChallenge);
string response = System.Convert.ToBase64String(hash);

return response;
}

Sample Outputs:
{ "result" : "success",
"details" : "HABajHr82T0W8g4hjwQ7VR/mRxy7wsTISncs6G7eD9M=" }

{ “result” : “error”, “details” : “unknown” }

Note: The session ID returned by this API is valid for 15 minutes and should be supplied as
the ‘session’ variable while making all the API calls mentioned later in this document. This
requirement is mentioned in the specification of each subsequent API. When the session ID
expires, all the subsequent APIs return HTTP status code 403 (see section 1.3) and this is not
mentioned in the API specifications.

2.3 VerifyOtp
The API is used to verify one time password (OTP) for a given username. All the hard-tokens
and soft-tokens assigned to the user will be tried in an attempt to find a match. If the OTP
matches then the token-id of the token which produced the matching OTP is returned. If the
OTP doesn’t match the user is rejected with 'result' set to 'failure'.

Request URL: https://<address>/mi-token/api/authentication/v4/RawHttpWithSSL/verify

Request Method: POST
Request version: HTTP/1.1
Request content type: application/x-www-form-urlencoded
Posted form variables:
username: <username>
password: <otp>
validate: “otp”
usertype: “raw”
session: <session ID>

8 Mi-Token API Interface Specification © 2016

Response content type: text/plain
Response content: { 'result' : <result>, 'details' : <details> }

<result> : 'success' | 'failure' | 'unauthorized' | 'error' | 'exception'

'success' : OTP verified successfully

'failure' : API call has been executed, the outcome was a failure
'unauthorized' : invalid session
'error' : API call has not been executed
'exception' : should not occur, contact Mi-Token Support if it does

<details> : an explanatory message useful for logging/troubleshooting

Sample Outputs:
{ "result" : "success", "details": {"token":"ccccbgbujild"} }

{ "result" : "failure", "details" : "no OTP match" }

{ "result" : "failure",
"details" : "user has no tokens assigned (UserID Mode)" }

{ "result" : "failure", "details" : "user locked out" }

{ "result" : "error", "details" : "username argument is required" }

2.4 AssignToken
Assign hard-token token-id to user user-name.

Request URL: https://<address>/mi-token/api/authentication/v4/RawHttpWithSSL/assign

Request Method: POST
Request version: HTTP/1.1
Request content type: application/x-www-form-urlencoded
Posted form variables:
username: <username>
token: <token-id>
usertype: “raw”
session: <session ID>
Response content type: text/plain
Response content: { 'result' : <result>, 'details' : <details> }
<result> : 'success' | 'failure' | 'unauthorized' | 'error' | 'exception'

'success' : token assigned (or re-assigned) successfully

© 2016 Mi-Token API Interface Specification 9

 'failure' : API call has been executed, the outcome was a failure
'unauthorized' : invalid session
'error' : API call has not been executed
'exception' : should not occur, contact Mi-Token Support if it does

<details> : an explanatory message useful for logging/troubleshooting

Sample Outputs:
{ "result" : "success", "details" : "1 token assigned" }

{ "result" : "failure", "details" : "no tokens found" }

{ "result" : "error",
"details" : "Both the username and token variables are required." }

2.5 UnassignToken
Unassign token token-id.

Request URL:
https://<address>/mi-token/api/authentication/v4/RawHttpWithSSL/unassign
Request Method: POST
Request version: HTTP/1.1
Request content type: application/x-www-form-urlencoded
Posted form variables:
token: <token-id>
session: <session ID>
Response content type: text/plain
Response content: { 'result' : <result>, 'details' : <details> }
<result> : 'success' | 'failure' | 'unauthorized' | 'error' | 'exception'

'success' : token unassigned successfully

'failure' : API call has been executed, the outcome was a failure
'unauthorized' : invalid session
'error' : API call has not been executed
'exception' : should not occur, contact Mi-Token Support if it does

<details> : an explanatory message useful for logging/troubleshooting

Sample Outputs:
{ "result" : "success", "details" : "1 token unassigned" }

10 Mi-Token API Interface Specification © 2016

 { "result" : "failure", "details" : "no tokens found" }

{ "result" : "error", "details" : "The token variable is required." }

2.6 EnableToken
Enable token token-id.

Request URL: https://<address>/mi-token/api/authentication/v4/RawHttpWithSSL/enable

Request Method: POST
Request version: HTTP/1.1
Request content type: application/x-www-form-urlencoded
Posted form variables:
token: <token-id>
session: <session ID>
Response content type: text/plain
Response content: { 'result' : <result>, 'details' : <details> }
<result> : 'success' | 'failure' | 'unauthorized' | 'error' | 'exception'

'success' : token enabled successfully

'failure' : API call has been executed, the outcome was a failure
'unauthorized' : invalid session
'error' : API call has not been executed
'exception' : should not occur, contact Mi-Token Support if it does

<details> : an explanatory message useful for logging/troubleshooting

Sample Outputs:
{ "result" : "success", "details" : "1 token enabled" }

{ "result" : "success", "details" : "token re-enabled" }

{ "result" : "failure", "details" : "no tokens found" }

{ "result" : "error", "details" : "The token variable is required." }

2.7 DisableToken
Disable token token-id.

Request URL: https://<address>/mi-token/api/authentication/v4/RawHttpWithSSL/disable

© 2016 Mi-Token API Interface Specification 11

Request Method: POST
Request version: HTTP/1.1
Request content type: application/x-www-form-urlencoded
Posted form variables:
token: <token-id>
session: <session ID>
Response content type: text/plain
Response content: { 'result' : <result>, 'details' : <details> }

<result> : 'success' | 'failure' | 'unauthorized' | 'error' | 'exception'

'success' : token disabled successfully

'failure' : API call has been executed, the outcome was a failure
'unauthorized' : invalid session
'error' : API call has not been executed
'exception' : should not occur, contact Mi-Token Support if it does

<details> : an explanatory message useful for logging/troubleshooting

Sample Outputs:
{ "result" : "success", "details" : "1 token disabled" }

{ "result" : "failure", "details" : "no tokens found" }

{ "result" : "error", "details" : "The token variable is required." }

2.8 CreateSoftToken
Create a soft-token for user user-name and return the token activation URL.

Request URL:
https://<address>/mi-token/api/authentication/v4/RawHttpWithSSL/createsofttoken

Request Method: POST

Request version: HTTP/1.1
Request content type: application/x-www-form-urlencoded
Posted form variables:
version: 'v4' | 'v5'
code: loading code for 'v5' displayed on user’s device
session: <session ID>
Response content type: text/plain

12 Mi-Token API Interface Specification © 2016

Response content: { 'result' : <result>, 'details' : <details> }
<result> : 'success' | 'failure' | 'unauthorized' | 'error' | 'exception'

'success' : token created successfully

'failure' : API call has been executed, the outcome was a failure
'unauthorized' : invalid session
'error' : API call has not been executed
'exception' : should not occur, contact Mi-Token Support if it does

<details> : {'tokenSerial' : <serial>, 'tokenLink' : <link>} | <message>

<message> : an explanatory message useful for logging/troubleshooting
<serial> : token-id of the created token
<link> : token activation link (URL) to be tapped on user’s device

Sample Outputs:
{ "result" : "success",
"details" : {"tokenSerial" : "0a380965-eb70-471c-8c6d-c9bc41d36920",
"tokenLink" : "https://mobile.mi-token.com/4/i/demo/WI20JP
JfpbquvOmKDIqWwXmGgUNakf2C8PVSfgYWzbm19Nk5F4vZzjxVbcviA9W3"} }

{ "result" : "error", "details" : "version not specified" }

{ "result" : "error", "details" : "Invalid version. Only 4 and 5 are valid." }

{ "result" : "error",
"details" : "loadingCode is not specified, or is of the wrong length." }

{ "result" : "error", "details" : "could not create soft-token" }

2.9 DeleteToken
Delete token token-id.

Request URL:
https://<address>/mi-token/api/authentication/v4/RawHttpWithSSL/delete
Request Method: POST
Request version: HTTP/1.1
Request content type: application/x-www-form-urlencoded
Posted form variables:
token: <token-id>
session: <session ID>
Response content type: text/plain
Response content: { 'result' : <result>, 'details' : <details> }

© 2016 Mi-Token API Interface Specification 13

<result> : 'success' | 'failure' | 'unauthorized' | 'error' | 'exception'

'success' : token deleted successfully

'failure' : API call has been executed, the outcome was a failure
'unauthorized' : invalid session
'error' : API call has not been executed
'exception' : should not occur, contact Mi-Token Support if it does

<details> : an explanatory message useful for logging/troubleshooting

Sample Outputs:
{ "result" : "success", "details" : "1 token deleted" }

{ "result" : "failure", "details" : "no tokens found" }

{ "result" : "error",
"details" : "The token variable is required." }

2.10 ListUserTokens
List all soft-tokens and hard-tokens assigned to a user user-name.

Request URL: https://<address>/mi-token/api/authentication/v4/RawHttpWithSSL/list

Request Method: POST
Request version: HTTP/1.1
Request content type: application/x-www-form-urlencoded
Posted form variables:
username: <username>
usertype: “raw”
format: “nameserial”
session: <session ID>
Response content type: text/plain
Response content: { 'result' : <result>, 'details' : <details> }

<result> : 'success' | 'unauthorized' | 'error' | 'exception'

'success' : token(s) listed successfully

'failure' : API call has been executed, the outcome was a failure
'unauthorized' : invalid session
'error' : API call has not been executed
'exception' : should not occur, contact Mi-Token Support if it does

<details> : { [<tokenData>, ...] } | <message>

14 Mi-Token API Interface Specification © 2016

 <message> : an explanatory message useful for logging/troubleshooting
<tokenData> : { 'tokenName' : <name>, 'tokenSerial' : <serial> }
<serial> : token-id
<name> : token name visible in AD UI and printed on the token

Sample Outputs:
{ "result" : "success", "details" : [], "count" : 0 }

{ "result" : "success",
"details" : [{"tokenName":"HOTP YubiKey 285640", "tokenSerial":"285640"},
{"tokenName":"YubiKey 285457", "tokenSerial":" ccccbgbujild"},
{"tokenName":"Token MT0100011026", "tokenSerial":MT0100011026"},
{"tokenName":"Mobile Soft Token d3e725a5-8898-4ec2-87e0-
b6153ea65692","tokenSerial":"d3e725a5-8898-4ec2-87e0-
b6153ea65692"}],
"count" : 4 }

{ "result" : "error", "details" : "username argument is required" }

{ "result" : "error", "details" : "unsupported listing format" }

2.11 ListUnassignedHardtokens
List all unassigned hard-tokens imported into the system.

Request URL:
https://<address>/mi-token/api/authentication/v4/RawHttpWithSSL/listunassigned
Request Method: POST
Request version: HTTP/1.1
Request content type: application/x-www-form-urlencoded
Posted form variables:
format: “nameserial”
session: <session ID>
Response content type: text/plain
Response content: { 'result' : <result>, 'details' : <details> }
<result> : 'success' | 'unauthorized' | 'error' | 'exception'

'success' : token(s) listed successfully

'failure' : API call has been executed, the outcome was a failure
'unauthorized' : invalid session
'error' : API call has not been executed
'exception' : should not occur, contact Mi-Token Support if it does

© 2016 Mi-Token API Interface Specification 15

<details> : { [<tokenData>, ...] } | <message>

<message> : an explanatory message useful for logging/troubleshooting

<tokenData> : { 'tokenName' : <name>, 'tokenSerial' : <serial> }
<serial> : token-id
<name> : token name visible in AD UI and printed on the token

Sample Outputs:
{ "result" : "success", "details" : [], "count" : 0 }

{ "result" : "success",
"details" : [{"tokenName":"HOTP YubiKey 285640", "tokenSerial":"285640"},
{"tokenName":"YubiKey 285457", "tokenSerial":" ccccbgbujild"},
{"tokenName":"Token MT0100011026", "tokenSerial":MT0100011026"}],
"count" : 3 }

{ "result" : "error", "details" : "unsupported listing format" }

2.12 DeleteUnassignedSoftTokens
Delete all unassigned soft-tokens.

Request URL:
https://<address>/mi-token/api/authentication/v4/RawHttpWithSSL/deleteunassigned
Request Method: POST
Request version: HTTP/1.1
Request content type: application/x-www-form-urlencoded
Posted form variables:
session: <session ID>
Response content type: text/plain
Response content: { 'result' : <result>, 'details' : <details> }
<result> : 'success' | 'unauthorized' | 'exception'

'success' : token(s) deleted successfully

'failure' : API call has been executed, the outcome was a failure
'unauthorized' : invalid session
'error' : API call has not been executed
'exception' : should not occur, contact Mi-Token Support if it does

<details> : <message>

<message> : an explanatory message useful for logging/troubleshooting

16 Mi-Token API Interface Specification © 2016

Sample Outputs:
{ "result" : "success", "details" : "unassigned soft-tokens deleted" }

2.13 DeleteUser
Delete all soft-tokens and unassign all hard-tokens assigned to user user-name.

Request URL:
https://<address>/mi-token/api/authentication/v4/RawHttpWithSSL/deleteuser
Request Method: POST
Request version: HTTP/1.1
Request content type: application/x-www-form-urlencoded
Posted form variables:
username: <username>
usertype: “raw”
session: <session ID>
Response content type: text/plain
Response content: { 'result' : <result>, 'details' : <details> }

<result> : 'success' | 'unauthorized' | 'error' | 'exception'

'success' : token(s) listed successfully

'failure' : API call has been executed, the outcome was a failure
'unauthorized' : invalid session
'error' : API call has not been executed
'exception' : should not occur, contact Mi-Token Support if it does

<details> : <message>

<message> : an explanatory message useful for logging/troubleshooting

Sample Outputs:
{ "result" : "success", "details" : "user tokens processed" }

{ "result" : "error", "details" : "unsupported user type" }

© 2016 Mi-Token API Interface Specification 17