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.
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 |
Copy the token user from one token to the other.
Parameters: |
|
---|
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
Disable a single token or all the tokens of a user. Disabled tokens can not be used to authenticate but can be enabled again.
Parameters: |
|
---|---|
Return: | In case of success it returns the number of disabled |
tokens in “value”. :rtype: json object
Copy the token PIN from one token to the other.
Parameters: |
|
---|
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
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 |
Enable a single token or all the tokens of a user.
Parameters: |
|
---|---|
Return: | In case of success it returns the number of enabled |
tokens in “value”. :rtype: json object
Resync the OTP token by providing two consecutive OTP values.
Parameters: |
|
---|---|
Return: | In case of success it returns “value”=True |
Rtype: | json object |
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.
Parameters: |
|
---|---|
Return: | In “value” returns the number of PINs set. |
Rtype: | json object |
Reset the failcounter of a single token or of all tokens of a user.
Parameters: |
|
---|---|
Return: | In case of success it returns “value”=True |
Rtype: | json object |
create a new token.
Parameters: |
|
---|
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: |
|
---|---|
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" }
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.
Parameters: |
|
---|---|
Return: | returns the number of attributes set in “value” |
Rtype: | json object |
The method is called at /token Display the list of available tokens.
Parameters: |
|
---|
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 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: |
|
---|---|
Return: | The serial number of the token found |
Disable a single token or all the tokens of a user. Disabled tokens can not be used to authenticate but can be enabled again.
Parameters: |
|
---|---|
Return: | In case of success it returns the number of disabled |
tokens in “value”. :rtype: json object
Enable a single token or all the tokens of a user.
Parameters: |
|
---|---|
Return: | In case of success it returns the number of enabled |
tokens in “value”. :rtype: json object
Resync the OTP token by providing two consecutive OTP values.
Parameters: |
|
---|---|
Return: | In case of success it returns “value”=True |
Rtype: | json object |
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.
Parameters: |
|
---|---|
Return: | In “value” returns the number of PINs set. |
Rtype: | json object |
Reset the failcounter of a single token or of all tokens of a user.
Parameters: |
|
---|---|
Return: | In case of success it returns “value”=True |
Rtype: | json object |
Set the realms of a token. The token is identified by the unique serial number
Parameters: |
|
---|---|
Return: | returns value=True in case of success |
Rtype: | bool |
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: |
|
---|---|
Return: | The number of the imported tokens |
Rtype: | int |
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.
Parameters: |
|
---|---|
Return: | returns value=dictionary in case of success |
Rtype: | bool |
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.
Parameters: |
|
---|---|
Return: | returns the number of attributes set in “value” |
Rtype: | json object |
Delete a token by its serial number. There are three different ways to delete a token. You can call one of these URLs:
POST /token/delete?serial=<serial> DELETE /token/<serial> POST /token/delete/<serial>
Return: | In case of success it return the number of deleted tokens in |
---|
“value” :rtype: json object