Authentication Services

The Authentication Services of PowerAuth provide services for simplifying signature and token verification.

Possible Error Codes

Error Code HTTP Status Code Description
ERROR_SIGNATURE_INVALID 400 Indicates that the signature HTTP header is invalid. This occurs when signature verification for online approvals fails due to incorrect or malformed signature details.
ERROR_TOKEN_INVALID 400 Indicates that the token HTTP header is invalid or that an unsupported protocol version was used. This occurs when token verification fails due to incorrect or malformed token details.
HTTP_401 401 Unauthorized access attempt. This occurs when invalid credentials are provided.
ERROR_INTERNAL_API 500 An internal server error occurred, potentially due to misconfiguration. Check your deployment configuration for errors.

Services

post /v2/signature/verify Verify Signature (Online Approval)

Verify PowerAuth signature for online operation approval. This endpoint simplifies signature verification by using the PowerAuth authentication header received from the mobile application together with HTTP request parameters: HTTP method, resource URI and request body / query parameters.

Request

Request Params
{
  "method": "$HTTP_METHOD",
  "uriId": "$RESOURCE_URI",
  "authHeader": "$POWERAUTH_HEADER",
  "requestBody": "$REQUEST_BODY_BASE64",
  "queryParams": {
    "param1": "$PARAM1",
    "param2": "$PARAM2",
    "param3": "$PARAM3"
  }
}
Attribute Type Description
method* String HTTP method: GET, POST, PUT, or DELETE.
uriId* String Resource URI of the endpoint used for signature verification, e.g. /pa/signature/validate.
authHeader* String PowerAuth authentication header in format PowerAuth pa_activation_id=\"$ACTIVATION_ID\", pa_application_key=\"$APPLICATION_KEY\", pa_nonce=\"$NONCE\", pa_signature_type=\"$SIGNATURE_TYPE\", pa_signature=\"$SIGNATURE\", pa_version=\"$VERSION\".
requestBody String Base64-encoded request body for POST, PUT, and DELETE HTTP methods. Use null value for GET HTTP method.
queryParams String Query parameters for the GET HTTP method as a map. The map keys should be unique and the values should not be URL-encoded, sensitive characters should be escaped using regular JSON normalization syntax. Use null value for for POST, PUT, and DELETE HTTP methods.

Response

{
  "signatureValid": true,
  "userId": "test-user",
  "registrationId": "b4c73d24-050f-4aaa-9fab-bda401079879",
  "registrationStatus": "ACTIVE",
  "signatureType": "POSSESSION_KNOWLEDGE",
  "remainingAttempts": 5,
  "flags": [
    "FLAG1"
  ],
  "application": {
    "name": "APP1",
    "roles": [
      "ROLE1"
    ]
  }
}
Attribute Type Description
signatureValid* boolean Whether signature verification succeeded.
userId* String Identifier of user who requested the signature verification.
registrationId* String Identifier of registration used when verifying the signature.
registrationStatus* String Registration status.
signatureType* String PowerAuth signature type.
remainingAttempts* Long Number of remaining attempts for signature verification.
flags* String[] Registration flags.
application.name* String Application name.
application.roles* String[] Assigned application roles.

Signature verification for online approvals failed due to a business logic problem.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_SIGNATURE_INVALID",
    "message": "Signature HTTP header validation failed"
  }
}

Possible error states are:

  • ERROR_SIGNATURE_INVALID - Signature HTTP header is 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"
  }
}

post /v2/token/verify Verify PowerAuth Token

Verify PowerAuth token digest. This endpoint simplifies token verification by using the PowerAuth authentication header received from the mobile application.

Request

Request Params
{
  "authHeader": "$POWERAUTH_HEADER"
}
Attribute Type Description
authHeader* String PowerAuth authentication header in format PowerAuth token_id=\"$TOKEN_ID\", token_digest=\"$TOKEN_DIGEST\", nonce=\"$NONCE\", timestamp=\"$TIMESTAMP\", pa_version=\"$VERSION\".

Response

{
  "tokenValid": true,
  "userId": "test-user",
  "registrationId": "b4c73d24-050f-4aaa-9fab-bda401079879",
  "registrationStatus": "ACTIVE",
  "signatureType": "POSSESSION_KNOWLEDGE",
  "flags": [
    "FLAG1"
  ],
  "application": {
    "name": "APP1",
    "roles": [
      "ROLE1"
    ]
  }
}
Attribute Type Description
tokenValid* boolean Whether token verification succeeded.
userId* String Identifier of user who requested the signature verification.
registrationId* String Identifier of registration used when verifying the signature.
registrationStatus* String Registration status.
signatureType* String PowerAuth signature type.
flags* String[] Registration flags.
application.name* String Application name.
application.roles* String[] Assigned application roles.

Signature verification for online approvals failed due to a business logic problem.

{
  "status": "ERROR",
  "responseObject": {
    "code": "ERROR_TOKEN_INVALID",
    "message": "Token HTTP header validation failed"
  }
}

Possible error states are:

  • ERROR_TOKEN_INVALID - Token HTTP header is invalid or unsupported protocol version.

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"
  }
}
Last updated on Apr 30, 2024 (09:55) View product
Search

1.8.x

PowerAuth Cloud