WebAuthnPreregistration

The WebAuthn Preregistration API provides a flow to initiate and set up WebAuthn Preregistration authenticator enrollments through third-party providers.

Activate a Preregistered WebAuthn Factor
OAuth 2.0: okta.users.manage

Activates a preregistered WebAuthn Factor. As part of this operation, Okta first decrypts and verifies the Factor PIN and enrollment data sent by the fulfillment provider.

Request
Request Body schema: application/json

Enrollment Activation Request

Array of objects (WebAuthnCredResponse)

List of credential responses from the fulfillment provider

Array
authenticatorEnrollmentId
string

ID for a WebAuthn Preregistration Factor in Okta

credResponseJWE
string

Encrypted JWE of credential response from the fulfillment provider

fulfillmentProvider
string

Name of the fulfillment provider for the WebAuthn Preregistration Factor

Value: "yubico"
pinResponseJwe
string

Encrypted JWE of PIN response from the fulfillment provider

serial
string

Serial number of the YubiKey

userId
string

ID of an existing Okta user

version
string

Firmware version of the YubiKey

Array of objects (ECKeyJWK)

List of usable signing keys from Yubico (in JWKS format) used to verify the JWS inside the JWE

Array
crv
required
string
Value: "P-384"
kid
required
string

The unique identifier of the key

kty
required
string

The type of public key

Value: "EC"
use
required
string

The intended use for the key. The ECKeyJWK is always enc because Okta uses it to encrypt requests to Yubico.

Value: "enc"
x
required
string

The public x coordinate for the elliptic curve point

y
required
string

The public y coordinate for the elliptic curve point

Responses
200

Success

400

PIN or Cred Requests Generation Failed

403

Forbidden

404

Not Found

429

Too Many Requests

post/webauthn-registration/api/v1/activate
Request samples
application/json
{
  • "credResponses": [
    • {
      }
    ],
  • "fulfillmentProvider": "yubico",
  • "pinResponseJwe": "string",
  • "serial": "string",
  • "userId": "string",
  • "version": "string",
  • "yubicoSigningJwks": [
    • {
      }
    ]
}
Response samples
application/json
{
  • "authenticatorEnrollmentIds": [
    • "string"
    ],
  • "fulfillmentProvider": "yubico",
  • "userId": "string"
}

Enroll a Preregistered WebAuthn Factor
OAuth 2.0: okta.users.manage

Enrolls a preregistered WebAuthn Factor. This WebAuthn Factor has a longer challenge timeout period to accommodate the fulfillment request process. As part of this operation, Okta generates EC key-pairs used to encrypt the Factor PIN and enrollment data sent by the fulfillment provider.

Request
Request Body schema: application/json

Enrollment Initialization Request

enrollmentRpIds
Array of strings

List of Relying Party hostnames to register on the YubiKey.

fulfillmentProvider
string

Name of the fulfillment provider for the WebAuthn Preregistration Factor

Value: "yubico"
userId
string

ID of an existing Okta user

object (ECKeyJWK)

Elliptic Curve Key in JWK format, currently used during enrollment to encrypt fulfillment requests to Yubico, or during activation to verify Yubico's JWS objects in fulfillment responses. The currently agreed protocol uses P-384.

crv
required
string
Value: "P-384"
kid
required
string

The unique identifier of the key

kty
required
string

The type of public key

Value: "EC"
use
required
string

The intended use for the key. The ECKeyJWK is always enc because Okta uses it to encrypt requests to Yubico.

Value: "enc"
x
required
string

The public x coordinate for the elliptic curve point

y
required
string

The public y coordinate for the elliptic curve point

Responses
200

Success

400

PIN or Cred Requests Generation Failed

403

Forbidden

404

Not Found

429

Too Many Requests

post/webauthn-registration/api/v1/enroll
Request samples
application/json
{
  • "enrollmentRpIds": [
    • "string"
    ],
  • "fulfillmentProvider": "yubico",
  • "userId": "string",
  • "yubicoTransportKeyJWK": {
    • "crv": "P-384",
    • "kid": "string",
    • "kty": "EC",
    • "use": "enc",
    • "x": "string",
    • "y": "string"
    }
}
Response samples
application/json
{
  • "credRequests": [
    • {
      }
    ],
  • "fulfillmentProvider": "yubico",
  • "pinRequestJwe": "string",
  • "userId": "string"
}

Generate a Fulfillment Request
OAuth 2.0: okta.users.manage

Generates a fulfillment request by sending a WebAuthn Preregistration event to start the flow. The Okta Workflows WebAuthn preregistration integration uses this to populate the fulfillment request.

Request
Request Body schema: application/json

Fulfillment Request

object (FulfillmentData)

Fulfillment provider details

customizationId
string

ID for the set of custom configurations of the requested Factor

inventoryProductId
string

ID for the specific inventory bucket of the requested Factor

productId
string

ID for the make and model of the requested Factor

fulfillmentProvider
string

Name of the fulfillment provider for the WebAuthn Preregistration Factor

Value: "yubico"
userId
string

ID of an existing Okta user

Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

post/webauthn-registration/api/v1/initiate-fulfillment-request
Request samples
application/json
{
  • "fulfillmentData": {
    • "customizationId": "string",
    • "inventoryProductId": "string",
    • "productId": "string"
    },
  • "fulfillmentProvider": "yubico",
  • "userId": "string"
}
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}

List all WebAuthn Preregistration Factors
OAuth 2.0: okta.users.read

Lists all WebAuthn Preregistration Factors for the specified user

Request
path Parameters
userId
required
string

ID of an existing Okta user

Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/webauthn-registration/api/v1/users/{userId}/enrollments
Request samples
Response samples
application/json
[
  • {
    • "id": "fwf23789dfs9asdf782",
    • "factorType": "webauthn",
    • "provider": "FIDO",
    • "vendorName": "FIDO",
    • "fulfillmentProvider": "yubico",
    • "status": "ACTIVE",
    • "created": "2018-05-24T20:43:19.000Z",
    • "lastUpdated": "2018-05-24T21:43:32.000Z",
    • "profile": {
      },
    }
]

Delete a WebAuthn Preregistration Factor
OAuth 2.0: okta.users.manage

Deletes a specific WebAuthn Preregistration Factor for a user

Request
path Parameters
userId
required
string

ID of an existing Okta user

authenticatorEnrollmentId
required
string

ID for a WebAuthn Preregistration Factor in Okta

Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

delete/webauthn-registration/api/v1/users/{userId}/enrollments/{authenticatorEnrollmentId}
Request samples
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}