WebAuthn Preregistration

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

Activate a Preregistered WebAuthn Factor
Identity Engine
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
x
required
string

The public x coordinate for the elliptic curve point

y
required
string

The public y coordinate for the elliptic curve point

kty
required
string

The type of public key

Value: "EC"
crv
required
string
Value: "P-384"
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"
kid
required
string

The unique identifier of the key

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
Identity Engine
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.

x
required
string

The public x coordinate for the elliptic curve point

y
required
string

The public y coordinate for the elliptic curve point

kty
required
string

The type of public key

Value: "EC"
crv
required
string
Value: "P-384"
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"
kid
required
string

The unique identifier of the key

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
Identity Engine
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": [ ]
}

Send a PIN to user
Identity Engine
OAuth 2.0: okta.users.manage

Sends the decoded PIN for the specified WebAuthn Preregistration Enrollment. PINs are sent to the user's email. To resend the PIN, call this operation again.

Request
Request Body schema: application/json

Send PIN Request

authenticatorEnrollmentId
string

ID for a WebAuthn Preregistration Factor in Okta

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/send-pin
Request samples
application/json
{
  • "authenticatorEnrollmentId": "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
Identity Engine
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

Example: 00ub0oNGTSWTBKOLGLNR
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": {
      },
    • "_links": {}
    }
]
Delete a WebAuthn Preregistration Factor
Identity Engine
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


 
 Example:  00ub0oNGTSWTBKOLGLNR
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": [ ]
}
Assign the Fulfillment Error Status to WebAuthn Preregistration Factor
Identity Engine
OAuth 2.0: okta.users.manage
Assigns the Fulfillment Error Status to a WebAuthn Preregistration Factor for a user. The /mark-error path indicates that the specific FULFILLMENT_ERRORED AuthFactor status is set on the enrollment.


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
 Example:  00ub0oNGTSWTBKOLGLNR
authenticatorEnrollmentId
required
string
ID for a WebAuthn Preregistration Factor in Okta


 
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


post/webauthn-registration/api/v1/users/{userId}/enrollments/{authenticatorEnrollmentId}/mark-error
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": [ ]
}