Select release
On this page:

Authentication Services

View product develop

The Passkeys Services of PowerAuth provide integration of WebAuthN standard into PowerAuth for FIDO2 authenticators. Registration and authentication ceremonies are supported by this REST API.

Possible Error Codes

HTTP Error Code Description
400 ERROR_FIDO2 Error related to failed FIDO2 registration or assertions.
400 ERROR_HTTP_REQUEST Request did not pass validation (mandatory property missing, null/invalid value).
401 ERROR_UNAUTHORIZED Returned in the case authentication fails (invalid application credentials).
404 ERROR_NOT_FOUND Returned in the case URL is not present (calling wrong API).

Registration Services

post /v2/fido2/registrations/list List Registered Authenticators

Obtain a list of registered FIDO2 authenticators for specified user.

FIDO2 authenticators are backed by PowerAuth registrations.

Request

Query Params
Param Type Description
userId* String ID of the user for whom the registration list is being retrieved.
appId* String Application for which the authenticators should be returned.

Response

List of authenticators for provided user and application.

{
  "status": "string",
  "responseObject": {
    "authenticators": [
      {
        "userId": "string",
        "registrationId": "string",
        "appId": "string",
        "registrationName": "string",
        "credentialId": "string",
        "registrationStatus": "CREATED",
        "extras": {
          "additionalProp1": {},
          "additionalProp2": {},
          "additionalProp3": {}
        },
        "platform": "string",
        "deviceInfo": "string",
        "blockedReason": "string",
        "failedAttempts": 0,
        "maxFailedAttempts": 0,
        "applicationRoles": [
          "string"
        ],
        "registrationFlags": [
          "string"
        ],
        "publicKeyBytes": "string"
      }
    ]
  }
}
Description of Response Params
Attribute Type Description
userId String User ID associated with the authenticator.
registrationId String Registration ID.
appId String Application associated with the authenticator.
registrationName String Registration name.
credentialId String Credential ID (FIDO2 Authenticator ID).
registrationStatus String The registration status.
extras String Associated authenticator data.
platform String Type of FIDO2 authenticator (platform, cross-platform).
deviceInfo String Authenticator model info (vendor, type).
blockedReason String If blocked, the value contains reason for blocking.
failedAttempts Long How many approvals failed.
maxFailedAttempts Long Maximum allowed count of approval failures.
applicationRoles String[] Application roles.
registrationFlags String[] Registration flags.
publicKeyBytes String Authenticator public key, encoded as Base64.

post /v2/fido2/registrations/challenge Generate a Registration Challenge

Generate a FIDO2 registration challenge for specified user. See WebAuth for full registration process

FIDO2 authenticators are backed by PowerAuth registrations.

Request

{
  "requestObject": {
    "userId": "string",
    "appId": "string"
  }
}
Request Params
Attribute Type Description
userId* String User for which the challenge should be prepared.
appId* String Application for which the challenge should be prepared.

Response

Challenge for new FIDO2 authenticator registration.

{
  "status": "string",
  "responseObject": {
    "registrationId": "string",
    "appId": "string",
    "challenge": "string",
    "userId": "string",
    "excludeCredentials": [
      {
        "credentialId": "string",
        "type": "string",
        "transports": [
          "string"
        ]
      }
    ]
  }
}
Description of Response Params
Attribute Type Description
userId String User ID associated with the authenticator.
registrationId String Registration ID.
appId String Application associated with the authenticator.
challenge String FIDO2 registration challenge.
excludeCredentials List List of credentials that should be excluded from a registration ceremony. E.g., authenticators are already registered for the user.

post /v2/fido2/registrations Register an Authenticator

Register a FIDO2 authenticator based on a registration request generated and signed by the authenticator. See WebAuth for full registration process

FIDO2 authenticators are backed by PowerAuth registrations.

Request

{
  "requestObject": {
    "appId": "string",
    "registrationName": "string",
    "expectedChallenge": "string",
    "authenticatorParameters": {
      "id": "string",
      "type": "string",
      "authenticatorAttachment": "string",
      "response": "...",
      "relyingPartyId": "string",
      "allowedOrigins": [
        "string"
      ],
      "allowedTopOrigins": [
        "string"
      ],
      "requiresUserVerification": true
    }
  }
}
Request Params
Attribute Type Description
appId* String Application for which the challenge should be prepared.
registrationName* String Name of the registration.
expectedChallenge String Expected challenge value. If present, it is checked against the actual challenge.
authenticatorParameters AuthenticatorParameters Parameters of the registered authenticator.
AuthenticatorParameters Object
Attribute Type Description
credentialId* String Credential ID.
type* String Credential type (public-key).
authenticatorAttachment* String Information about authenticator attachment.
response* String Authenticator response (value provided by authenticator, encoded as Base64).
relyingPartyId String Identification of relying party, typically the domain, i.e., example.com.
allowedOrigins String[] Collection of origins that should be allowed to provide the assertion.
allowedTopOrigins String[] Collection of top origins that should be allowed to provide the assertion.
requiresUserVerification boolean Information if user verification flag must be present (if user was verified).

Response

A new FIDO2 authenticator registration.

{
  "status": "string",
  "responseObject": {
    "userId": "string",
    "registrationId": "string",
    "appId": "string",
    "registrationName": "string",
    "credentialId": "string",
    "registrationStatus": "ACTIVE",
    "extras": {
      "additionalProp1": {},
      "additionalProp2": {},
      "additionalProp3": {}
    },
    "platform": "string",
    "deviceInfo": "string",
    "blockedReason": "string",
    "failedAttempts": 0,
    "maxFailedAttempts": 0,
    "applicationRoles": [
      "string"
    ],
    "registrationFlags": [
      "string"
    ],
    "publicKeyBytes": "string"
  }
}
Description of Response Params
Attribute Type Description
userId String User ID associated with the authenticator.
registrationId String Registration ID.
appId String Application associated with the authenticator.
registrationName String Registration name.
credentialId String Credential ID (FIDO2 Authenticator ID).
registrationStatus String The registration status.
extras String Associated authenticator data.
platform String Type of FIDO2 authenticator (platform, cross-platform).
deviceInfo String Authenticator model info (vendor, type).
blockedReason String If blocked, the value contains reason for blocking.
failedAttempts Long How many approvals failed.
maxFailedAttempts Long Maximum allowed count of approval failures.
applicationRoles String[] Application roles.
registrationFlags String[] Registration flags.
publicKeyBytes String Authenticator public key, encoded as Base64.

Assertion Services

post /v2/fido2/assertions/challenge Create a FIDO2 Assertion Challenge

Request a new FIDO2 assertion challenge.

FIDO2 assertions are backed by PowerAuth operations. This allows you to use templates and template parameters.

Request

{
  "requestObject": {
    "appIds": [
      "string"
    ],
    "userId": "string",
    "externalId": "string",
    "templateName": "string",
    "operationId": "string",
    "parameters": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    }
  }
}
Request Params
Attribute Type Description
appIds* String[] Applications that are capable of approving the operation.
userId String User with which the assertion should be associated with. Can be null.
externalId String Link to transaction in other system (i.e., core system transaction).
templateName* String Template on which this assertion should be based.
operationId String Optional identifier of the operation with which the assertion should be associated. If omitted or null, a new operation is created.
parameters Map<String,String> Template parameters.

Response

If the challenge is successfully created, API returns the following response:

{
  "status": "string",
  "responseObject": {
    "appIds": [
      "string"
    ],
    "challenge": "string",
    "userId": "string",
    "failedAttempts": 0,
    "maxFailedAttempts": 0,
    "allowCredentials": [
      {
        "credentialId": "string",
        "type": "string",
        "transports": [
          "string"
        ]
      }
    ]
  }
}
Description of Response Params
Attribute Type Description
appIds* String[] Applications that are capable of approving the operation.
challenge String The assertion challenge to be signed by the authenticator.
userId String User with which the assertion should be associated with. Can be null.
failedAttempts Long Information about how many times this assertion was unsuccessfully approved.
maxFailedAttempts Long Information about how many times this assertion can be unsuccessfully approved.
allowCredentials AllowCredentials Credentials that are associated with this assertion.
AllowCredentials Object
Attribute Type Description
credentialId* String Credential ID, byte array encoded in Base64 encoding.
type String Type of credentials, mostly public-key value.
transports String[] Allowed authenticator transport modes.

post /v2/fido2/assertions Verify an Assertion

Verify a FIDO2 assertion for an operation based on an assertion verification request generated and signed by the authenticator.

Request

{
  "requestObject": {
    "credentialId": "string",
    "type": "string",
    "authenticatorAttachment": "string",
    "response": "...",
    "appId": "string",
    "relyingPartyId": "string",
    "allowedOrigins": [
      "string"
    ],
    "allowedTopOrigins": [
      "string"
    ],
    "requiresUserVerification": true,
    "expectedChallenge": "string"
  }
}
Request Params
Attribute Type Description
credentialId* String Credential ID.
type* String Credential type (public-key).
authenticatorAttachment* String Information about authenticator attachment.
response* String Authenticator response (value provided by authenticator, encoded as Base64).
appId String Application identifier, to verify the challenge can be approved by given app.
relyingPartyId String Identification of relying party, typically the domain, i.e., example.com.
allowedOrigins String[] Collection of origins that should be allowed to provide the assertion.
allowedTopOrigins String[] Collection of top origins that should be allowed to provide the assertion.
requiresUserVerification boolean Information if user verification flag must be present (if user was verified).
expectedChallenge String Expected challenge value. If present, it is checked against the actual challenge.

Response

If the challenge is successfully verified, API returns the following response:

{
  "status": "string",
  "responseObject": {
    "assertionValid": true,
    "userId": "string",
    "registrationId": "string",
    "appId": "string",
    "registrationStatus": "ACTIVE",
    "blockedReason": "string",
    "remainingAttempts": 0,
    "applicationRoles": [
      "string"
    ],
    "registrationFlags": [
      "string"
    ]
  }
}
Description of Response Params
Attribute Type Description
assertionValid* Boolean Result of assertion validation.
userId String User with which the assertion should be associated with. Can be null.
registrationId String ID of registration that was used for verification.
appId String Information about what application was used for approval.
registrationStatus String Associated registration status.
blockedReason String If registration is blocked, the value contains information about reason for blocking.
remainingAttempts String How many attempts remain to approve the assertion (authenticator counter).
applicationRoles String[] Roles associated with the related application.
registrationFlags String[] Flags associated with the related registration.
Last updated on Dec 22, 2025 (16:05) View product
Search

develop

PowerAuth Cloud