Select release
On this page:

Mobile Token API

Edit on Github Send Feedback v1.5.1

Enrollment Server provides a RESTful API used by the Mobile Token application.

The generated REST API documentation in deployed Enrollment server, and it includes standard PowerAuth RESTful API:

http[s]://[host]:[port]/enrollment-server/swagger-ui.html

Following endpoints are published in Enrollment Server RESTful API:

Error Handling

Enrollment Server uses following format for error response body, accompanied by an appropriate HTTP status code. Besides the HTTP error codes that application server may return regardless of server application (such as 404 when resource is not found or 503 when server is down), following status codes may be returned:

Status HTTP Code Description
OK 200 No issue
ERROR 400 Issue with a request format, or issue of the business logic
ERROR 401 Unauthorized

All error responses that are produced by the Enrollment Server have the following body:


{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_GENERIC",
    "message": "An error message"
  }
}
  • status - OK, ERROR
  • code - ERROR_GENERIC
  • message - Message that describes certain error.

Mobile Token API for Operations

Mobile token API provides access to operations.

Mobile API Error Codes

List of error codes in Mobile Token API:

Code Description HTTP Status Code
INVALID_REQUEST Invalid request sent - missing request object in request 400
INVALID_ACTIVATION Activation is not valid (it is different from configured activation). Return this error in case the activation does not exist, or in case the activation is not allowed to perform the action (for example, user did not allow operation approvals on such device). 400
POWERAUTH_AUTH_FAIL PowerAuth authentication failed 401
OPERATION_ALREADY_FINISHED Operation is already finished 400
OPERATION_ALREADY_FAILED Operation is already failed 400
OPERATION_ALREADY_CANCELED Operation is already canceled 400
OPERATION_EXPIRED Operation is expired 400

Localization

In order to get a correctly localized response, use the Accept-Language HTTP header in your request.

post /api/auth/token/app/operation/list Get Pending Operations

Get the list with all operations that are pending confirmation.

Request

  • Headers:
    • Content-Type: application/json
    • Accept-Language: en-US
    • X-PowerAuth-Authorization: ...
{}

Response

{
  "status": "OK",
  "responseObject": [
    {
      "id": "7e0ba60f-bf22-4ff5-b999-2733784e5eaa",
      "name": "authorize_payment",
      "data": "A1*A100CZK*Q238400856/0300**D20190629*NUtility Bill Payment - 05/2019",
      "status": "PENDING",
      "operationCreated": "2018-07-02T14:43:13+0000",
      "operationExpires": "2018-07-02T14:48:17+0000",
      "allowedSignatureType": {
        "type": "2FA",
        "variants": [
          "possession_knowledge",
          "possession_biometry"
        ]
      },
      "formData": {
        "title": "Confirm Payment",
        "message": "Hello,\nplease confirm following payment:",
        "attributes": [
          {
            "type": "ALERT",
            "alertType": "WARNING",
            "id": "operation.warning",
            "label": "Balance alert",
            "title": "Insufficient Balance",
            "message": "You have only $1.00 on your account with number 238400856/0300."
          },
          {
            "type": "HEADING",
            "id": "operation.heading",
            "label": "Utility Payment"
          },
          {
            "type": "AMOUNT",
            "id": "operation.amount",
            "label": "Amount",
            "amount": 2199.40,
            "currency": "CZK",
            "amountFormatted": "2199,40",
            "currencyFormatted": "Kč"
          },
          {
            "type": "AMOUNT_CONVERSION",
            "id": "operation.conversion",
            "label": "Conversion Rate",
            "dynamic": false,
            "sourceAmount": 100.00,
            "sourceCurrency": "USD",
            "sourceAmountFormatted": "100.00",
            "sourceCurrencyFormatted": "$",
            "sourceValueFormatted": "$100.00",
            "targetAmount": 2199.40,
            "targetCurrency": "CZK",
            "targetAmountFormatted": "2199,40",
            "targetCurrencyFormatted": "Kč",
            "targetValueFormatted": "2199,40 Kč"
          },
          {
            "type": "KEY_VALUE",
            "id": "operation.account",
            "label": "To Account",
            "value": "238400856/0300"
          },
          {
            "type": "KEY_VALUE",
            "id": "operation.dueDate",
            "label": "Due Date",
            "value": "Jun 29, 2019"
          },
          {
            "type": "NOTE",
            "id": "operation.note",
            "label": "Note",
            "note": "Utility Bill Payment - 05/2019"
          },
          {
            "type": "IMAGE",
            "id": "operation.image",
            "label": "Payment Check Preview",
            "thumbnailUrl": "https://example.com/thumbnail.png",
            "originalUrl": "https://example.com/image.png"
          },
          {
            "type": "PARTY_INFO",
            "id": "operation.partyInfo",
            "label": "Application",
            "partyInfo": {
              "logoUrl": "https://itesco.cz/img/logo/logo.svg",
              "name": "Tesco",
              "description": "Find out more about Tesco...",
              "websiteUrl": "https://itesco.cz/hello"
            }
          }
        ]
      }
    }
  ]
}

post /api/auth/token/app/operation/history Get History of Operations

Get the list of confirmed or rejected Mobile Token operations.

Request

  • Headers:
    • Content-Type: application/json
    • Accept-Language: en-US
    • X-PowerAuth-Authorization: ...
{}

Response

{
  "status": "OK",
  "responseObject": [
    {
      "id": "7e0ba60f-bf22-4ff5-b999-2733784e5eaa",
      "name": "authorize_payment",
      "data": "A1*A100CZK*Q238400856/0300**D20190629*NUtility Bill Payment - 05/2019",
      "status": "APPROVED",
      "operationCreated": "2018-07-02T14:43:13+0000",
      "operationExpires": "2018-07-02T14:48:17+0000",
      "allowedSignatureType": {
        "type": "2FA",
        "variants": [
          "possession_knowledge",
          "possession_biometry"
        ]
      },
      "formData": {
        "title": "Confirm Payment",
        "message": "Hello,\nplease confirm following payment:",
        "attributes": [
          {
            "type": "ALERT",
            "alertType": "WARNING",
            "id": "operation.warning",
            "label": "Balance alert",
            "title": "Insufficient Balance",
            "message": "You have only $1.00 on your account with number 238400856/0300."
          },
          {
            "type": "HEADING",
            "id": "operation.heading",
            "label": "Utility Payment"
          },
          {
            "type": "AMOUNT",
            "id": "operation.amount",
            "label": "Amount",
            "amount": 2199.40,
            "currency": "CZK",
            "amountFormatted": "2199,40",
            "currencyFormatted": "Kč"
          },
          {
            "type": "AMOUNT_CONVERSION",
            "id": "operation.conversion",
            "label": "Conversion Rate",
            "dynamic": false,
            "sourceAmount": 100.00,
            "sourceCurrency": "USD",
            "sourceAmountFormatted": "100.00",
            "sourceCurrencyFormatted": "$",
            "sourceValueFormatted": "$100.00",
            "targetAmount": 2199.40,
            "targetCurrency": "CZK",
            "targetAmountFormatted": "2199,40",
            "targetCurrencyFormatted": "Kč",
            "targetValueFormatted": "2199,40 Kč"
          },
          {
            "type": "KEY_VALUE",
            "id": "operation.account",
            "label": "To Account",
            "value": "238400856/0300"
          },
          {
            "type": "KEY_VALUE",
            "id": "operation.dueDate",
            "label": "Due Date",
            "value": "Jun 29, 2019"
          },
          {
            "type": "NOTE",
            "id": "operation.note",
            "label": "Note",
            "note": "Utility Bill Payment - 05/2019"
          },
          {
            "type": "IMAGE",
            "id": "operation.image",
            "label": "Payment Check Preview",
            "thumbnailUrl": "https://example.com/thumbnail.png",
            "originalUrl": "https://example.com/image.png"
          },
          {
            "type": "PARTY_INFO",
            "id": "operation.partyInfo",
            "label": "Application",
            "partyInfo": {
              "logoUrl": "https://itesco.cz/img/logo/logo.svg",
              "name": "Tesco",
              "description": "Find out more about Tesco...",
              "websiteUrl": "https://itesco.cz/hello"
            }
          }
        ]
      }
    }
  ]
}

post /api/auth/token/app/operation/authorize Confirm Operation

Confirms an operation with given ID and data. This endpoint requires a signature of a type specified by the operation.

Request

  • Headers:
    • Content-Type: application/json
    • X-PowerAuth-Authorization: ...
{
  "requestObject": {
    "id": "3699a9c0-45f0-458d-84bc-5bde7ec384f7",
    "data": "A1*A100CZK*Q238400856\/0300**D20190629*NUtility Bill Payment - 05\/2019"
  }
}

Response

{
  "status": "OK"
}

post /api/auth/token/app/operation/cancel Reject Operation

Reject an operation with given ID, with a provided reason.

Request

  • Headers:
    • Content-Type: application/json
    • X-PowerAuth-Authorization: ...
{
  "requestObject": {
    "id": "352d6cfa-b8d7-4366-af1f-c99b071b4dc4",
    "reason": "INCORRECT_DATA"
  }
}

Response

{
  "status": "OK"
}

Enumerations

Form Attribute Types

Type Description
AMOUNT Form field representing an amount with currency.
AMOUNT_CONVERSION Form field representing a conversion between amounts.
KEY_VALUE Form field representing a key value item with single-line value.
NOTE Form field representing a generic text note with multi-line value.
HEADING Form field representing a heading, where label is displayed as the heading text.
ALERT Form field representing a alert with success, info, warning or error states.
PARTY_INFO Form field representing a structured object with information about a third party.
IMAGE Form field representing an image.

Operation Rejection Reasons

Type Description
UNKNOWN User decided not to tell us the operation rejection reason.
INCORRECT_DATA User claims incorrect data was presented in mToken app.
UNEXPECTED_OPERATION User claims he/she did not expect any operation.

Allowed Signature Types

Type Description
1FA One-factor signature - user just has to tap “Confirm” button to confirm it.
2FA Two-factor signature - user needs to use either password of biometry as addition to possession factor. The variants key then determines what signature type is allowed for the given operation.
ECDSA ECDSA signature with device private key.

Mobile Push Registration API

In order to register mobile device to the push notifications, following endpoints are published.

post /api/push/device/register Register for Push Messages (Signed)

Registers a device to push notifications. Authorization is done using PowerAuth signature.

Request

  • Headers:
    • Content-Type: application/json
    • X-PowerAuth-Authorization: ...
{
  "requestObject": {
    "platform": "ios",
    "token": "10de0b9c-791f-4e9f-93c4-e2203951c307"
  }
}

Supported platforms:

  • ios
  • android

Response

{
  "status": "OK"
}

{
    "status": "ERROR",
    "responseObject": {
        "code": "PUSH_REGISTRATION_FAILED",
        "message": "Push registration failed in Mobile Token API component."
    }
}

Possible error codes:

  • PUSH_REGISTRATION_FAILED - returned when Push Server returns error during registration.
  • INVALID_REQUEST - returned when request object is invalid.
  • INVALID_ACTIVATION - returned when application or activation is invalid.

Returned when PowerAuth authentication fails.

{
  "status": "ERROR",
  "responseObject": {
    "code": "POWERAUTH_AUTH_FAIL",
    "message": "Unable to verify device registration"
  }
}

post /api/push/device/register/token Register for Push Messages (Token)

Registers a device to push notifications. Authorization is done using PowerAuth token.

Request

  • Headers:
    • Content-Type: application/json
    • X-PowerAuth-Token: ...
{
  "requestObject": {
    "platform": "ios",
    "token": "10de0b9c-791f-4e9f-93c4-e2203951c307"
  }
}

Supported platforms:

  • ios
  • android

Response

{
  "status": "OK"
}

{
    "status": "ERROR",
    "responseObject": {
        "code": "PUSH_REGISTRATION_FAILED",
        "message": "Push registration failed in Mobile Token API component."
    }
}

Possible error codes:

  • PUSH_REGISTRATION_FAILED - returned when Push Server returns error during registration.
  • INVALID_REQUEST - returned when request object is invalid.
  • INVALID_ACTIVATION - returned when application or activation is invalid.

Returned when PowerAuth authentication fails.

{
  "status": "ERROR",
  "responseObject": {
    "code": "POWERAUTH_AUTH_FAIL",
    "message": "Unable to verify device registration"
  }
}

Activation Spawn

Activation Spawn API contains a single endpoint which is used for requesting the activation code.

post /api/activation/code Activation Code

Handle a request for activation code in activation spawn.

Request

  • Headers:
    • Content-Type: application/json
    • X-PowerAuth-Authorization: ...
{
  "requestObject": {
    "applicationId": "app1",
    "otp": "12345678"
  }
}

Response

{
  "status": "OK"
}

Message Inbox

Message Inbox API provides endpoints for managing the message inbox.

post /api/inbox/count Inbox Message Count

Get count of unread messages in Inbox.

Request

  • Headers:
    • Content-Type: application/json
    • X-PowerAuth-Token: ...
{}

Response

{
  "status": "OK",
  "responseObject": {
    "countUnread": 10
  }
}

post /api/inbox/message/list Inbox Message List

Get messages in Inbox.

Request

  • Headers:
    • Content-Type: application/json
    • X-PowerAuth-Token: ...
{
  "requestObject": {
    "page": 0,
    "size": 10,
    "onlyUnread": false
  }
}

Response

{
  "status": "OK",
  "responseObject": [
    {
      "id": "ae641389-d37a-4425-bd14-41c29484596f",
      "type": "text",
      "subject": "Example subject",
      "summary": "Example summary",
      "read": false,
      "timestampCreated": "2022-08-25T22:34:58.702+00:00"
    }
  ]
}

post /api/inbox/message/detail Inbox Message Detail

Get detail of a message in Inbox.

Request

  • Headers:
    • Content-Type: application/json
    • X-PowerAuth-Token: ...
{
  "requestObject": {
    "id": "ae641389-d37a-4425-bd14-41c29484596f"
  }
}

Response

{
  "status": "OK",
  "responseObject": [
    {
      "id": "ae641389-d37a-4425-bd14-41c29484596f",
      "type": "text",
      "subject": "Example subject",
      "summary": "Example summary",
      "body": "Example message body",
      "read": false,
      "timestampCreated": "2022-08-25T22:34:58.702+00:00"
    }
  ]
}

post /api/inbox/message/read Inbox Message Read

Mark a message in inbox as read.

Request

  • Headers:
    • Content-Type: application/json
    • X-PowerAuth-Token: ...
{
  "requestObject": {
    "id": "ae641389-d37a-4425-bd14-41c29484596f"
  }
}

Response

{
  "status": "OK"
}

post /api/inbox/message/read-all Inbox Message Read All

Mark all messages in inbox as read.

Request

  • Headers:
    • Content-Type: application/json
    • X-PowerAuth-Token: ...
{}

Response

{
  "status": "OK"
}
Last updated on May 19, 2023 (14:05) Edit on Github Send Feedback
Search

1.5.x

Enrollment Server