Administrative Services

View product develop

The PowerAuth Admin API consists of several API resource groups:

The Application Services provide services for managing applications.
The Application Configuration Services provide services for managing application configurations.
The Callback URL Services provide services for managing callbacks, enabling real-time notifications for your systems whenever status of a registration or an operation changes.
The Internal Services provide services that are used for invoking internal system calls.
The Push Notification Services provide services for managing push notifications.
The System Users Services provide services for managing system users.
The Telemetry Services provide services to query various statistics about the PowerAuth system usage.

Possible Error Codes

The API may return one of the following error codes:

HTTP Status Code	Error Code	Description
`400`	`ERROR_REGISTRATION`	Registration related error occurred.
`400`	`ERROR_REGISTRATION_NOT_FOUND`	Registration was not found during a call where registration is expected.
`400`	`ERROR_REGISTRATION_NOT_ALLOWED`	Registration was not allowed because another registration is already in progress for the user.
`400`	`ERROR_REGISTRATION_CHANGE`	Invalid registration change was attempted.
`400`	`ERROR_OPERATION_NOT_FOUND`	Operation was not found during a call where operation is expected.
`400`	`ERROR_OPERATION_STATE_CHANGE`	Invalid operation change was attempted.
`400`	`ERROR_OTP_INVALID`	Offline certification - OTP format is invalid.
`400`	`ERROR_AUDIT`	Error occurred while fetching the audit log.
`400`	`ERROR_REQUEST`	Request did not pass validation (mandatory property missing, null/invalid value).
`401`	`ERROR_UNAUTHORIZED`	Returned in the case authentication fails (invalid application credentials).
`404`	`ERROR_NOT_FOUND`	Returned in the case URL is not present (calling wrong API).
`500`	`ERROR_GENERIC`	Unknown error occurred while processing request.
`500`	`ERROR_INTERNAL_API`	Communication with internal service failed.

Please ensure your application handles these errors appropriately, displaying user-friendly messages or taking corrective actions as needed.

Application Services

post /admin/applications Create Application

Create a new app with provided ID.

Request

{
  "id": "MY_APP_01",
  "roles": [
    "ROLE1",
    "ROLE2"
  ]
}

Response

{
  "id": "MY_APP_01",
  "serviceBaseUrl": "https://api.example.com/",
  "mobileSdkConfig": "ARB...w==",
  "roles": [
    "ROLE1", "ROLE2"
  ],
  "appKey": "b34...==",
  "appSecret": "aef...=="
}

Attribute	Type	Description
`id`*	String	Name of the application.
`serviceBaseUrl`*	URL	Base URL of the PowerAuth Standard RESTful API. This attribute is only returned if the property named `service.base.url` is set in the table `pa_cloud_property`.
`mobileSdkConfig`*	String	Configuration string for mobile SDK.
`roles`*	String[]	Collection of application roles.
`appKey`*	String	(deprecated) App Key (value for the mobile app configuration).
`appSecret`*	String	(deprecated) App Secret (value for the mobile app configuration).

Unable to return application because of the invalid application name or version.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_ADMIN",
    "message": "No enabled application version was found"
  }
}

Invalid username or password was provided while calling the service.

{
  "status": "ERROR",
  "responseObject": {
    "code": "HTTP_401",
    "message": "Unauthorized"
  }
}

Error occurred while calling the internal service. This can happen only as a result of misconfiguration. Check your deployment configuration for errors.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INTERNAL_API",
    "message": "Unable to call upstream service"
  }
}

get /admin/applications Get Application List

Obtain a list of all the applications in the system.

Request

Empty Request

Response

{
  "applications": [
    {
      "id": "demo-app1"
    },
    {
      "id": "demo-app2"
    }
  ]
}

Attribute	Type	Description
`applications`*	String	Root element for the application list.
`applications[].id`	String	Unique identifier of the application

Invalid username or password was provided while calling the service.

{
  "status": "ERROR",
  "responseObject": {
    "code": "HTTP_401",
    "message": "Unauthorized"
  }
}

Error occurred while calling the internal service. This can happen only as a result of misconfiguration. Check your deployment configuration for errors.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INTERNAL_API",
    "message": "Unable to call upstream service"
  }
}

get /admin/applications/{id} Get App Details

Obtain the configuration for an app with provided ID.

Request

Path Params

Param	Type	Description
`id`	`String`	ID of the application.

Response

{
  "id": "MY_APP_01",
  "serviceBaseUrl": "https://api.example.com/",
  "mobileSdkConfig": "ARB...w==",
  "roles": [
    "ROLE1", "ROLE2"
  ],
  "appKey": "b34...==",
  "appSecret": "aef...=="
}

Attribute	Type	Description
`id`*	String	Name of the application.
`serviceBaseUrl`*	URL	Base URL of the PowerAuth Standard RESTful API.
`mobileSdkConfig`*	String	Configuration string for mobile SDK.
`roles`*	String[]	Collection of application roles.
`appKey`*	String	(deprecated) App Key (value for the mobile app configuration).
`appSecret`*	String	(deprecated) App Secret (value for the mobile app configuration).

Unable to return application because of the invalid application name or version.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_ADMIN",
    "message": "No enabled application version was found"
  }
}

Invalid username or password was provided while calling the service.

{
  "status": "ERROR",
  "responseObject": {
    "code": "HTTP_401",
    "message": "Unauthorized"
  }
}

Error occurred while calling the internal service. This can happen only as a result of misconfiguration. Check your deployment configuration for errors.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INTERNAL_API",
    "message": "Unable to call upstream service"
  }
}

post /admin/applications/roles Add Roles To Application

Add roles to an app with provided ID. The call ignores duplicities on application roles.

Request

{
  "id": "MY_APP_01",
  "roles": [
    "ROLE1",
    "ROLE2"
  ]
}

Response

{
  "status": "OK"
}

When formal request validation fails, i.e., due to missing application ID.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_REQUEST",
    "message": "Invalid method parameter value",
    "violations": [
      {
        "fieldName": "id",
        "hint": "must not be empty"
      }
    ]
  }
}

Invalid username or password was provided while calling the service.

{
  "status": "ERROR",
  "responseObject": {
    "code": "HTTP_401",
    "message": "Unauthorized"
  }
}

Error occurred while calling the internal service. This can happen only as a result of misconfiguration. Check your deployment configuration for errors.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INTERNAL_API",
    "message": "Unable to call upstream service"
  }
}

post /admin/applications/{id}/roles/remove Remove Roles From Application

Remove roles from an app with provided ID. The call ignores missing roles to be removed from an application.

Request

{
  "roles": [
    "ROLE1",
    "ROLE2"
  ]
}

Path Params

Attribute	Type	Description
`id`*	`String`	ID of the application, whose role should be removed.

Request Params

Attribute	Type	Description
`roles`*	`String[]`	Collection of roles to be removed.

Response

{
  "status": "OK"
}

When formal request validation fails, i.e., due to missing application ID.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_REQUEST",
    "message": "Invalid method parameter value",
    "violations": [
      {
        "fieldName": "id",
        "hint": "must not be empty"
      }
    ]
  }
}

Invalid username or password was provided while calling the service.

{
  "status": "ERROR",
  "responseObject": {
    "code": "HTTP_401",
    "message": "Unauthorized"
  }
}

Error occurred while calling the internal service. This can happen only as a result of misconfiguration. Check your deployment configuration for errors.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INTERNAL_API",
    "message": "Unable to call upstream service"
  }
}

Application Configuration Services

get /admin/applications/{id}/config Get Application Configuration

Get configuration for an application with provided application ID.

Request

Path Params

Param	Type	Description
`id`	`String`	Identifier of the application.

Response

{
  "appId": "dev",
  "applicationConfigs": [
    {
      "key": "fido2_aaguids_allowed",
      "values": [
        "b34d6780-4264-459e-9b99-600a21017a69",
        "2aa64fc5-bf88-4681-b18f-98404d0d3661"
      ]
    },
    {
      "key": "fido2_attestation_fmt_allowed",
      "values": [
        "packed"
      ]
    }
  ]
}

Attribute	Type	Description
`appId`*	String	Identifier of the application.
`applicationConfigs`*	Array	Array of application configurations.
`key`*	String	Configuration key.
`values`	Object	Configuration values for given configuration key.

Invalid username or password was provided while calling the service.

{
  "status": "ERROR",
  "responseObject": {
    "code": "HTTP_401",
    "message": "Unauthorized"
  }
}

Error occurred while calling the internal service. This can happen only as a result of misconfiguration. Check your deployment configuration for errors.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INTERNAL_API",
    "message": "Unable to call upstream service"
  }
}

post /admin/applications/{id}/config Create Application Configuration

Create or update a configuration for an application with provided application ID.

Request

{
  "key": "fido2_attestation_fmt_allowed",
  "values": ["packed"]
}

Attribute	Type	Description
`key`*	String	Configuration key to create or update.
`values`	Object	Configuration values for given configuration key.

Path Params

Param	Type	Description
`id`	`String`	Identifier of the application.

Response

{
  "appId": "dev",
  "key": "fido2_attestation_fmt_allowed",
  "values": [
    "packed"
  ]
}

Attribute	Type	Description
`appId`*	String	Identifier of the application.
`key`*	String	Configuration key.
`values`	Object	Configuration values for given configuration key.

Unable to return application configuration because application does not exist or configuration key is invalid.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_ADMIN",
    "message": "Invalid create application configuration request for configuration key: invalid"
  }
}

Invalid username or password was provided while calling the service.

{
  "status": "ERROR",
  "responseObject": {
    "code": "HTTP_401",
    "message": "Unauthorized"
  }
}

Error occurred while calling the internal service. This can happen only as a result of misconfiguration. Check your deployment configuration for errors.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INTERNAL_API",
    "message": "Unable to call upstream service"
  }
}

delete /admin/applications/{id}/config Remove Application Configuration

Remove a configuration for an application with provided application ID.

Request

{
  "key": "fido2_attestation_fmt_allowed"
}

Attribute	Type	Description
`key`*	String	Configuration key to remove.

Path Params

Param	Type	Description
`id`	`String`	Identifier of the application.

Response

{
  "status": "OK"
}

Unable to return application configuration because application does not exist or configuration key is invalid.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_ADMIN",
    "message": "Invalid remove application configuration request for configuration key: invalid"
  }
}

Invalid username or password was provided while calling the service.

{
  "status": "ERROR",
  "responseObject": {
    "code": "HTTP_401",
    "message": "Unauthorized"
  }
}

Error occurred while calling the internal service. This can happen only as a result of misconfiguration. Check your deployment configuration for errors.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INTERNAL_API",
    "message": "Unable to call upstream service"
  }
}

Callback URL Services

PowerAuth Cloud can notify your systems via a callback (sometimes called “webhooks”) whenever status of a registration or an operation changes. This API provides a convenient way to manage callbacks associated with an existing application.

There are two callback types:

Registration callbacks are called whenever registration status changes.
Operation callbacks are called whenever operation status changes.

post /v2/admin/applications/{appId}/callbacks Create New Callback

Request

{
  "name": "$CALLBACK_NAME",
  "type": "$(REGISTRATION_STATUS_CHANGE|OPERATION_STATUS_CHANGE)",
  "callbackUrl": "$CALLBACK_URL",
  "attributes": [
    "$ATTRIBUTE1",
    "$ATTRIBUTE2"
  ],
  "authentication": {
    "certificate": {
      "enabled": true,
      "useCustomKeyStore": true,
      "keyStoreLocation": null,
      "keyStoreContent": "MIIKAAIBA...",
      "keyStorePassword": "changeit",
      "keyAlias": "temp",
      "keyPassword": "changeit",
      "useCustomTrustStore": true,
      "trustStoreLocation": null,
      "trustStoreContent": "MIIKAAIBA...",
      "trustStorePassword": "changeit"
    },
    "httpBasic": {
      "enabled": true,
      "username": "$USERNAME",
      "password": "$PASSWORD"
    },
    "oauth2": {
      "enabled": true,
      "clientId": "$CLIENT_ID",
      "clientSecret": "$CLIENT_SECRET",
      "tokenUri": "$TOKEN_URI",
      "scope": "$SCOPE"
    }
  },
  "retentionPeriod": "P30D",
  "initialBackoff": "PT2S",
  "maxAttempts": 1
}

Path Params

Attribute	Type	Description
`appId`*	`String`	ID of the application to which the callback is registered.

Request Params

Attribute	Type	Description
`name`*	`String`	Name of the callback to identify the callback purpose.
`type`*	`CallbackUrlType`	Type of the callback. Either `REGISTRATION_STATUS_CHANGE` or `OPERATION_STATUS_CHANGE`.
`callbackUrl`*	`String`	Callback URL that is able to receive update callbacks.
`attributes`	`String[]`	Attributes to include into the callback.
`authentication.certificate.enabled`	`boolean`	Whether to enable certificate-based authentication.
`authentication.certificate.useCustomKeyStore`	`boolean`	Whether custom keystore should be used for certificate-based authentication.
`authentication.certificate.keyStoreLocation`	`String`	Location of keystore on the filesystem. Do not use when `keyStoreContent` is set.
`authentication.certificate.keyStoreContent`	`String`	Keystore content encoded in Base64 encoding. Do not use when `keyStoreLocation` is set.
`authentication.certificate.keyStorePassword`	`String`	Keystore password used for accessing the keystore file.
`authentication.certificate.keyAlias`	`String`	Alias of the key inside the keystore used for certificate-based authentication.
`authentication.certificate.keyPassword`	`String`	Password used for encrypting the key used for certificate-based authentication.
`authentication.certificate.useCustomTrustStore`	`boolean`	Whether custom truststore is used for certificate-based authentication.
`authentication.certificate.trustStoreLocation`	`String`	Location of truststore on the filesystem. Do not use when `trustStoreContent` is set.
`authentication.certificate.trustStoreContent`	`boolean`	Truststore content encoded in Base64 encoding. Do not use when `trustStoreLocation` is set.
`authentication.certificate.trustStorePassword`	`boolean`	Truststore password used for accessing the truststore file.
`authentication.httpBasic.enabled`	`boolean`	Whether to enable the HTTP basic authentication.
`authentication.httpBasic.username`	`String`	Username for the HTTP basic authentication.
`authentication.httpBasic.password`	`String`	Password for the HTTP basic authentication.
`authentication.oauth2.enabled`	`boolean`	Whether to enable the OAuth2 authentication.
`authentication.oauth2.clientId`	`String`	Client ID for the OAuth2 authentication.
`authentication.oauth2.clientSecret`	`String`	Client secret for the OAuth2 authentication.
`authentication.oauth2.tokenUri`	`String`	Token URI for the OAuth2 authentication.
`authentication.oauth2.scope`	`String`	Scope for the OAuth2 authentication.
`retentionPeriod`	`Duration`	Duration in ISO 8601 duration format after which a completed callback event is automatically removed from database.
`initialBackoff`	`Duration`	Initial delay in ISO 8601 duration format before retry attempt following a callback event failure, if retries are enabled.
`maxAttempts`	`Integer`	Maximum number of attempts to send a callback event.

The attributes list differs slightly based on the type of the callback. See the Callback API (WebHooks) for a description of the attributes.

Callbacks with mTLS authentication currently cannot be managed via API.

Response

{
  "applicationId": "$APPLICATION_ID",
  "callbackId": "$CALLBACK_ID",
  "name": "$CALLBACK_NAME",
  "type": "$(REGISTRATION_STATUS_CHANGE|OPERATION_STATUS_CHANGE)",
  "callbackUrl": "$CALLBACK_URL",
  "attributes": [
    "$ATTRIBUTE1",
    "$ATTRIBUTE2"
  ],
  "authentication": {
    "httpBasic": {
      "enabled": true,
      "username": "$USERNAME",
      "passwordSet": true
    },
    "oauth2": {
      "enabled": true,
      "clientId": "$CLIENT_ID",
      "clientSecretSet": true,
      "tokenUri": "$TOKEN_URI",
      "scope": "$SCOPE"
    }
  },
  "retentionPeriod": "P30D",
  "initialBackoff": "PT2S",
  "maxAttempts": 1
}

Request validation failed.

Application with specified applicationId does not exist.
Passed callbackUrl is not valid.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_ADMIN",
    "message": "$ERROR_MESSAGE"
  }
}

Invalid username or password was provided while calling the service.

{
  "status": "ERROR",
  "responseObject": {
    "code": "HTTP_401",
    "message": "Unauthorized"
  }
}

Error occurred while calling the internal service. This can happen only as a result of misconfiguration. Check your deployment configuration for errors.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INTERNAL_API",
    "message": "Unable to call upstream service"
  }
}

get /v2/admin/applications/{appId}/callbacks Get Callback List

List all callbacks associated with a given application.

Request

Path Params

Attribute	Type	Description
`appId`*	`String`	ID of the application whose callbacks are to be listed.

Response

{
  "callbacks": [
    {
      "applicationId": "$APPLICATION_ID",
      "callbackId": "$CALLBACK_ID",
      "name": "$CALLBACK_NAME",
      "type": "$(REGISTRATION_STATUS_CHANGE|OPERATION_STATUS_CHANGE)",
      "callbackUrl": "$CALLBACK_URL",
      "attributes": [
        "$ATTRIBUTE1",
        "$ATTRIBUTE2"
      ],
      "authentication": {
        "httpBasic": {
          "enabled": true,
          "username": "$USERNAME",
          "passwordSet": true
        },
        "oauth2": {
          "enabled": true,
          "clientId": "$CLIENT_ID",
          "clientSecretSet": true,
          "tokenUri": "$TOKEN_URI",
          "scope": "$SCOPE"
        }
      },
      "retentionPeriod": "P30D",
      "initialBackoff": "PT2S",
      "maxAttempts": 1
    }
  ]
}

Request validation failed.

Application with specified applicationId does not exist.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_ADMIN",
    "message": "$ERROR_MESSAGE"
  }
}

Invalid username or password was provided while calling the service.

{
  "status": "ERROR",
  "responseObject": {
    "code": "HTTP_401",
    "message": "Unauthorized"
  }
}

Error occurred while calling the internal service. This can happen only as a result of misconfiguration. Check your deployment configuration for errors.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INTERNAL_API",
    "message": "Unable to call upstream service"
  }
}

put /v2/admin/applications/{appId}/callbacks/{callbackId} Update Callback

Edit an existing callback url.

Request

{
  "name": "$CALLBACK_NAME",
  "type": "$(REGISTRATION_STATUS_CHANGE|OPERATION_STATUS_CHANGE)",
  "callbackUrl": "$CALLBACK_URL",
  "attributes": [
    "$ATTRIBUTE1",
    "$ATTRIBUTE2"
  ],
  "authentication": {
    "httpBasic": {
      "enabled": true,
      "username": "$USERNAME",
      "password": "$PASSWORD"
    },
    "oauth2": {
      "enabled": true,
      "clientId": "$CLIENT_ID",
      "clientSecret": "$CLIENT_SECRET",
      "tokenUri": "$TOKEN_URI",
      "scope": "$SCOPE"
    }
  },
  "retentionPeriod": "P30D",
  "initialBackoff": "PT2S",
  "maxAttempts": 1
}

Path Params

Attribute	Type	Description
`appId`*	`String`	ID of the application whose callback is to be edited.
`callbackId`*	`String`	ID of the callback to edit.

Request Params

Attribute	Type	Description
`name`*	`String`	Name of the callback to identify the callback purpose.
`type`*	`CallbackUrlType`	Type of the callback. Either `REGISTRATION_STATUS_CHANGE` or `OPERATION_STATUS_CHANGE`.
`callbackUrl`*	`String`	Callback URL that is able to receive update callbacks.
`attributes`	`String[]`	Attributes to include into the callback.
`authentication.httpBasic.enabled`	`Boolean`	Whether to enable the HTTP basic authentication.
`authentication.httpBasic.username`	`String`	Username for the HTTP basic authentication.
`authentication.httpBasic.password`	`String`	Password for the HTTP basic authentication.
`authentication.oauth2.enabled`	`Boolean`	Whether to enable the OAuth2 authentication.
`authentication.oauth2.clientId`	`String`	Client ID for the OAuth2 authentication.
`authentication.oauth2.clientSecret`	`String`	Client secret for the OAuth2 authentication.
`authentication.oauth2.tokenUri`	`String`	Token URI for the OAuth2 authentication.
`authentication.oauth2.scope`	`String`	Scope for the OAuth2 authentication.
`retentionPeriod`	`Duration`	Duration in ISO 8601 duration format after which a completed callback event is automatically removed from database.
`initialBackoff`	`Duration`	Initial delay in ISO 8601 duration format before retry attempt following a callback event failure, if retries are enabled.
`maxAttempts`	`Integer`	Maximum number of attempts to send a callback event.

The attributes list differs slightly based on the type of the callback. See the Callback API (WebHooks) for a description of the attributes.

Response

{
  "applicationId": "$APPLICATION_ID",
  "callbackId": "$CALLBACK_ID",
  "name": "$CALLBACK_NAME",
  "type": "$(REGISTRATION_STATUS_CHANGE|OPERATION_STATUS_CHANGE)",
  "callbackUrl": "$CALLBACK_URL",
  "attributes": [
    "$ATTRIBUTE1",
    "$ATTRIBUTE2"
  ],
  "authentication": {
    "httpBasic": {
      "enabled": true,
      "username": "$USERNAME",
      "passwordSet": true
    },
    "oauth2": {
      "enabled": true,
      "clientId": "$CLIENT_ID",
      "clientSecretSet": true,
      "tokenUri": "$TOKEN_URI",
      "scope": "$SCOPE"
    }
  },
  "retentionPeriod": "P30D",
  "initialBackoff": "PT2S",
  "maxAttempts": 1
}

Request validation failed.

Application with specified appId does not exist.
Callback with specified callbackId does not exist.
Passed callbackUrl is not valid.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_ADMIN",
    "message": "$ERROR_MESSAGE"
  }
}

Invalid username or password was provided while calling the service.

{
  "status": "ERROR",
  "responseObject": {
    "code": "HTTP_401",
    "message": "Unauthorized"
  }
}

Error occurred while calling the internal service. This can happen only as a result of misconfiguration. Check your deployment configuration for errors.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INTERNAL_API",
    "message": "Unable to call upstream service"
  }
}

delete /v2/admin/applications/{appId}/callbacks/{callbackId} Remove Callback

Remove a callback url from an application’s callback list.

Request

Path Params

Attribute	Type	Description
`appId`*	`String`	ID of the application whose callback is to be removed.
`callbackId`*	`String`	ID of the callback to remove.

Response

{
  "status": "OK"
}

Attribute	Type	Description
`status`*	`String`	Fixed value `OK`.

Request validation failed.

Application with specified appId does not exist.
Callback with specified callbackId does not exist.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_ADMIN",
    "message": "$ERROR_MESSAGE"
  }
}

Invalid username or password was provided while calling the service.

{
  "status": "ERROR",
  "responseObject": {
    "code": "HTTP_401",
    "message": "Unauthorized"
  }
}

Error occurred while calling the internal service. This can happen only as a result of misconfiguration. Check your deployment configuration for errors.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INTERNAL_API",
    "message": "Unable to call upstream service"
  }
}

Internal Services

Internal callbacks are not supposed to be directly called by the app developer. They are intended for internal systems, as a means to notify the cloud component about various internal changes.

post /internal/callback/operation Operation Callback

Operation status changed internally, i.e., operation expired.

Request

{
  "operationId": "$OPERATION_ID"
}

Attribute	Type	Description
`operationId`*	`UUID`	ID of an operation check the status on callback in order to obtain the current status.

Response

{
  "status": "OK"
}

Attribute	Type	Description
`status`*	`String`	Fixed value `OK`.

Request validation failed.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_REQUEST",
    "message": "Required String parameter 'operationId' is not present"
  }
}

ERROR_REQUEST - Request did not pass a structural validation (mandatory field is null, invalid field type, etc.).

Invalid username or password was provided while calling the service.

{
  "status": "ERROR",
  "responseObject": {
    "code": "HTTP_401",
    "message": "Unauthorized"
  }
}

Error occurred while calling the internal service. This can happen only as a result of misconfiguration. Check your deployment configuration for errors.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INTERNAL_API",
    "message": "Unable to call upstream service"
  }
}

Push Notification Services

get admin/applications/{id}/push Fetch Push Configuration

Fetch push notification configuration for specified application.

Request

Path Params

Param	Type	Description
`id`*	`String`	ID of the application.

Response

{
  "id": "config123",
  "apns": {
    "topic": "com.example.MyApp",
    "keyId": "ABCD1234",
    "teamId": "EFGH5678",
    "environment": "DEVELOPMENT"
  },
  "fcm": {
    "projectId": "my-fcm-project-123"
  },
  "hms": {
    "projectId": "my-hms-project-456"
  }
}

Attribute	Type	Description
`id`*	`String`	The unique identifier of the push configuration.
`apns`	`Object`	Contains the Apple Push Notification service (APNs) configuration.
`apns.topic`*	`String`	The application bundle ID for APNs.
`apns.keyId`*	`String`	The identifier of the key used for APNs authentication.
`apns.teamId`*	`String`	The identifier of the team or developer account in the Apple Developer Program.
`apns.environment`*	`String`	Indicates the APNs environment, can be either `DEVELOPMENT` or `PRODUCTION`.
`fcm`	`Object`	Contains the Firebase Cloud Messaging (FCM) configuration.
`fcm.projectId`*	`String`	The identifier of the Firebase project for FCM.
`hms`	`Object`	Contains the Huawei Mobile Services (HMS) configuration.
`hms.projectId`*	`String`	The identifier of the HMS project.

Invalid username or password was provided while calling the service.

{
  "status": "ERROR",
  "responseObject": {
    "code": "HTTP_401",
    "message": "Unauthorized"
  }
}

Error occurred while calling the internal service. This can happen only as a result of misconfiguration. Check your deployment configuration for errors.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INTERNAL_API",
    "message": "Unable to call upstream service"
  }
}

post admin/applications/{id}/push/apns Update Apple Push Notification Service Configuration

Update Apple push notification service configuration for specified application.

Request

{
  "topic": "com.wultra.apns.topic",
  "keyId": "ABC123DEFG",
  "teamId": "DEF123GHIJ",
  "environment": "PRODUCTION",
  "privateKeyBase64": "QmFzZT...ZmlsZSAoKi5wOCk="
}

Attribute	Type	Description
`topic`*	String	The topic of the APNs request.
`keyId`*	String	The key ID for the APNs request.
`teamId`*	String	The team ID for the APNs request.
`environment`*	ApnsEnvironment	The environment for the APNs request, indicating either development or production.
`privateKeyBase64`*	String	Base64 encoded content of the entire private key file.

Path Params

Param	Type	Description
`id` *	`String`	ID of the application.

Response

{
  "id": "config123",
  "apns": {
    "topic": "com.example.MyApp",
    "keyId": "ABCD1234",
    "teamId": "EFGH5678",
    "environment": "DEVELOPMENT"
  },
  "fcm": {
    "projectId": "my-fcm-project-123"
  },
  "hms": {
    "projectId": "my-hms-project-456"
  }
}

Attribute	Type	Description
`id`*	`String`	The unique identifier of the push configuration.
`apns`	`Object`	Contains the Apple Push Notification service (APNs) configuration.
`apns.topic`*	`String`	The application bundle ID for APNs.
`apns.keyId`*	`String`	The identifier of the key used for APNs authentication.
`apns.teamId`*	`String`	The identifier of the team or developer account in the Apple Developer Program.
`apns.environment`*	`String`	Indicates the APNs environment, can be either `DEVELOPMENT` or `PRODUCTION`.
`fcm`	`Object`	Contains the Firebase Cloud Messaging (FCM) configuration.
`fcm.projectId`*	`String`	The identifier of the Firebase project for FCM.
`hms`	`Object`	Contains the Huawei Mobile Services (HMS) configuration.
`hms.projectId`*	`String`	The identifier of the HMS project.

Request validation failed.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_REQUEST",
    "message": "Required String parameter 'topic' is not present"
  }
}

ERROR_REQUEST - Request did not pass a structural validation (mandatory field is null, invalid field type, etc.).

Invalid username or password was provided while calling the service.

{
  "status": "ERROR",
  "responseObject": {
    "code": "HTTP_401",
    "message": "Unauthorized"
  }
}

Error occurred while calling the internal service. This can happen only as a result of misconfiguration. Check your deployment configuration for errors.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INTERNAL_API",
    "message": "Unable to call upstream service"
  }
}

delete admin/applications/{id}/push/apns Delete Apple Push Notification Service Configuration

Delete Apple push notification configuration for specified application.

Request

Path Params

Param	Type	Description
`id` *	`String`	ID of the application.

Response

{
  "status": "OK"
}

Attribute	Type	Description
`status`*	`String`	Fixed value `OK`.

Invalid username or password was provided while calling the service.

{
  "status": "ERROR",
  "responseObject": {
    "code": "HTTP_401",
    "message": "Unauthorized"
  }
}

Error occurred while calling the internal service. This can happen only as a result of misconfiguration. Check your deployment configuration for errors.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INTERNAL_API",
    "message": "Unable to call upstream service"
  }
}

post admin/applications/{id}/push/fcm Update Firebase Cloud Messaging Configuration

Update Firebase cloud messaging configuration for specified application.

Request

{
  "projectId": "fcm-project-id",
  "privateKeyBase64": "QmFzZT...ZmlsZSAoKi5wOCk="
}

Attribute	Type	Description
`projectId`	String	The project id of the FCM request.
`privateKeyBase64`*	String	Base64 encoded content of the entire json private key file obtained from Firebase console.

Path Params

Param	Type	Description
`id` *	`String`	ID of the application.

Response

{
  "id": "config123",
  "apns": {
    "topic": "com.example.MyApp",
    "keyId": "ABCD1234",
    "teamId": "EFGH5678",
    "environment": "DEVELOPMENT"
  },
  "fcm": {
    "projectId": "my-fcm-project-123"
  },
  "hms": {
    "projectId": "my-hms-project-456"
  }
}

Attribute	Type	Description
`id`*	`String`	The unique identifier of the push configuration.
`apns`	`Object`	Contains the Apple Push Notification service (APNs) configuration.
`apns.topic`*	`String`	The application bundle ID for APNs.
`apns.keyId`*	`String`	The identifier of the key used for APNs authentication.
`apns.teamId`*	`String`	The identifier of the team or developer account in the Apple Developer Program.
`apns.environment`*	`String`	Indicates the APNs environment, can be either `DEVELOPMENT` or `PRODUCTION`.
`fcm`	`Object`	Contains the Firebase Cloud Messaging (FCM) configuration.
`fcm.projectId`*	`String`	The identifier of the Firebase project for FCM.
`hms`	`Object`	Contains the Huawei Mobile Services (HMS) configuration.
`hms.projectId`*	`String`	The identifier of the HMS project.

Request validation failed.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_REQUEST",
    "message": "Required String parameter 'privateKeyBase64' is not present"
  }
}

ERROR_REQUEST - Request did not pass a structural validation (mandatory field is null, invalid field type, etc.).

Invalid username or password was provided while calling the service.

{
  "status": "ERROR",
  "responseObject": {
    "code": "HTTP_401",
    "message": "Unauthorized"
  }
}

Error occurred while calling the internal service. This can happen only as a result of misconfiguration. Check your deployment configuration for errors.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INTERNAL_API",
    "message": "Unable to call upstream service"
  }
}

delete admin/applications/{id}/push/fcm Delete Firebase Cloud Messaging Configuration

Delete Firebase cloud messaging configuration for specified application.

Request

Path Params

Param	Type	Description
`id` *	`String`	ID of the application.

Response

{
  "status": "OK"
}

Attribute	Type	Description
`status`*	`String`	Fixed value `OK`.

Invalid username or password was provided while calling the service.

{
  "status": "ERROR",
  "responseObject": {
    "code": "HTTP_401",
    "message": "Unauthorized"
  }
}

Error occurred while calling the internal service. This can happen only as a result of misconfiguration. Check your deployment configuration for errors.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INTERNAL_API",
    "message": "Unable to call upstream service"
  }
}

post admin/applications/{id}/push/hms Update Huawei Mobile Services Configuration

Update Huawei mobile services configuration for specified application.

Request

{
  "projectId": "hms-project-id",
  "clientId": "my-client-id",
  "clientSecret": "my-client-secret"
}

Attribute	Type	Description
`projectId`*	String	The project ID for the HMS request. Example: “hms-project-id”.
`clientId`*	String	Huawei OAuth 2.0 client ID.
`clientSecret`*	String	Huawei OAuth 2.0 client secret.

Path Params

Param	Type	Description
`id` *	`String`	ID of the application.

Response

{
  "id": "config123",
  "apns": {
    "topic": "com.example.MyApp",
    "keyId": "ABCD1234",
    "teamId": "EFGH5678",
    "environment": "DEVELOPMENT"
  },
  "fcm": {
    "projectId": "my-fcm-project-123"
  },
  "hms": {
    "projectId": "my-hms-project-456"
  }
}

Attribute	Type	Description
`id`*	`String`	The unique identifier of the push configuration.
`apns`	`Object`	Contains the Apple Push Notification service (APNs) configuration.
`apns.topic`*	`String`	The application bundle ID for APNs.
`apns.keyId`*	`String`	The identifier of the key used for APNs authentication.
`apns.teamId`*	`String`	The identifier of the team or developer account in the Apple Developer Program.
`apns.environment`*	`String`	Indicates the APNs environment, can be either `DEVELOPMENT` or `PRODUCTION`.
`fcm`	`Object`	Contains the Firebase Cloud Messaging (FCM) configuration.
`fcm.projectId`*	`String`	The identifier of the Firebase project for FCM.
`hms`	`Object`	Contains the Huawei Mobile Services (HMS) configuration.
`hms.projectId`*	`String`	The identifier of the HMS project.

Request validation failed.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_REQUEST",
    "message": "Required String parameter 'projectId' is not present"
  }
}

ERROR_REQUEST - Request did not pass a structural validation (mandatory field is null, invalid field type, etc.).

Invalid username or password was provided while calling the service.

{
  "status": "ERROR",
  "responseObject": {
    "code": "HTTP_401",
    "message": "Unauthorized"
  }
}

Error occurred while calling the internal service. This can happen only as a result of misconfiguration. Check your deployment configuration for errors.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INTERNAL_API",
    "message": "Unable to call upstream service"
  }
}

delete admin/applications/{id}/push/hms Delete Huawei Mobile Service Configuration

Delete Huawei mobile service configuration for specified application.

Request

Path Params

Param	Type	Description
`id` *	`String`	ID of the application.

Response

{
  "status": "OK"
}

Attribute	Type	Description
`status`*	`String`	Fixed value `OK`.

Invalid username or password was provided while calling the service.

{
  "status": "ERROR",
  "responseObject": {
    "code": "HTTP_401",
    "message": "Unauthorized"
  }
}

Error occurred while calling the internal service. This can happen only as a result of misconfiguration. Check your deployment configuration for errors.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INTERNAL_API",
    "message": "Unable to call upstream service"
  }
}

System Users Services

The System Users Services provide user administration endpoints. All endpoints require an administrator.

get admin/users Get User List

Obtain a list of all system users.

Request

Empty Request

Response

{
  "users": [
    {
      "username": "system-user",
      "enabled": true
    }
  ]
}

Attribute	Type	Description
`users`*	Object[]	List of system users.
`users[].username`*	String	Username used to sign in.
`users[].enabled`*	Boolean	Whether the user is enabled to authenticate.

post admin/users Create User

Create a system user. A random password is generated and returned in the response. The username must contain 3 to 255 letters, digits, underscores, or hyphens. New users are enabled and are assigned the ROLE_USER role by default.

Request

{
  "username": "system-user"
}

Attribute	Type	Description
`username`*	String	Username for the new user (3–255 letters, digits, `_`, or `-`).

Response

{
  "username": "system-user",
  "password": "generated-password",
  "enabled": true,
  "role": [
    "ROLE_USER"
  ],
  "applications": []
}

Attribute	Type	Description
`username`*	String	Username used to sign in.
`password`*	String	Generated password for the new user.
`enabled`*	Boolean	Whether the user is enabled to authenticate.
`role`*	String[]	Roles assigned to the user, such as `ROLE_USER`.
`applications`*	String[]	IDs of applications the user can access.

get admin/users/{username} Get User Details

Obtain details of a system user.

Request

Path Params

Param	Type	Description
`username`*	String	Username of the user whose details are requested.

Response

{
  "username": "system-user",
  "enabled": true,
  "role": [
    "ROLE_USER"
  ],
  "applications": [
    "MY_APP_01"
  ]
}

This endpoint does not return the user’s password.

Attribute	Type	Description
`username`*	String	Username used to sign in.
`enabled`*	Boolean	Whether the user is enabled to authenticate.
`role`*	String[]	Roles assigned to the user, such as `ROLE_USER`.
`applications`*	String[]	IDs of applications the user can access.

put admin/users/{username} Update User

Enable or disable a system user. An administrator cannot update their own account through this endpoint.

Request

Path Params

Param	Type	Description
`username`*	String	Username of the user to update.

{
  "enabled": false
}

Attribute	Type	Description
`enabled`*	Boolean	Whether the user should be enabled to authenticate.

Response

Returns the updated user details:

{
  "username": "system-user",
  "enabled": false,
  "role": [
    "ROLE_USER"
  ],
  "applications": []
}

This endpoint does not return the user’s password.

Attribute	Type	Description
`username`*	String	Username used to sign in.
`enabled`*	Boolean	Whether the user is enabled to authenticate.
`role`*	String[]	Roles assigned to the user, such as `ROLE_USER`.
`applications`*	String[]	IDs of applications the user can access.

delete admin/users/{username} Delete User

Delete a system user. An administrator cannot delete their own account through this endpoint to prevent lockout.

Request

Path Params

Param	Type	Description
`username`*	String	Username of the user to delete.

Response

{
  "status": "OK"
}

Attribute	Type	Description
`status`*	String	Fixed value `OK`.

post admin/users/{username}/roles Add Roles to User

Add one or more roles to a system user. Supported roles are ROLE_USER and ROLE_ADMIN.

Request

Path Params

Param	Type	Description
`username`*	String	Username of the user whose roles are updated.

{
  "roles": [
    "ROLE_ADMIN"
  ]
}

Attribute	Type	Description
`roles`*	String[]	Non-empty list of roles to add; each must be `ROLE_USER` or `ROLE_ADMIN`.

Response

Returns the updated user details:

{
  "username": "system-user",
  "enabled": true,
  "role": [
    "ROLE_USER",
    "ROLE_ADMIN"
  ],
  "applications": []
}

This endpoint does not return the user’s password.

Attribute	Type	Description
`username`*	String	Username used to sign in.
`enabled`*	Boolean	Whether the user is enabled to authenticate.
`role`*	String[]	Roles assigned to the user.
`applications`*	String[]	IDs of applications the user can access.

post admin/users/{username}/roles/remove Remove Roles from User

Remove one or more roles from a system user. Supported roles are ROLE_USER and ROLE_ADMIN.

Request

Path Params

Param	Type	Description
`username`*	String	Username of the user whose roles are updated.

{
  "roles": [
    "ROLE_ADMIN"
  ]
}

Attribute	Type	Description
`roles`*	String[]	Non-empty list of roles to remove; each must be `ROLE_USER` or `ROLE_ADMIN`.

Response

{
  "status": "OK"
}

Attribute	Type	Description
`status`*	String	Fixed value `OK`.

post admin/users/{username}/applications/{appId} Add Application Access to User

Grant a system user access to an application.

Request

Path Params

Param	Type	Description
`username`*	String	Username of the user whose access is changed.
`appId`*	String	ID of an existing application to grant access to.

Response

Returns the updated user details:

{
  "username": "system-user",
  "enabled": true,
  "role": [
    "ROLE_USER"
  ],
  "applications": [
    "MY_APP_01"
  ]
}

This endpoint does not return the user’s password.

Attribute	Type	Description
`username`*	String	Username used to sign in.
`enabled`*	Boolean	Whether the user is enabled to authenticate.
`role`*	String[]	Roles assigned to the user.
`applications`*	String[]	IDs of applications the user can access.

delete admin/users/{username}/applications/{appId} Remove Application Access from User

Revoke a system user’s access to an application.

Request

Path Params

Param	Type	Description
`username`*	String	Username of the user whose access is changed.
`appId`*	String	Application ID whose access is revoked.

Response

{
  "status": "OK"
}

Attribute	Type	Description
`status`*	String	Fixed value `OK`.

post admin/users/{username}/password/reset Reset User Password

Generate a new random password for a system user. The generated password is returned in the response. An administrator cannot reset their own password through this endpoint to prevent lockout. In this case, update the administrator’s credentials using the database configuration instead.

Request

Path Params

Param	Type	Description
`username`*	String	Username of the user whose password is reset.

Response

{
  "username": "system-user",
  "password": "generated-password"
}

Attribute	Type	Description
`username`*	String	Username whose password was reset.
`password`*	String	Newly generated 24-character alphanumeric password.

Telemetry Services

PowerAuth Cloud allows querying statistics about the PowerAuth system usage.

get admin/telemetry/applications/{id}/users Fetch Number of Unique Active Users

Fetch number of unique active users of an application in specified number of days from the past until today.

Request

Path Params

Param	Type	Description
`id`*	`String`	ID of the application to query.

Query Params

Param	Type	Description
`days`	`Integer`	Number of days from the past until today for which the statistics will be built. Defaults to 30.

Response

{
  "applicationId": "MyApp",
  "days": 7,
  "users": 42
}

Attribute	Type	Description
`applicationId`*	`String`	The ID of the queried application.
`days`*	`Integer`	The number of days from the past until today.
`users`*	`Long`	The number of unique active users.

Invalid username or password was provided while calling the service.

{
  "status": "ERROR",
  "responseObject": {
    "code": "HTTP_401",
    "message": "Unauthorized"
  }
}

Error occurred while calling the internal service. This can happen as a result of misconfiguration. Check your deployment configuration for errors.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_INTERNAL_API",
    "message": "Unable to call upstream service"
  }
}

Last updated on Oct 06, 2026 (09:03) View product