16.1.1.5. Tokengroup endpoints¶

The tokengroup REST API manages tokengroup definitions. See tokengroups for the conceptual chapter.

All endpoints require admin authentication. Listing is gated by the admin policy action tokengroup_list, creation/update by tokengroup_add, deletion by tokengroup_delete.

POST /tokengroup/(groupname)¶

Create a new tokengroup or update the description of an existing one. The tokengroup name must be unique.

Requires admin authentication and the policy action tokengroup_add.

Parameters:

groupname – path component, the unique name of the tokengroup.

JSON Parameters:

description – free-form description of the tokengroup.

Status Codes:

200 OK – database id of the tokengroup in result.value.

Example request:

POST /tokengroup/groupA HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded

description=My cool first tokengroup

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "status": true,
    "value": 1
  },
  "version": "privacyIDEA unknown"
}

GET /tokengroup/(groupname)¶

GET /tokengroup/¶

Return tokengroup definitions. If groupname is given, only the matching tokengroup is returned; otherwise all tokengroups are listed.

The result is a dictionary keyed by tokengroup name; each value carries description and id.

Requires admin authentication and the policy action tokengroup_list.

Parameters:

groupname – optional path component selecting a single tokengroup.

Status Codes:

200 OK – dict of tokengroups in result.value.

Example request:

GET /tokengroup/ HTTP/1.1
Host: example.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "status": true,
    "value": {
      "gruppe1": {"description": "1st group", "id": 1},
      "gruppe2": {"description": "2nd group", "id": 2}
    }
  },
  "version": "privacyIDEA unknown"
}

DELETE /tokengroup/(groupname)¶

Delete the tokengroup with the given name. The tokengroup must be empty — if any tokens are still assigned to it, the request fails.

Requires admin authentication and the policy action tokengroup_delete.

Parameters:

groupname – path component, the name of the tokengroup.

Status Codes:

200 OK – result.value is 1 on success.
404 Not Found – no tokengroup with that name exists.
400 Bad Request – the tokengroup still has tokens assigned and cannot be deleted.

Example request:

DELETE /tokengroup/gruppe1 HTTP/1.1
Host: example.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "status": true,
    "value": 1
  },
  "version": "privacyIDEA unknown"
}