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

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

POST /token/unassign

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

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

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

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.

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

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.

The result will be paginated (even with outform=csv) with a default page size of 15 entries.

Query Parameters

  • serial – Display the token data of this single token. You can do a not strict matching by specifying a serial like “OATH”. Multiple serials can be passed as comma separated list.

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

  • type_list – Comma separated list of token types. Display only tokens of the types in the list.

  • 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”, 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

  • container_serial – only list tokens, which are assigned to the container with the given serial or tokens without container if the value is an empty string “”

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.

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

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

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