Public RESTful API

Mobile Utility Server publishes comprehensive RESTful API with all endpoints required by a mobile app:

Swagger Documentation

Application publishes a Swagger UI documentation at the /swagger-ui.html path with up-to-date information about published endpoints.

Error Handling

REST API returns errors in a unified format:

{
    "code": "${ERROR_CODE}",
    "message": "${ERROR_MESSAGE}"
}
attribute Description
code Unique code of an error, represents the error type.
message Description of an error with additional details.

Published Resources

Get App Public Key

Method to obtain the public key for a provided application ID. You should obtain this key manually and include it in your application. Do not download the key from the mobile application directly, since MITM attack is possible.

Request GET /app/init/public-key?appName=${name}

Query Param Description
appName Name of the application.

Response

Returns the public key in case of the success, or a standardized error output in the case of an error.

200 OK

In the case of a success.

{
  "publicKey": "BCeNRoRsy2KjIk7J...cp0="
}
Response Attribute Description
publicKey The signature public key for a given application.
400 Bad Request

In case of any generic error.

{
  "id": "${ERROR_ID}",
  "code": "${ERROR_CODE}",
  "message": "${ERROR_MESSAGE}"
}
404 Not Found

In case application with given name is not found.

{
  "code": "PUBLIC_KEY_NOT_FOUND",
  "message": "Public key for the provided app name was not found."
}

Get App Fingerprints

Method to obtain the fingerprints of the certificates that are pinned in the app for a provided application ID. Optionally also verify whether the mobile application version is up-to-date or whether it should or must be updated.

Request GET /app/init?appName=${name}&appVersion=${appVersion}&osVersion=${osVersion}&platform=${platform}

Header Description
X-Cert-Pinning-Challenge Random challenge that is included in the response signature calculation. It must be at least 16 bytes long.
Query Param Description
appName Name of the application.
appVersion Application version in SemVer 2.0 format but only MAJOR.MINOR.PATCH are taken into account. (Optional, but needed for version verification.)
osVersion Operation system version, e.g. ‘31’ for Android or ‘14.5.1’ for iOS. (Optional, but needed for version verification.)
platfrom Platform: ANDROID, IOS (Optional, but needed for version verification.)

Response

Returns the list of fingerprints in case of the success together with optional result of version verification, or a standardized error output in the case of an error.

200 OK

In the case of a successful call.

{
  "timestamp": 1604853448,
  "fingerprints": [
    {
      "name": "test1.wultra.com",
      "fingerprint": "/+zwSJh7....wo7s=",
      "expires": 1627214400
    },
    {
      "name": "test2.wultra.com",
      "fingerprint": "fj8iVdqu....vCig=",
      "expires": 1603108800
    }
  ],
  "verifyVersionResult": {
    "update": "NOT_REQUIRED"
  }
}
Header Description
X-Cert-Pinning-Signature Base64 value of an encoded response signature. The signature contains the response challenge as well as full response data, and it must be validated on the client side before the client accepts the response.
Response Attribute Description
timestamp The current timestamp on the server side.
fingerprints Array with the TLS/SSL certificate signatures.
fingerprints.name Name of the domain, for example, test1.wultra.com.
fingerprints.fingerprint The value of the certificate/public key fingerprint.
fingerprints.expires Unix timestamp (seconds since Jan 01, 1970) of the pinned certificate expiration.
verifyVersionResult.update The update status of the mobile application version. Possible values: NOT_REQUIRED, SUGGESTED, FORCED.
verifyVersionResult.message Optional localized message, should be filled when the update status is SUGGESTED or FORCED.
400 Bad Request

In case of any generic error.

{
    "id": "${ERROR_ID}",
    "code": "${ERROR_CODE}",
    "message": "${ERROR_MESSAGE}"
}
403 Unauthorized

Returned if the challenge was missing, or if provided challenge was insufficient.

{
    "id": "93121111-1111-1111-1111-1111e8645505",
    "code": "INSUFFICIENT_CHALLENGE",
    "message": "Request does not contain sufficiently strong challenge header, 16B is required at least."
}
404 Not Found

In case application with given name is not found.

{
    "id": "717e1111-1111-1111-1111-1111c53fe0da",
    "code": "PUBLIC_KEY_NOT_FOUND",
    "message": "Public key for the provided app name was not found."
}
Last updated on Aug 22, 2023 (12:38) Edit on Github Send Feedback
Search

1.7.x

Mobile Utility Server