16.1.1.11. Container endpoints

API for managing token containers

GET /container/

Get containers depending on the query parameters. If pagesize and page are not provided, all containers are returned at once.

Query Parameters:

  • user – Username of a user assigned to the containers

  • container_serial – Serial of a single container (case-insensitive, can contain ‘*’ as wildcards)

  • type – Type of the containers to return (case-insensitive, can contain ‘*’ as wildcards)

  • token_serial – Serial of a token assigned to the container (case-insensitive, can contain ‘*’ as wildcards)

  • template – Name of the template the container is created from (case-sensitive, can contain ‘*’ as wildcards)

  • container_realm – Name of the realm the container is assigned to (case-insensitive, can contain ‘*’ as wildcards)

  • description – Description of the container (case-insensitive, can contain ‘*’ as wildcards)

  • resolver – Resolver of the user assigned to the container (case-insensitive, can contain ‘*’ as wildcards)

  • assigned – Filter for assigned or unassigned containers (True or False)

  • info_key – Key of the container info (case-sensitive, can contain ‘*’ as wildcards)

  • info_value – Value of the container info (case-insensitive, can contain ‘*’ as wildcards)

  • last_auth_delta – The maximum time difference the last authentication may have to now, e.g. “1y”, “14d”, “1h” The following units are supported: y (years), d (days), h (hours), m (minutes), s (seconds)

  • last_sync_delta – The maximum time difference the last synchronization may have to now, e.g. “1y”, “14d”, “1h” The following units are supported: y (years), d (days), h (hours), m (minutes), s (seconds)

  • state – State the container should have (case-insensitive and allows “*” as wildcard), optional

  • sortby – Sort by a container attribute (serial or type)

  • sortdir – Sort direction (asc or desc)

  • pagesize – Number of containers per page

  • page – Page number

  • no_token – no_token=1: Do not return tokens assigned to the container

POST /container/(string: container_serial)/assign

Assign a container to a user.

Parameters:

  • container_serial – serial of the container

JSON Parameters:

  • user – Username of the user

  • realm – Name of the realm of the user

POST /container/(string: container_serial)/unassign

Unassign a user from a container In case the user does not exist anymore, the user_id is required.

Parameters:

  • container_serial – serial of the container

JSON Parameters:

  • user – Username of the user

  • realm – Realm of the user

  • resolver – Resolver of the user

  • user_id – User ID of the user, to be able to unassign non-existing users

POST /container/init

Create a new container. Raises an EnrollmentError if an invalid type or an already existing serial is provided.

To create a container from a template, the template can either be passed as a dictionary, containing all necessary information for all tokens or only the name of an already existing template in the db. If both are given, a ParameterError is raised.

JSON Parameters:

  • description – Description for the container

  • type – Type of the container. If the type is unknown, an error will be returned

  • container_serial – Optional unique serial (not case-sensitive)

  • user – Optional username to assign the container to. Requires realm param to be present as well.

  • realm – Optional realm to assign the container to. Requires user param to be present as well.

  • template – The template to create the container from (dictionary), optional

  • template_name – The name of the template to create the container from, optional

DELETE /container/(string: container_serial)

Delete a container.

Parameters:

  • container_serial – serial of the container

POST /container/(string: container_serial)/add

Add a single token to a container.

Parameters:

  • container_serial – serial of the container

JSON Parameters:

  • serial – Serial of the token to add.

POST /container/(string: container_serial)/addall

Add multiple tokens to a container.

Parameters:

  • container_serial – serial of the container

JSON Parameters:

  • serial – Comma separated list of token serials

POST /container/(string: container_serial)/remove

Remove a single token from a container.

Parameters:

  • container_serial – serial of the container

JSON Parameters:

  • serial – Serial of the token to remove.

POST /container/(string: container_serial)/removeall

Remove multiple tokens from a container.

Parameters:

  • container_serial – serial of the container

JSON Parameters:

  • serial – Comma separated list of token serials.

GET /container/tokentypes
GET /container/types

Returns a dictionary with the container types as keys and their descriptions and supported token types as values.

{
    type: { description: "Description", token_types: ["hotp", "totp", "push", "daypassword", "sms"] },
    type: { description: "Description", token_types: ["hotp", "totp", "push", "daypassword", "sms"] }
}
POST /container/(string: container_serial)/description

Set the description of a container.

Parameters:

  • container_serial – Serial of the container

JSON Parameters:

  • description – New description to be set

POST /container/(string: container_serial)/states

Set the states of a container.

JSON Parameters:

  • states – string of comma separated states

GET /container/statetypes

Get the supported state types as dictionary. The types are the keys and the value is a list containing all states that are excluded when the key state is selected.

POST /container/(string: container_serial)/realms

Set the realms of a container. Old realms will be deleted.

Parameters:

  • container_serial – Serial of the container

JSON Parameters:

  • realms – comma separated string of realms, e.g. “realm1,realm2”

POST /container/(string: container_serial)/info/(key)

Set the value of a container info key. Overwrites the old value if the key already exists. However, existing entries of type PI_INTERNAL are not overwritten and a PolicyError is raised.

Parameters:

  • container_serial – Serial of the container

  • key – Key of the container info

JSON Parameters:

  • value – Value to set

DELETE /container/(string: container_serial)/info/delete/(key)

Deletes the container info for the given key. Entries of type PI_INTERNAL can not be deleted.

Parameters:

  • container_serial – Serial of the container

  • key – Key of the container info

POST /container/register/initialize

Prepares the registration of a container. It returns all information required for the container to register.

JSON Parameters:

  • container_serial – Serial of the container

Return:

Result of the registration process as dictionary. The information may differ depending on the container type.

An example response for smartphones looks like this:
{
    "container_url": {"description": "URL for privacyIDEA Container Registration",
                      "img": <QR code>,
                      "value": "pia://container/SMPH0006D5BC?issuer=privacyIDEA&ttl=10..."},
    "nonce": "c238392af49250804c25bbd7d86408839e91fe97",
    "time_stamp": "2024-12-20T09:53:40.158319+00:00",
    "server_url": "https://pi.net",
    "ttl": 10,
    "ssl_verify": "True",
    "key_algorithm": "secp384r1",
    "hash_algorithm": "sha256"
}
POST /container/register/finalize

This endpoint is called from a container as second step for the registration process. At least the container serial has to be passed in the parameters. Further parameters might be required depending on the container type.

JSON Parameters:

  • container_serial – Serial of the container

Return:

Result of the registration process as dictionary. The information may differ depending on the container type.

POST /container/register/(string: container_serial)/terminate

Terminates the synchronization of a container with privacyIDEA.

Parameters:

  • container_serial – Serial of the container

Return:

dictionary with success information such as

{"success": True}
POST /container/register/terminate/client

Terminates the synchronization of a container with privacyIDEA. This endpoint can only be called from clients that are registered at the container, providing a valid signature.

JSON Parameters:

  • container_serial – Serial of the container

  • signature – Signature of the client

Return:

dictionary with success information such as

{"success": True}
POST /container/challenge

Creates a challenge for a container.

JSON Parameters:
Return:

dictionary with the challenge information

An example response looks like this:

{
    "server_url": "https://pi.net"
    "nonce": "123456",
    "time_stamp": "2024-10-23T05:45:02.484954+00:00",
}
POST /container/synchronize

Compares the client tokens with the server tokens and returns the differences. Returns a dictionary with the container properties and the tokens to be added or updated. For the tokens to be added, the enroll information is provided containing the tokens secret. For the tokens to be updated, the token details are returned as dictionary. Additionally, the container rights read from the policies are included in the response. Additional parameters and entries in the response are possible, depending on the container type. The container is only authorized to synchronize if the challenge is valid.

JSON Parameters:

  • container_serial – Serial of the container

  • container_dict_client – container data with included tokens from the client. The provided information may differ for different container and token types. To identify tokens at least the serial shall be provided. However, some clients might not have the serial. In this case, the client can provide a list of at least two otp values for hotp, totp and daypassword tokens.

An example container_dict_client looks like this:
{
    "serial": "SMPH001",
    "type": "smartphone",
    "tokens": [{"serial": "TOTP001", ...},
               {"otp": ["1234", "4567"], "tokentype": "hotp"}]
}
Return:

dictionary including the container properties, the tokens and the container policies. The provided enroll information depends on the token type as well as the returned information for the tokens to be updated.

Example response:
{
    "container": {"type": "smartphone", "serial": "SMPH001"},
        "tokens": {"add": ["enroll_url1", "enroll_url2"],
                   "update": [{"serial": "TOTP001", "tokentype": "totp"},
                              {"serial": "HOTP001", "otp": ["1234", "9876"],
                               "tokentype": "hotp", "counter": 2}]}
    "policies": {"container_client_rollover": True,
                 "initially_add_tokens_to_container": False,
                 "disable_client_token_deletion": True,
                 "disable_client_container_unregister": True}
}
POST /container/rollover

Initiate a rollover for a container which will generate new token secrets for all tokens in the container. The data or QR code is returned for the container to re-register. This endpoint can be used to transfer a container from one device to another. Parameters and entries in the returned dictionary are container type specific.

JSON Parameters:

  • container_serial – Serial of the container

Return:

Result of the rollover process as dictionary. The information may differ depending on the container type.

An example response for smartphones looks like this:
{
    "container_url": {"description": "URL for privacyIDEA Container Registration",
                      "img": <QR code>,
                      "value": "pia://container/SMPH0006D5BC?issuer=privacyIDEA&ttl=10..."},
    "nonce": "c238392af49250804c25bbd7d86408839e91fe97",
    "time_stamp": "2024-12-20T09:53:40.158319+00:00",
    "server_url": "https://pi.net",
    "ttl": 10,
    "ssl_verify": "True",
    "key_algorithm": "secp384r1",
    "hash_algorithm": "sha256",
    "passphrase_prompt": ""
}
GET /container/templates

Get all container templates filtered by the given parameters.

Query Parameters:

  • name – Name of the template, optional

  • container_type – Type of the container, optional

  • page – Number of the page (starts with 1), optional

  • pagesize – Number of templates displayed per page, optional

  • sortdir – Sort direction, optional, default is “asc”

  • sortby – column name to sort by, optional, default is “name”

Return:

Dictionary with at least an entry “templates” and further entries if pagination is used.

An example response looks like this:

{
    "templates": [{"name": "template1", "container_type": "smartphone",
                   "template_options": {"tokens": [{"type": "hotp", "genkey": True}, ...]}, ...},
                   {"name": "template2", "container_type": "yubikey", ...},
                   ...],
    "count": 25,
    "current": 1,
    "prev": null,
    "next": 2,
}
POST /container/(string: container_type)/template/(string: template_name)

Creates a template for the given name. If a template with this name already exists, the template options will be updated.

Parameters:

  • container_type – Type of the container

  • template_name – Name of the template

JSON Parameters:

  • template_options – Dictionary with the template options

  • default – Set this template as default for the container type

Return:

ID of the created template or the template that was updated as dictionary such as

{
    "template_id": 1
}
DELETE /container/template/(string: template_name)

Deletes the template of the given name.

Return:

True if the template was deleted successfully, raises an exception otherwise

GET /container/template/(string: template_name)/compare

Compares a template with its created containers. Only containers the user is allowed to manage are included in the comparison.

If a container serial is provided, only this container will be compared to the template.

Parameters:

  • template_name – Name of the template

JSON Parameters:

  • container_serial – Serial of the container to compare with the template, optional

Return:

A dictionary with the differences between the template and each container in the format:

{"SMPH0001": {
                "tokens": {
                            "missing": ["hotp"],
                            "additional": ["totp"]
                            }
                }
}
GET /container/template/tokentypes

Returns a dictionary with the template container types as keys and their description and supported token types as values.

{
    <type>: { description: "Description", token_types: ["hotp", "totp", "push", "daypassword", "sms"] },
    <type>: { description: "Description", token_types: ["hotp", "totp", "push", "daypassword", "sms"] }
}