15.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 the number of unassigned tokens in “value”.
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.

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

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.

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