13.1.1.8. 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 adminitrators.

To see how to authenticate read Authentication endpoints.

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 “value”: True.
Rtype:	json object

POST /token/copyuser¶

Copy the token user from one token to the other.

You can call the function like this:: POST /token/copyuser?from=<serial>&to=<something>

Parameters:	from – the serial number of the single, from where you want to

copy the pin. :type from: basestring :param to: the serial number of the single, from where you want to copy the pin. :type to: basestring :return: returns value=True in case of success :rtype: bool

POST /token/disable¶

Disable a single token or all the tokens of a user. Disabled tokens can not be used to authenticate but can be enabled again.

You can call the function like this:: POST /token/disable?serial=<serial> POST /token/disable?user=<user>&realm=<realm> POST /token/disable/<serial>

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

POST /token/copypin¶

Copy the token PIN from one token to the other.

You can call the function like this:: POST /token/copypin?from=<serial>&to=<something>

Parameters:	from – the serial number of the single, from where you want to

copy the pin. :type from: basestring :param to: the serial number of the single, from where you want to copy the pin. :type to: basestring :return: returns value=True in case of success :rtype: bool

POST /token/assign¶

Assign a token to a user. The required arguments are serial, user and realm.

Return:	In case of success it returns “value”: True.
Rtype:	json object

POST /token/enable¶

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

You can call the function like this:: POST /token/enable?serial=<serial> POST /token/enable?user=<user>&realm=<realm> POST /token/enable/<serial>

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/resync¶

Resync the OTP token by providing two consecutive OTP values.

You can call the function like this:: POST /token/resync?serial=<serial>&otp1=<otp1>&otp2=<otp2> POST /token/resync/<serial>?otp1=<otp1>&otp2=<otp2>

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¶

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.

You can call the function like this:: POST /token/setpin?serial=<serial>&userpin=<userpin>&sopin=<sopin> POST /token/setpin/<serial>?userpin=<userpin>&sopin=<sopin>

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/reset¶

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

You can call the function like this:: POST /token/reset?serial=<serial> POST /token/reset?user=<user>&realm=<realm> POST /token/reset/<serial>

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/init¶

create a new token.

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 – required: the serial number/identifier of the token
description – A description for the token
pin – the pin of the user pass
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 oder sha256

ocra arguments: for generating OCRA Tokens type=ocra you can specify the following parameters: :param ocrasuite: if you do not want to use the default

ocra suite OCRA-1:HOTP-SHA256-8:QA64

Parameters:	sharedsecret – if you are in Step0 of enrolling an OCRA/QR token the sharedsecret=1 specifies, that you want to generate a shared secret activationcode – if you are in Step1 of enrolling an OCRA token you need to pass the activation code, that was generated in the QRTAN-App
Return:	a json result with a boolean “result”: true

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": "privacyIDEA unknown"
 }

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

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.

You can call the function like this:: POST /token/set?serial=<serial>&description=<something> POST /token/set/<serial>?hashlib=<hash> POST /token/set?user=<username>&realm=<realm>&sync_window=100

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

GET /token/¶

The method is called at /token Display the list of available tokens.

Parameters:	serial – Display the token data of this single token. You can do a

not strict matching by specifying a serial like “OATH”. :param 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. :param user: display tokens of this user :param viewrealm: takes a realm, only the tokens in this realm will be displayed :param description: Display token with this kind of description :type description: basestring :param sortby: sort the output by column :param sortdir: asc/desc :param page: request a certain page :param assigned: Only return assigned (True) or not assigned (False) tokens :param pagesize: limit the number of returned tokens :param user_fields: additional user fields from the userid resolver of the owner (user) :param outform: if set to “csv”, than the token list will be given in CSV

Return:	a json result with the data being a list of token dictionaries { “data”: [ { <token1> }, { <token2> }. ] }
Rtype:	json

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.

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 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/disable/(serial)¶

Disable a single token or all the tokens of a user. Disabled tokens can not be used to authenticate but can be enabled again.

You can call the function like this:: POST /token/disable?serial=<serial> POST /token/disable?user=<user>&realm=<realm> POST /token/disable/<serial>

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

POST /token/enable/(serial)¶

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

You can call the function like this:: POST /token/enable?serial=<serial> POST /token/enable?user=<user>&realm=<realm> POST /token/enable/<serial>

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/resync/(serial)¶

Resync the OTP token by providing two consecutive OTP values.

You can call the function like this:: POST /token/resync?serial=<serial>&otp1=<otp1>&otp2=<otp2> POST /token/resync/<serial>?otp1=<otp1>&otp2=<otp2>

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)¶

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.

You can call the function like this:: POST /token/setpin?serial=<serial>&userpin=<userpin>&sopin=<sopin> POST /token/setpin/<serial>?userpin=<userpin>&sopin=<sopin>

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/reset/(serial)¶

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

You can call the function like this:: POST /token/reset?serial=<serial> POST /token/reset?user=<user>&realm=<realm> POST /token/reset/<serial>

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/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>

Parameters:	serial (basestring) – the serial number of the single token to reset realms (basestring) – The realms the token should be assigned to. Comma seperated
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.

Parameters:	filename (basestring) – The name of the token file, that is imported type (basestring) – The file type. Can be “aladdin-xml”, “oathcsv” or “yubikeycsv”.
Return:	The number of the imported tokens
Rtype:	int

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

Parameters:	serial (basestring) – the serial number of the lost token.
Return:	returns value=dictionary in case of success
Rtype:	bool

POST /token/set/(serial)¶

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

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.

You can call the function like this:: POST /token/set?serial=<serial>&description=<something> POST /token/set/<serial>?hashlib=<hash> POST /token/set?user=<username>&realm=<realm>&sync_window=100

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

DELETE /token/(serial)¶

Delete a token by its serial number. There are three different ways to delete a token.

DELETE /token/<serial>

Return:	In case of success it return the number of deleted tokens in

“value” :rtype: json object

13.1.1.8. Token endpoints¶

Related Topics

This Page