17.1.1.8. Service ID endpoints¶

The serviceid REST API manages service ID definitions. Service IDs are used to scope SSH key assignments and application-specific passwords; see Service IDs for the conceptual chapter.

Creation, update and deletion require admin authentication and are gated by the admin policy actions serviceid_add and serviceid_delete. Listing is available to both admins and self-service users - the latter need it to populate the service ID choice when enrolling an application specific password token - and is gated by the policy action serviceid_list in the scope of the caller, see serviceid_list and serviceid_list.

POST /serviceid/(name)¶

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

Requires admin authentication and the policy action serviceid_add.

Parameters:

name – path component, the unique name of the service ID.

JSON Parameters:

description – free-form description of the service ID.

Status Codes:

200 OK – database id of the service ID in result.value.

Example request:

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

description=My cool first service

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 /serviceid/(name)¶

GET /serviceid/¶

Return service ID definitions. If name is given, only the matching service ID is returned; otherwise all service IDs are listed.

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

Requires admin or user authentication and the policy action serviceid_list in the scope of the caller, see serviceid_list and serviceid_list. Self-service users need this to populate the service ID choice when enrolling an application specific password token.

Parameters:

name – optional path component selecting a single service ID.

Status Codes:

200 OK – dict of service IDs in result.value.

Example request:

GET /serviceid/ 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": {
      "service1": {"description": "1st service", "id": 1},
      "service2": {"description": "2nd service", "id": 2}
    }
  },
  "version": "privacyIDEA unknown"
}

DELETE /serviceid/(name)¶

Delete the service ID with the given name.

Warning

This call does not check whether the service ID is still in use by SSH key assignments or application-specific passwords. Removing a service ID that is still referenced will leave those assignments pointing at a missing target.

Requires admin authentication and the policy action serviceid_delete.

Parameters:

name – path component, the name of the service ID.

Status Codes:

200 OK – result.value is 1 on success.
404 Not Found – no service ID with that name exists.

Example request:

DELETE /serviceid/service1 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"
}