Mobile Token API

Mobile token API provides access to operations.

The generated REST API documentation in deployed Web Flow:

http[s]://[host]:[port]/powerauth-webflow/swagger-ui.html

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, please use the Accept-Language HTTP header in your request.

Mobile Token API Endpoints

Get Pending Operations

Get the list with all operations that are pending confirmation.

Method	`POST`
Resource URI	`/api/auth/token/app/operation/list`

Request

Headers:
- Content-Type: application/json
- Accept-Language: en-US
- X-PowerAuth-Token: ...

{}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status": "OK",
  "responseObject": [
    {
      "id": "7e0ba60f-bf22-4ff5-b999-2733784e5eaa",
      "name": "authorize_payment",
      "data": "A1*A100CZK*Q238400856/0300**D20190629*NUtility Bill Payment - 05/2019",
      "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": "HEADING",
            "id": "operation.heading",
            "label": "Utility Payment"
          },
          {
            "type": "AMOUNT",
            "id": "operation.amount",
            "label": "Amount",
            "amount": 100,
            "currency": "CZK",
            "amountFormatted": "100,00",
            "currencyFormatted": "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": "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"
            }
          }
        ]
      }
    }
  ]
}

Confirm Operation

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

Method	`POST`
Resource URI	`/api/auth/token/app/operation/authorize`

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 Code: 200
Headers:
- Content-Type: application/json

{
  "status": "OK"
}

Reject Operation

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

Method	`POST`
Resource URI	`/api/auth/token/app/operation/cancel`

Request

Headers:
- Content-Type: application/json
- X-PowerAuth-Authorization: ...

{
  "requestObject": {
    "id": "352d6cfa-b8d7-4366-af1f-c99b071b4dc4",
    "reason": "INCORRECT_DATA"
  }
}

Response

Status Code: 200
Headers:
- Content-Type: application/json

{
  "status": "OK"
}

Enumerations

Form Attribute Types

Type	Description
`AMOUNT`	Form field representing an amount with currency.
`KEY_VALUE`	Form field representing a key value item, where items are displayed next to each other. This realistically impose limitation on value length - it should fit into the single line.
`NOTE`	Form field representing a generic text note, where label is displayed above the note. As a result, note can be of an arbitrary length and can be multi-line.
`HEADING`	Form field representing a heading, where label is displayed as the heading text.
`PARTY_INFO`	Form field representing a structured object with information about a third party.

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.

Last updated on Jun 15, 2020 (13:11) Edit on Github Send Feedback