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

All endpoints require admin authentication. Listing is gated by the admin policy action serviceid_list, creation/update by serviceid_add, deletion by serviceid_delete.

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 authentication and the policy action serviceid_list.

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"
}