14.1.1.10. Token endpoints

The token API can be accessed via /token.

You need to authenticate to gain access to these token functions. If you are authenticated as administrator, you can manage all tokens. If you are authenticated as normal user, you can only manage your own tokens. Some API calls are only allowed to be accessed by administrators.

To see how to authenticate read Authentication endpoints.

POST /token/init

create a new token.

JSON Parameters:

  • otpkey – required: the secret key of the token

  • genkey – set to =1, if key should be generated. We either need otpkey or genkey

  • keysize – the size (byte) of the key. Either 20 or 32. Default is 20

  • serial – the serial number/identifier of the token

  • description – A description for the token

  • pin – the pin of the token. “OTP PIN”

  • user – the login user name. This user gets the token assigned

  • realm – the realm of the user.

  • type – the type of the token

  • tokenrealm – additional realms, the token should be put into

  • otplen – length of the OTP value

  • hashlib – used hashlib sha1, sha256 or sha512

  • validity_period_start – The beginning of the validity period

  • validity_period_end – The end of the validity period

  • 2stepinit – set to =1 in conjunction with genkey=1 if you want a 2 step initialization process. Additional policies have to be set see Two Step Enrollment.

  • otpkeyformat – used to supply the OTP key in alternate formats, currently hex or base32check (see Two Step Enrollment)

  • rollover – Set this to 1 or true to indicate, that you want to rollover a token. This is mandatory to rollover tokens, that are in the clientwait state.

  • info – string representation of a json object whose key-value pairs will be set as tokeninfo.

Return:

a json result with a boolean “result”: true

Depending on the token type there can be additional parameters. In the tokenclass you can see additional parameters in the method update when looking for getParam functions.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "detail": {
     "googleurl": {
       "description": "URL for google Authenticator",
       "img": "<img    width=250   src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAcIAAAHCAQAAAABUY/ToAAADsUlEQVR4nO2czY3bMBCF34QCfKSALcClyB2kpCAlpQOxlBQQgDwaoPBy4I+p9W4OSRaWF28OgizxgylgMJw/0oi/k/DlL0FApEiRIkWKFCnyeKRVmdrjNAFh3srTMuSS2qjLg2cr8pDkQpKMgF3SBITz1QA4YolVfQA4kiT35CNmK/JQZLM8aQaWH+3pEkEgTZlhBojksgGAAS7/83+K/ORkOF/NLtismiCfYXbOd+AxZivygCTXdCLCDJRLfTbhTo4wW5FHIJtyeAJIAJb4AobLBIP/ZQRAwMcyakxIPtd3ivw4EqObXJzody9t1EKS63N9p8iPI4sO3QTwGSSbA1Q0x+cWunWRDolsUjSnxvau6VB0xMIMrp4EPAnAkWsjpEMiu+ysD1mUZomuKk1/i6WtedIhkXupS1MEsMRmaVafh7dVfXwGV0D+kMj3yXDOsIsngXQiV59R0tZIE7jC0b4VA3WE2Yo8CtkTPy7b8sPA8HWbWML6dCKAqxG4GgADw+weOVuRRyTHuGztbk+PwdqQPIzTWibyDbJWVdOJQDLj9xkod4yOCK2gbzZvVpyip/xOkR9B4maCbnF8c53vHGuuLVaTHRLZpBgYgweAVP0hLPElA+mFtVrvf3W/aTM+brYij0j23o8JthAweNc1J5cCmSFNYDCAS5wfOVuRRyT7QpVL9F6XLN/zjhG4ZSAHj1trmcgmLcfoWoq6/B4LZLeqBxmVpxb5WobYfl8vaxfU7DSA4mdLh0S+TW5W2xXTiaWZ0WbALqiXmi5KU/n5tN8p8r+TzaqUH936MKNW6/2uIkvZIZF/IEleDfAZZnYi1zSB/DmVpa2YJZtVLxP5JmnfWCutty5qwNcFrWSsV2xGxs3+03+K/Cxk74WtTWflDr652L0XtoZuylOLvJNb9H7XPzQ0DOX9RTokcpAhAzRYpN4LO5TsI1rQLx0SOci4z7VcSuvQZgxWX1gfbfBX1ctEvhLupbZSe5bNQK0Jv/dTe9U6RL6WtoIBqDs33NA7Xdey3SYzrWUi99L8IfJW4cC4pYNjg+Ow/+O5vlPkx5OpnSsUzler2cbS29g8pmBmWH6elGMU+UqaFwS0NBBa9O45Rmhr26Mof0jkTt440MNlC9aOGQqzA8McaQs34xJfsv3rf4r8XOTduR+lezHN5fyh0sdY76qz/cDZijwwGcxqs0c9gNFx5w9t7e18hNmKPBRZ7NDtXKF6V1qp2e9qtZ7DkOf6TpEiRYoUKVKkyPfkNyq7YXtdjZCIAAAAAElFTkSuQmCC"/>",
       "value": "otpauth://hotp/mylabel?secret=GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ&counter=0"
     },
     "oathurl": {
       "description": "URL for OATH token",
       "img": "<img    width=250   src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAcIAAAHCAQAAAABUY/ToAAADfElEQVR4nO2cTYrjMBCFX40EvZRvkKPIN5gz9c3so/QBBqxlwObNQpIlp2cYaBI6zrxamDjyhywo6leyEV+T+ccXQUCkSJEiRYoUKfL5SCviy7+zmZWBAbARmwGpPjXeZU6RL0ZGkuQCAMkMCCTmqlJ8HwAb4UiSPJJfn1Pki5Fpty8AED/MEBeAU/JoA52pOuk6Rd6f9H/60xBWbwCMyG7Mg0j3mlPky5OOiB9v5AQACCQnONr4yDlFnpisdigQQAIM4WpE2oyAWy0umyfCku1QX5A81zpFPo5EHybDEXH566U+FUlyOtc6RT6OzHao2RfOgwMQVqBYJADz5WrFVN1jTpGvRRY7FLmCExwR8y3JKbAm84HkFFawieyQyCpFJRagaMniikqRK4C9KpSVa3GULxN5lGZp8n3kinrr2H5xCmsZlQ6JPEiLqbPzKh5sRefL4uJILq4MyJeJPEjzZb2jQnFopQmSH3FZw2SHRB6lC3bQeatDiI2wghOAaoykQyKb7L2OzQPpjZjNEUgDDNiMSAMAOFpchjvNKfK1yGqHlkNetofYxclVs5RzNfkykZ/J4rc+So+++S2zy1ofDVezMXmURtoZ1ynyEeRuh1xXSiwJPtCFRyUygupDIm+l5fa9Q+Na0rT8yCG3lw6JPEqtMZaCUNfmyPWhBajtMx46Iedap8jHkV2/DK0cDWBXqapczY0ptxd5kFZjLEqzlJi6C4WyHYJjHZAOieyk2aGsSNyjoF2l0Jsg9TpE/oVMHpgvK8wupRZkIwDMQy0S5QMfbVfsOdcp8v5kF1M3N9ZaGrX/sbf2g+yQyFtpPdW2/75pTtGX5tWCcnuRt9L1OtguLcFve9DazmrpkMheOn3Ju4aA4tX6gVopiurbi7yV3Lc3IJ+vh0VuHoBbAWyeSH41hF+fzzKea50iH012QdE8OPJ92MzG9HY4NJRDpqt9+9uKfEayffeDU/J7z3UzG8PVSlqfPMrlm99W5FOSsUY8Noarmdkb+T7UTSF7Wv8kbyvyqcguL+u23k/7cDvdmm9Vpxb5LzLbobErObbc/lFzijw3eZtvcR4WAtjKx2Lmn1djztBAWN5ZPX3X24p8RrI719HcWNnsEVoz1vWPyJeJ7KXYoTln7A4Wcz6/eQL7xxxyRr95IlwNskMiezF941ykSJEiRYoU+Z+TvwF49nApsKFZZAAAAABJRU5ErkJggg=="/>",
       "value": "oathtoken:///addToken?name=mylabel&lockdown=true&key=3132333435363738393031323334353637383930"
     },
     "otpkey": {
       "description": "OTP seed",
       "img": "<img    width=200   src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAUoAAAFKAQAAAABTUiuoAAAB70lEQVR4nO2aTY6jQAyFPw9IWYI0B+ijwNHhKH0DWLZU6PXCVYSOZkF6xM/CXkQkfIsnWRU/22ViZ4x/9pIQaKCBBhpooEeilqPGrAWzdjGYy8/94QICfQftJEkTAIsBlYBKkqSf6DECAn0HnfMRkj4fnjfrATOrzxEQ6I6oX74bYGJuzxIQ6H9kqySqSjCfISDQX6CNpKE8mX18lT9GpXMEBLofHc3M7WA/19B9PgQsbgnPEBDonrCXyZMB/HMaFZOnu6DWz2aMZqaBZ79Vw9gu0W/dBsU7qm4CL16aKq9geonhcq2BlqR4jirRSYImoaF8eO8c2boeXR38YnRavIwJkNFUsg1xudZAy5ywreSFyqcabgxr8lE7XECgu8JPjpj/Ao2AJtXAYoIEYzsVi3i51kBz3Rq8O658RFhKVn4Rdesu6MYTemZoEm468kh+TejlWgNdjXoeMGVjOJXXnVJk6zboa1uFb7Wm1csTZ+tu6HN3TKcEYwvZIlLJ+sMFBPoO+twdjz7GXQy8Mf6Kqe7t0HV37FaDSp630R7Rb90WtR6ytxiaFPute6Gvu2OY6wRzC92EtguUy7UGWvqtzWgX8DtPZZ8cnvAuKNs7aH4v7ZnBPH6PWcZd0DInLPHjqSTvSAGBBhpooIEG+gb6DeDWV0l+Ofz2AAAAAElFTkSuQmCC"/>",
       "value": "seed://3132333435363738393031323334353637383930"
     },
     "serial": "OATH00096020"
   },
   "id": 1,
   "jsonrpc": "2.0",
   "result": {
     "status": true,
     "value": true
   },
   "version": "eduMFA unknown"
 }

2 Step Enrollment

Some tokens might need a 2 step initialization process like a smartphone app. This way you can create a shared secret from a part generated by the eduMFA server and from a second part generated by the smartphone app/client.

The first API call would be

POST /token/init

2stepinit=1

The response would contain the otpkey generated by the server and the serial number of the token. At this point, the token is deactivated and marked as being in an enrollment state. The client would also generated a component of the key and send his component to the eduMFA server:

The second API call would be

POST /token/init

serial=<serial from the previous response>
otpkey=<key part generated by the client>

Each tokenclass can define its own way to generate the secret key by overwriting the method generate_symmetric_key. The Base Tokenclass contains an extremely simple way by concatenating the two parts. See generate_symmetric_key()

verify enrollment

Some tokens can be configured via enrollment policy so that the user needs to provide some verification that e.g. a QR code was scanned correctly or the token works correctly in general. The specific way depends on the token class. The necessary token class functions are

The first API call to /token/init returns responses in:

{"detail": {"verify": {"message": "Please provide a valid OTP value."},
            "rollout_state": "verify"}}

The second API call then needs to send the serial number and a response

POST /token/init

serial=<serial from the previous response>
verify=<e.g. the OTP value>

As long as the token is in state “verify” it can not be used for authentication.

GET /token/challenges/(serial)
GET /token/challenges/

This endpoint returns the active challenges in the database or returns the challenges for a single token by its serial number

Query Parameters:

  • serial – The optional serial number of the token for which the challenges should be returned

  • sortby – sort the output by column

  • sortdir – asc/desc

  • page – request a certain page

  • pagesize – limit the number of returned tokens

  • transaction_id – only returns challenges for this transaction_id. This is useful when working with push or tiqr tokens.

Return:

json

GET /token/

Display the list of tokens. Using different parameters you can choose, which tokens you want to get and also in which format you want to get the information (outform).

Query Parameters:

  • serial – Display the token data of this single token. You can do a not strict matching by specifying a serial like “OATH”.

  • type – Display only token of type. You ca do a non strict matching by specifying a tokentype like “otp”, to file hotp and totp tokens.

  • user – display tokens of this user

  • tokenrealm – takes a realm, only the tokens in this realm will be displayed

  • description (basestring) – Display token with this kind of description

  • sortby – sort the output by column

  • sortdir – asc/desc

  • page – request a certain page

  • assigned – Only return assigned (True) or not assigned (False) tokens

  • active – Only return active (True) or inactive (False) tokens

  • pagesize – limit the number of returned tokens

  • outform – if set to “csv”, than the token list will be given in CSV

  • rollout_state – only list tokens with the given rollout_state

  • infokey – only list tokens, where the infokey has the given infovalue

  • infovalue – only list tokens, where the infokey has the given infovalue

Return:

a json result with the data being a list of token dictionaries:

{ "data": [ { <token1> }, { <token2> } ]}
Rtype:

json

POST /token/assign

Assign a token to a user.

JSON Parameters:

  • serial – The token, which should be assigned to a user

  • user – The username of the user

  • realm – The realm of the user

Return:

In case of success it returns “value”: True.

Rtype:

json object

POST /token/unassign

Unssign a token from a user. You can either provide “serial” as an argument to unassign this very token or you can provide user and realm, to unassign all tokens of a user.

Return:

In case of success it returns the number of unassigned tokens in “value”.

Rtype:

JSON object

POST /token/revoke/(serial)
POST /token/revoke

Revoke a single token or all the tokens of a user. A revoked token will usually be locked. A locked token can not be used anymore. For certain token types additional actions might occur when revoking a token.

JSON Parameters:

  • serial (basestring) – the serial number of the single token to revoke

  • user (basestring) – The login name of the user

  • realm (basestring) – the realm name of the user

Return:

In case of success it returns the number of revoked tokens in “value”.

Rtype:

JSON object

POST /token/enable/(serial)
POST /token/enable

Enable a single token or all the tokens of a user.

JSON Parameters:

  • serial (basestring) – the serial number of the single token to enable

  • user (basestring) – The login name of the user

  • realm (basestring) – the realm name of the user

Return:

In case of success it returns the number of enabled tokens in “value”.

Rtype:

json object

POST /token/disable/(serial)
POST /token/disable

Disable a single token or all the tokens of a user either by providing the serial number of the single token or a username and realm.

Disabled tokens can not be used to authenticate but can be enabled again.

JSON Parameters:

  • serial (basestring) – the serial number of the single token to disable

  • user (basestring) – The login name of the user

  • realm (basestring) – the realm name of the user

Return:

In case of success it returns the number of disabled tokens in “value”.

Rtype:

json object

DELETE /token/(serial)

Delete a token by its serial number.

JSON Parameters:

  • serial – The serial number of a single token.

Return:

In case of success it return the number of deleted tokens in “value”

Rtype:

json object

POST /token/reset/(serial)
POST /token/reset

Reset the failcounter of a single token or of all tokens of a user.

JSON Parameters:

  • serial (basestring) – the serial number of the single token to reset

  • user (basestring) – The login name of the user

  • realm (basestring) – the realm name of the user

Return:

In case of success it returns “value”=True

Rtype:

json object

POST /token/resync/(serial)
POST /token/resync

Resync the OTP token by providing two consecutive OTP values.

JSON Parameters:

  • serial (basestring) – the serial number of the single token to reset

  • otp1 (basestring) – First OTP value

  • otp2 (basestring) – Second OTP value

Return:

In case of success it returns “value”=True

Rtype:

json object

POST /token/setpin/(serial)
POST /token/setpin

Set the the user pin or the SO PIN of the specific token. Usually these are smartcard or token specific PINs. E.g. the userpin is used with mOTP tokens to store the mOTP PIN.

The token is identified by the unique serial number.

JSON Parameters:

  • serial (basestring) – the serial number of the single token to reset

  • userpin (basestring) – The user PIN of a smartcard

  • sopin (basestring) – The SO PIN of a smartcard

  • otppin (basestring) – The OTP PIN of a token

Return:

In “value” returns the number of PINs set.

Rtype:

json object

POST /token/setrandompin/(serial)
POST /token/setrandompin

Set the OTP PIN for a specific token to a random value.

The token is identified by the unique serial number.

JSON Parameters:

  • serial (basestring) – the serial number of the single token to reset

Return:

In “value” returns the number of PINs set. The detail-section contains the key “pin” with the set PIN.

Rtype:

json object

POST /token/description/(serial)
POST /token/description

This endpoint can be used by the user or by the admin to set the description of a token.

JSON Parameters:

  • description (basestring) – The description for the token

Parameters:

  • serial

Return:

POST /token/set/(serial)
POST /token/set

This API is only to be used by the admin! This can be used to set token specific attributes like

  • description

  • count_window

  • sync_window

  • count_auth_max

  • count_auth_success_max

  • hashlib,

  • max_failcount

  • validity_period_start

  • validity_period_end

The token is identified by the unique serial number or by the token owner. In the later case all tokens of the owner will be modified.

The validity period needs to be provided in the format YYYY-MM-DDThh:mm+oooo

JSON Parameters:

  • serial (basestring) – the serial number of the single token to reset

  • user (basestring) – The username of the token owner

  • realm (basestring) – The realm name of the token owner

Return:

returns the number of attributes set in “value”

Rtype:

json object

POST /token/realm/(serial)

Set the realms of a token. The token is identified by the unique serial number

You can call the function like this:

POST /token/realm?serial=<serial>&realms=<something> POST /token/realm/<serial>?realms=<hash>

JSON Parameters:

  • serial (basestring) – the serial number of the single token to reset

  • realms (basestring) – The realms the token should be assigned to. Comma separated

Return:

returns value=True in case of success

Rtype:

bool

POST /token/load/(filename)

The call imports the given file containing token definitions. The file can be an OATH CSV file, an aladdin XML file or a Yubikey CSV file exported from the yubikey initialization tool.

The function is called as a POST request with the file upload.

JSON Parameters:

  • filename – The name of the token file, that is imported

  • type – The file type. Can be “aladdin-xml”, “oathcsv” or “yubikeycsv”.

  • tokenrealms – comma separated list of realms.

  • psk – Pre Shared Key, when importing PSKC

  • pskcValidateMAC – Determines how invalid MACs should be handled when importing PSKC. Allowed values are ‘no_check’, ‘check_fail_soft’ and ‘check_fail_hard’.

Return:

The number of the imported tokens

Rtype:

int

POST /token/copypin

Copy the token PIN from one token to the other.

JSON Parameters:

  • from (basestring) – the serial number of the token, from where you want to copy the pin.

  • to (basestring) – the serial number of the token, from where you want to copy the pin.

Return:

returns value=True in case of success

Rtype:

bool

POST /token/copyuser

Copy the token user from one token to the other.

JSON Parameters:

  • from (basestring) – the serial number of the token, from where you want to copy the pin.

  • to (basestring) – the serial number of the token, from where you want to copy the pin.

Return:

returns value=True in case of success

Rtype:

bool

POST /token/lost/(serial)

Mark the specified token as lost and create a new temporary token. This new token gets the new serial number “lost<old-serial>” and a certain validity period and the PIN of the lost token.

This method can be called by either the admin or the user on his own tokens.

You can call the function like this:

POST /token/lost/serial

JSON Parameters:

  • serial (basestring) – the serial number of the lost token.

Return:

returns value=dictionary in case of success

Rtype:

bool

GET /token/getserial/(otp)

Get the serial number for a given OTP value. If the administrator has a token, he does not know to whom it belongs, he can type in the OTP value and gets the serial number of the token, that generates this very OTP value.

Query Parameters:

  • otp – The given OTP value

  • type – Limit the search to this token type

  • unassigned – If set=1, only search in unassigned tokens

  • assigned – If set=1, only search in assigned tokens

  • count – if set=1, only return the number of tokens, that will be searched

  • serial – This can be a substring of serial numbers to search in.

  • window – The number of OTP look ahead (default=10)

Return:

The serial number of the token found

POST /token/info/(serial)/(key)

Add a specific tokeninfo entry to a token. Already existing entries with the same key are overwritten.

Parameters:

  • serial – the serial number/identifier of the token

  • key – token info key that should be set

Query Parameters:

  • value – token info value that should be set

Return:

returns value=True in case the token info could be set

Rtype:

bool

DELETE /token/info/(serial)/(key)

Delete a specific tokeninfo entry of a token.

Parameters:

  • serial – the serial number/identifier of the token

  • key – token info key that should be deleted

Return:

returns value=True in case a matching token was found, which does not necessarily mean

that the matching token had a tokeninfo value set in the first place. :rtype: bool

POST /token/info/(serial)

Modifies tokeninfo entries for a token. Already existing entries with the same key are overwritten, keys with null value are deleted

JSON Parameters:

  • info (dict) – dictionary with key value pairs. keys with null value are deleted. always make sure not to

include keys with null value by accident! :param serial: the serial number/identifier of the token :return: returns value=True in case at least one token matching the serial could be found :rtype: bool

POST /token/group/(serial)/(groupname)
POST /token/group/(serial)

Assigns a token to a given tokengroup.

If no groupname is given, we expect a body data “groups”, that contains a list of tokengroups. tokengroups that are not contained in this list, will be removed.

JSON Parameters:

  • serial (basestring) – the serial number of the token

  • groupname (basestring) – The name of the tokengroup

  • groups (list) – A list of tokengroups

Return:

Rtype:

json object

DELETE /token/group/(serial)/(groupname)

Unassigned a token from a tokengroup.

JSON Parameters:

  • serial (basestring) – the serial number of the token

  • groupname (basestring) – The name of the tokengroup

Return:

Rtype:

json object