16.1.1.29. Subscriptions endpoints

The subscriptions REST API manages subscription files for licensed client components (e.g. RADIUS Credential Provider, Keycloak provider, ownCloud plugin). Subscription files are YAML-encoded and cryptographically signed by the subscription issuer; uploading them registers the subscription, and the GET endpoint reports the current state including remaining validity and how many tokens/users are in use.

All endpoints require admin authentication and the policy action managesubscription.

GET /subscriptions/(application)
GET /subscriptions/

Return all subscriptions stored on this server. Each subscription is enriched with usage information at request time:

  • timedelta — integer, days between today and date_till. Negative while the subscription is still valid, positive after expiry.

  • active_tokens — number of currently assigned active tokens on this server.

  • active_users — number of users with at least one active token.

Requires the admin policy action managesubscription.

Parameters:

  • application – optional path component naming a single application (e.g. privacyIDEA RADIUS); when given, the response is filtered to that application only.

Status Codes:

  • 200 OK – list of subscription dictionaries in result.value.

POST /subscriptions/

Upload a subscription file. The request body must be multipart/form-data with a single field named file carrying the YAML-encoded, signed subscription document. The signature is verified before the subscription is persisted; if a subscription already exists for the same application, it is replaced.

Requires the admin policy action managesubscription.

Request Headers:
Form Parameters:

  • file – signed YAML subscription document.

Status Codes:
DELETE /subscriptions/(application)

Delete the subscription for the given application.

Requires the admin policy action managesubscription.

Parameters:

  • application – path component naming the application whose subscription should be removed.

Status Codes:

  • 200 OK – id of the deleted subscription, or -1 if no subscription existed for application.