Authentication Services

View product v1.8.2

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.