14.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.

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
Return:	json

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.

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

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

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

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

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": "privacyIDEA 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 privacyIDEA 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 privacyIDEA 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()

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

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 pagesize – limit the number of returned tokens user_fields – additional user fields from the userid resolver of the owner (user) 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

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

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

Query Parameters:
Parameters:	serial – the serial number/identifier of the token key – token info key that should be set
	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

GET /token/challenges/(serial)¶

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
Return:	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.

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

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

POST /token/revoke/(serial)¶

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

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

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

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

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/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 tokens. psk – Pre Shared Key, when importing PSKC
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

JSON 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

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

DELETE /token/(serial)¶

Delete a token by its serial number or delete all tokens of a user.

JSON Parameters:
	serial – The serial number of a single token. user – The username of the user, whose tokens should be deleted. realm – The realm of the user.
Return:	In case of success it return the number of deleted tokens in “value”
Rtype:	json object

14.1.1.8. Token endpoints¶

Related Topics

This Page