API Reference

The following describes the APIs used with FIDO Pre-reg integrations when requesting credentials and shipment of enrolled YubiKeys.

Authentication

To authenticate to the YubiKey as a Service API and the FIDO Connector API, you will use an API caller authentication token (YED_API_Token). To create the API token, sign in to the Customer Portal with the account for the application that will be calling the APIs. See API Caller Account Setup.

FIDO Connector API

The FIDO Connector is deployed in the customer’s Azure environment, and provides APIs for credential requests. The API is called from processes and workflows to handle orchestration of credential requests from an IdP and shipment requests from Yubico.

Each deployment of the FIDO Connector will have its own instance of the API. The base URL is derived from the URL provided by the Container app service, and will be unique for each deployment. API calls will go to something like in the example below.

Base URL (example): https://company-fido-connector.azurecontainerapps.io/…

Create Credential Request

VERSION 2.0 (Current)

Provides the ability to create a request for both Yubico-managed and local on-site trusted agents programming of credentials onto a YubiKey using a mobile device. If desired, the request can include shipment requests for one or more enrolled YubiKeys. You can add multiple credentials to the same YubiKey, and request enrollment to multiple IdPs.

The authenticator in this context is a security application or device, for example a YubiKey. A credential is the authentication private/public key pair. One authenticator can have multiple credentials, and each credential correlates to a user ID and relying-party ID pair. A credential request is a request for creating a credential in the Yubico Enrollment service.

In the FIDO Connector API, all requests are credential requests, where some might also include shipments of physical YubiKeys. This means that there will always be a credential ID, and if shipment is included, there will also be a shipment ID. shipment_items is used for Yubico-managed programmed FIDO Pre-reg shipments, while authenticators is used for local on-site programming of credentials onto a YubiKey without involving any shipping. Both shipment and authenticators can be included in a request.

When multiple credentials are registered on the same security key, the credential requests are processed in the same order as added in the authenticators.credentials array, and the responses are sent back in the same order. To control the order of the credentials used when signing in, for example in cases where the most recently registered credential is automatically used first, ensure to place the requests in the desired order in the authenticators.credentials array.

The endpoint receives the credentials, the authenticators, and if there are physical YubiKeys to be shipped, associated information for these. A recipient email address is required if the request involves a YubiKey shipment. The credential object contains a list of the names of the authenticators and/or YubiKeys to which the credentials will be added.

The FIDO Connector accepts any PIN length between 4 and 63 characters (inclusive). A 6-digit PIN is often used by mobile operating systems to increase authentication security, while remaining manageable to memorize by end users. Note that if the YubiKey is for example a YubiKey FIPS and requires 8 characters, the programming will set the length to 8.

Endpoint: POST /v2/credential-requests

Request body

  {
 "recipient": {
   "email": "firstname.lastname@example.com",
   "first_name": "Firstname",
   "last_name": "Lastname",
   "company": "Example Corporation",
   "telephone": "+123456789",
   "external_id": "firstname.lastname@example.com"
 },
 "enrollment_contacts": {
   "emails_to": [
     "firstname.lastname@example.com", "itadmin@example.com"
   ]
 },
 "shipment": {
   "delivery_type": 1,
   "reseller_organization_id": "100",
   "customer_reference": "Cost center 123",
   "address_validation_bypass": false,
   "mailing_address": {
     "street_line1": "#123 Street Name",
     "street_line2": "Unit #456",
     "postal_code": "98765",
     "city": "City Name",
     "region": "MA",
     "country_code": "US"
   },
   "shipment_items": [
     {
       "name": "My YubiKey",
       "customization_id": "ABC123",
       "product_id": "1",
       "inventory_product_id": "789",
       "pin_request": {
         "length": 6,
         "type": "generate"
       },
       "credentials": [
         {
           "idp_id": "entraid",
           "user_id": "firstname.lastname@example.com"
         },
         {
           "idp_id": "pingone",
           "relying_party_id": "pingone",
           "user_id": "firstname.lastname@example.com"
         }
       ]
     }
   ]
 },
 "authenticators": [
   {
     "name": "My passkey",
     "customization_id": "DEF456",
     "preferred_authenticator_type": "software",
     "pin_request": {
       "min_length": 6,
       "entry_method": "user_entered",
       "delivery_method": "app"
     },
     "credentials": [
       {
         "idp_id": "entraid",
         "user_id": "firstname.lastname@example.com"
       },
       {
         "idp_id": "pingone",
         "relying_party_id": "pingone",
         "user_id": "firstname.lastname@example.com"
       }
     ]
   }
 ]
}

Parameters

  • recipient The end-user receiving the pre-enrolled YubiKey and/or credentials:
    • email Required. Used for Yubikey as a Service emails such as delivery notifications for shipment of physical keys.
    • first_name Required.
    • last_name Required.
    • company Optional. Either the company name or recipient name is required, you can provide both if shipping to a commercial/business address.
    • telephone Required. Supported characters are +, (, ), and digits 0 - 9. Dashes are accepted but not recommended. Up to 40 characters allowed. Passed on to the delivery carrier to be used if there is an issue with delivering a package. Yubico does not use this field to contact the user.
    • external_id Optional. Unique identifier for the recipient for which the credentials are requested, for example defined by the organization’s HR system. Can be for example the end user’s email address.
  • enrollment_contacts A list of email addresses to, for example the end user or the security administrator, where the PIN is sent:
    • emails_to Required. List of valid email addresses, should at least include one email address, does not have to be the same as the recipient email.
  • shipment Required if authenticators is not provided (shipment-only request), otherwise optional:
    • delivery_type Optional, if provided should be either “1” - standard (default), or “2” - expedited.
    • reseller_organization_id Optional, the organization ID of the channel partner (distributor/reseller) in the Delivery service. Use the Get all channel partners relevant to an org API to retrieve this.
    • customer_reference Optional, customer-provided reference information, see Customer Reference Field.
    • address_validation_bypass Optional, “true/false”, see Address Validation Override.
    • mailing_address For shipment of physical keys:
      • street_line1 Required, first line of address, see Address Field Limitations.
      • street_line2 Optional, second line of address. Can be used for long addresses, or to capture door code or other building access information, see Address Field Limitations.
      • postal_code Required, cannot be empty, space is accepted. For shipments to countries without postal codes, enter “00000”.
      • city Required.
      • region Optional, required for shipments going to the US, Canada, and US international military bases. Two-letter USPS region code, see USPS Region/State Codes.
      • country_code Required. Two-letter country code, see Country Codes.
    • shipment_items Used for shipment of Yubico-programmed YubiKeys:
      • name Optional, reference name sent to the IdP. Used as passkey name in Entra and device nickname in PingOne. If not provided, “Pre-Reg YubiKey” + serial number will be used as default.
      • customization_id Optional, ID associated with the programming, see Customizations.
      • product_id Required, ID of the YubiKey product model, see Product and Inventory Identifiers.
      • inventory_product_id Required, the subscription ID associated with the delivery, see Product and Inventory Identifiers.
      • pin_request Optional, defines the YubiKey PIN requirements. Default values only apply if at least the object is provided. Otherwise, the request is sent without the PIN request data. If an incomplete object is provided, the default length value is “6”.
        • length Optional, if provided, should be equal to or greater than “4” and equal to or less than “63”. The length of the PIN to be randomly generated and set on a YubiKey. Note this is not the YubiKey firmware setting of minimum PIN length. If a length is requested that is less than the YubiKey setting of minimum PIN length, a PIN meeting that requirement will be generated.
        • type Only “generate” is supported for shipments of physical keys.
      • credentials Required, information associated with the credentials:
        • idp_id Optional, used for multi-IdP deployments. Default value is configurable through the IDP_DEFAULT environment variable, see identity provider integration guides.
        • relying_party_id Optional, default value can be configured in the IdP implementation. Used for example for PingOne, see configuring PingOne PingID.
        • user_id ID of the end user in the relying party that the credential is being created for. Examples: For Entra ID, the UPN or user object ID; for PingOne, the PingOne PingID username.
  • authenticators Optional, required if shipment is not provided (credential-only request):
    • name Optional authenticator “nickname”. If not provided, the default ”Pre-Reg YubiKey” will be used..
    • customization_id Optional, ID associated with the programming, see Customizations.
    • preferred_authenticator_type Optional, if provided can be either “hardware”, passkey on a physical key (default), or “software”, passkey on for example a mobile device.
    • pin_request Optional, defines whether a PIN is required or not. Default values only apply if at least the object is provided. Otherwise, the request is sent without the PIN request data. If an incomplete object is provided, the default value is “6”:
      • min_length Optional, if provided, should be equal to or greater than “4” and equal or less than “63”.
      • entry_method Optional, can be either “generated” (default), pre-programmed, or “user_entered”, entered during on-site enrollment.
      • delivery_method Optional, if provided should be either “none”, “app”, or “email”.
    • credentials Required, information associated with the credentials:
      • idp_id Optional, used for multi-IdP deployments. Default value is configurable through the IDP_DEFAULT environment variable, see identity provider integration guides.
      • relying_party_id Optional, default value can be configured in the IdP implementation. Used for example for PingOne, see configuring PingOne PingID.
      • user_id ID of the end user in the relying party that the credential is being created for.

Success response body

{
"data": {
  "credential_request_id": "123abc-...",
  "shipment_id": "123xyz..."
}
  • data.credential_request_id The ID of the created credential request.
  • data.shipment_id The ID of the created shipment request. Only included if shipment is a request parameter.

Error response body

{
 "error_code": "error type",
 "error_message": "error message",
 "error_data": {
   "key": "value"
  }
}

Response messages

  • 201 Created
  • 400 Validation Failed or Propagated
  • 401 Unauthorized on FIDO Connector
  • 500 Unexpected error or failure authenticating with Enrollment service

Example 1: Shipment-only Request

In this example scenario, two enrolled YubiKeys are shipped directly to a new employee working remotely. The request includes shipment of a YubiKey 5 NFC (“product_id”: “1”), and a YubiKey 5C NFC ("product_id": "29"), to the end user who is registered in the organizations IdP ("user_id") Entra ID.

The keys are programmed by Yubico and shipped to the end user’s home address. The 6-digit PIN ("length": 6)`` for each YubiKey is delivered through email to the end user. The request body contains a shipment object with two items.

{
 "recipient": {
   "email": "enduser1@example.com",
   "first_name": "Firstname",
   "last_name": "Lastname",
   "company": "Example Corporation",
   "telephone": "+123456789",
   "external_id": "enduser1@example.com"
 },
 "enrollment_contacts": {
   "emails_to": [
     "enduser1@example.com"
   ]
 },
 "shipment": {
   "delivery_type": 1,
   "customer_reference": "Cost center 123",
   "address_validation_bypass": false,
   "mailing_address": {
     "street_line1": "#123 Street Name",
     "street_line2": "Unit #456",
     "postal_code": "98765",
     "city": "City Name",
     "region": "MA",
     "country_code": "US"
   },
   "shipment_items": [
     {
            "name": "Primary YubiKey",
      "customization_id": "ABC123",
      "product_id": "1",
            "inventory_product_id": "133",
      "pin_request": {
       "length": 6,
       "type": "generate"
      },
       "credentials": [
         {
           "user_id": "enduser1@example.com"
         }
       ]
     },
     {
       "name": "Backup YubiKey",
       "customization_id": "ABC123",
       "product_id": "29",
       "inventory_product_id": "133",
       "pin_request": {
         "length": 6,
         "type": "generate"
       },
       "credentials": [
         {
           "user_id": "enduser1@example.com"
         }
       ]
     }
   ]
 }
}

Example 2: Credential-only Request

The following shows a request in a scenario where a security administrator enrolls a YubiKey on-site, on behalf of an end user who has lost their YubiKey, and is present in person. The end user is registered in the organization’s IdP ("user_id") PingOne. The security administrator already has the YubiKey, so no shipment is involved, and the security administrator is acting as a trusted agent, performing the programming of the YubiKey.

The request is received by the Enroll app (LEA), and the security administrator uses the app on a mobile device to program the credentials onto the key ("preferred_authenticator_type": "hardware"). During the enrollment, the end user enters a PIN of their choice ("entry_method": "user_entered") in the mobile device. The enrolled YubiKey is then handed over to the end user. The request body contains an authenticators object with one credential item.

{
 "recipient": {
   "email": "enduser@pingone.com",
   "first_name": "Firstname",
   "last_name": "Lastname",
   "company": "Example Corporation",
   "telephone": "+46123456789",
   "external_id": "enduser@pingone.com"
 },
 "enrollment_contacts": {
   "emails_to": [
     "enduser@pingone.com, securityadmin@example.com"
   ]
 },
 "authenticators": [
   {
     "name": "Replacement YubiKey",
     "customization_id": "ABC123",
     "preferred_authenticator_type": "hardware",
     "pin_request": {
       "min_length": 6,
       "entry_method": "user_entered",
       "delivery_method": "app"
     },
     "credentials": [
        {
         "user_id": "enduser@pingone.com"
        }
     ]
   }
 ]
}

Example 3: Shipment and Credential Request

The following is an example of a scenario where one enrolled YubiKey is shipped to the end user as a backup key, and another YubiKey is enrolled on site by a security administrator, using the Enroll app (LEA) on a mobile device, with the end user present in person.

The 6-digit PIN for the YubiKey that is enrolled on site is entered by the end user during the enrollment procedure ("entry_method": "user_entered"). The shipped YubiKey is programmed by Yubico ("entry_method": "generated"), and the PIN is provided via email to the end user and the security administrator ("enrollment_contacts.emails_to"). The request body contains a shipment and an authenticators object with one item in each.

{
 "recipient": {
   "email": "enduser@example.com",
   "first_name": "Firstname",
   "last_name": "Lastname",
   "company": "Example Corporation",
   "telephone": "+123456789",
   "external_id": "enduser@example.com"
 },
 "enrollment_contacts": {
   "emails_to": [
     ",enduser@example.com, securityadmin@example.com"
   ]
 },
 "shipment": {
   "delivery_type": 1,
   "customer_reference": "Cost center 123",
   "address_validation_bypass": false,
   "mailing_address": {
     "street_line1": "#123 Street Name",
     "street_line2": "Unit #456",
     "postal_code": "98765",
     "city": "City Name",
     "region": "MA",
     "country_code": "US"
   },
   "shipment_items": [
     {
       "name": "Backup YubiKey",
       "customization_id": "ABC123",
       "product_id": "29",
       "inventory_product_id": "133",
       "pin_request": {
         "length": 6,
         "type": "generate"
       },
       "credentials": [
         {
           "user_id": "enduser@example.com"
         }
       ]
     }
   ]
 },
 "authenticators": [
   {
     "name": "Primary YubiKey",
     "customization_id": "ABC123",
     "preferred_authenticator_type": "hardware",
     "pin_request": {
       "min_length": 6,
       "entry_method": "user_entered",
       "delivery_method": "app"
     },
     "credentials": [
       {
         "user_id": "enduser@example.com"
       }
     ]
   }
 ]
}

Example 4: Multi-IdP Credential-only Request

In this example, a security administrator for an organization that uses both IdPs Entra ID and PingOne, enrolls two credentials for an end user onto the same YubiKey, using the Enroll app (LEA) on a mobile device. After the programming, the security administrator hands over the YubiKey to the end user, so no shipment is involved here.

The credentials are added to the YubiKey ("preferred_authenticator_type": "hardware"). The security administrator enters a temporary PIN ("entry_method": "user_entered"), which is then emailed ("delivery_method": "email") to the provided email addresses. The request body contains an authenticators object with two credential items, one for each IdP respectively.

{
 "recipient": {
   "email": "enduser@example.com",
   "first_name": "Firstname",
   "last_name": "Lastname",
   "company": "Example Corporation",
   "telephone": "+46123456789",
   "external_id": "enduser@example.com"
 },
 "enrollment_contacts": {
   "emails_to": [
     "enduser@example.com, securityadmin@example.com"
   ]
 },
 "authenticators": [
     {
       "name": "System XYZ security key",
       "customization_id": "ABC123",
       "preferred_authenticator_type": "hardware",
       "pin_request": {
         "min_length": 6,
         "entry_method": "user_entered",
         "delivery_method": "email"
     },
     "credentials": [
       {
         "idp_id": "entraid",
         "user_id": "enduser@example.com"
       },
       {
         "idp_id": "pingone",
         "relying_party_id": "pingone.com",
         "user_id": "enduser@example.com"
       }
     ]
   }
 ]
}

Version 1 - Create Credential Request

Version 1 of the Create Credential Request API is a credential-only request supporting local on-site programming by trusted agents of credentials using a mobile device. The API also supports the option to configure the credential creation flow to allow the end user to enter their PIN through the mobile device used in an on-site enrollment scenario.

Note

Version 1 of the FIDO Connector Create Credential API does not support multiple IdPs. By default the IdP configured in the environment variable IDP_DEFAULT will be used. To be able to connect to multiple IdPs, use the Create Credential Request version 2.0 API.

Endpoint: POST /v1/credential-requests

Request body

{
   "recipient": {
       "firstname": "Firstname",
       "lastname": "Lastname",
       "email": "firstname.lastname@example.com"
   },
   "credentials": [
       {
           "user_id": "firstname.lastname@example.com"
       }
   ],
   "pin_request": {
       "min_length": 6
       "entry_method": "user_entered"
   },
   "authenticator_name": "My passkey",
   "customization_id": "ABC123",
   "enrollment_contacts": {
       "emails_to": ["firstname.lastname@example.com"]
   }
}

Get Credential Request by ID

VERSION 2.0 (Current)

Provides the ability to view the status of a credential request with a specific ID in the FIDO Connector. The endpoint returns the status of programmed credentials, both programmed by Yubico as well as programmed on-site by trusted agents. The credential are returned as an array of authenticators and credentials.

If the request includes shipment of physical keys, the credential creation status for each YubiKey and the associated IdP included in the shipment are also returned.

Endpoint: GET /v2/credential-requests/{credential-request-id}

Success response body

{
 "data": {
   "credential_request_id": "9c8cb30f-bc7a-4e06-bfac...",
   "state": "received",
   "authenticators": [
     {
       "id": "fe0e64f2-eb18...",
       "name": "My YubiKey",
       "state": "processing",
       "credentials": [
         {
           "idp_id": "pingone",
           "relying_party_id": "pingone",
           "user_id": "firstname.lastname@example.com",
           "state": "activation_pending",
           "error_message": "optional"
         }
       ]
     }
   ],
   "shipment": {
     “shipment_id”: “R9SJFBzFbMw...”,
     "shipment_items": [
       {
         "id": "1",
         "name": "YubiKey 5 NFC",
         "state": "processing",
         "credentials": [
           {
             "idp_id": "entraid",
             "user_id": "firstname.lastname@example.com",
             "state": "activation_pending",
             "error_message": "optional"
           },
           {
             "idp_id": "pingone",
             "relying_party_id": "pingone",
             "user_id": "firstname.lastname@example.com",
             "state": "activation_pending",
             "error_message": "optional"
           }
         ]
       }
     ],
     "mailing_address": {
       "street_line1": "#123 Street Name",
       "street_line2": "Unit #456",
       "postal_code": "98765",
       "city": "City Name",
       "region": "MA",
       "country_code": "US"
     }
   }
 }
}

Parameters

  • credential_request_id The credential ID that was returned in the credential request response, see Create Credential Request.
  • state The state of the credential request can be one of “received”, “started”, “complete”, “partial”, “failed”, or “cancelled”.
  • authenticators Optional, for example one or more IdPs. If provided cannot be blank.
  • authenticators.id The ID of the created authenticator.
  • authenticators.name Required, either a custom name or the default ”Pre-Reg YubiKey”.
  • authenticators.state The state of the credential processing, can be one of “processing”, “complete”, “partial”, “failed”, or “cancelled”.
  • shipment Optional, be provided if a physical shipment is part of the request.
  • shipment.shipment_items Information provided to the IdP when the credential is sent back to the IdP.
  • shipment_items.id The ID of the shipment of physical items if included, returned in the credential request response, see Create Credential Request.
  • shipment_items.state The state of the shipment of physical items, if included, can be one of “processing”, “complete”, “partial”, “failed”, or “cancelled”.

Error response body

{
 "error_code": "error type",
 "error_message": "error message",
 "error_data": {
   "key": "value"
  }
}

Response messages

  • 200 Success
  • 404 Not Found
  • 401 Unauthorized on FIDO Connector
  • 500 Unexpected Error or Failure Authenticating with FPR

Version 1 - Get Credential Request by ID

Provides the ability to view the status of a credential request with a specific ID in the FIDO Connector.

Endpoint: GET /v1/credential-requests/{credential_request_id}

Success response body

{
 "credential_request_id": "9c8cb30f-bc7a-4e06-bfac...",
 "credential_request_state": "processing",
 "credentials": [
     {
         "user_id": "firstname.lastname@example.com",
         "relying_party_id": "pingone",
         "idp_id": "pingone",
         "credential_state": "activation_pending"
     }
 ]
}

Check Deployment Status

VERSION 2.0 (Current)

Provides the status of deployment components. The response returns the configuration settings specific to the default IdP configured in the FIDO Connector.

When testing a deployment, you can first do a call to /v2/status to verify that the API is operational and the client can connect to it. It is also a way to ensure that some of the key properties provided during deployment are set.

Endpoint: GET /v2/status

Success Response Body

Example with Entra ID, PingOne PingID and PingOne AIC as IdPs.

  {
   "AZURE_STORAGE_BLOB_ENDPOINT": "https://....blob.core.windows.net/",
   "AZURE_TABLES_SHIPMENTS_TABLE_NAME": "fprshipments",
   "AZURE_TENANT_ID": "fe0e64f2-eb18...",
   "CRON_PROCESS_SHIPMENT_SCHEDULE": "0 0 * * * *",
   "CRON_PROCESS_CREDENTIAL_REQUESTS_SCHEDULE": "0 */12 * * * 0",
   "CRON_DATA_CLEANUP_SCHEDULE": "0 30 * * * *",
   "CRON_DATA_CLEANUP_COMPLETED_DAYS": "0",
   "FIDO_CONNECTOR_VERSION": "2.0.0-rc5",
   "LOGGING_LEVEL_COM_YUBICO": "DEBUG",
   "EMAIL_API_SEND_ENDPOINT": "https://...westus2.logic.azure.com:443/...",
   "YE_API_BASE_URL": "https://.../v1",
   "YE_JWKS_SIGN_ENDPOINT": "https://.../.well-known/yubico-sign.jwks",
   "YE_JWKS_TRANSPORT_ENDPOINT": "https://.../.well-known/yubico-transport-keys.jwks",
   "RFPR_API_BASE_URL": "https://.../credentials/connector",
   "RFPR_RETRY_NUMBER_DAYS": "1",
   "ENROLLMENT_SUITE_API_BASE_URL": "https://...",
   "IDP_DEFAULT": "ping-aic",
   "IDP_ENABLE_MULTI_IDP": "true",
   "IDP_CONFIGURATION_PATH": "idp-configuration.yaml",
   "IDP_CONFIGURATIONS": {
       "pingone": {
           "default-relying-party": "pingone.com",
           "api-base-url": "https://api.pingone.com/v1",
           "environment-id": "c15efa10-4ebb...",
           "pre-registration-timeout-days": 30,
           "type": "pingone",
           "client-id": "6941c5d6-495b...",
           "auth-base-url": "https://auth.pingone.com"
       },
       "entraid": {
           "api-version": "beta",
           "graph-endpoint": "https://graph.microsoft.com",
           "type": "entraid",
           "challenge-timeout-minutes": 20160,
           "client-id": "b7b32d87-b933...",
           "tenant-id": "fe0e64f2-eb18...",
           "online-endpoint": "https://login.microsoftonline.com"
       },
       "ping-aic": {
           "journey": "WebAuthnPreReg-FIDOConnector",
           "challenge-timeout-milliseconds": 1300000000,
           "type": "ping-aic",
           "api-base-url": "https://example.forgeblocks.com",
           "authentication-header": "oidc_id_token",
           "token-id-2": "IDToken2",
           "token-id-1": "IDToken1",
           "scope": "api://scope-api.onmicrosoft.com",
           "realm": "alpha",
           "client-id": "client-id-string",
           "callback-1": "NameCallback",
           "auth-base-url": "https://example.forgeblocks.com",
           "callback-3": "HiddenValueCallback",
           "callback-2": "MetadataCallback"
       }
   }
}

Response messages

  • 200 Success

Version 1 - Check Deployment Status

Endpoint: GET /v1/status

Success response body

Example with Microsoft Entra ID as IdP.

"AZURE_KEY_VAULT_ENDPOINT":"https://msfpr...azure.net"
"AZURE_TABLES_ENDPOINT":"https://msfpr...windows.net"
"AZURE_TABLES_SHIPMENTS_TABLE_NAME":"fprshipments"
"AZURE_TENANT_ID":"fe0e64f2..."
"CRON_PROCESS_SHIPMENT_SCHEDULE":"0 0 * * * *"
"CRON_DATA_CLEANUP_SCHEDULE":"0 30 * * * *"
"CRON_DATA_CLEANUP_COMPLETED_DAYS":"0"
"EMAIL_API_SEND_ENDPOINT":"https://prod...IhyfXyc"
"ENTRA_FIDO_API_CLIENT_ID": "123abc...",
"ENTRA_FIDO_API_VERSION": "string",
"ENTRA_FIDO_API_CHALLENGE_TIMEOUT_MINUTES": "string",
"LOGGING_LEVEL_COM_YUBICO":"INFO"
"YE_API_BASE_URL":"https://..."
"YE_JWKS_SIGN_ENDPOINT":"https://...sign.jwks"
"YE_JWKS_TRANSPORT_ENDPOINT":"https://...keys.jwks"
"FIDO_CONNECTOR_VERSION":"1.2.0"

Process Shipments

VERSION 2.0 (Current)/1.0 (no changes between versions 1 and 2)

Provides the ability to trigger on-demand the process of retrieving shipment responses from the Delivery service and process them. This API is useful if shipment processing needs to be run right away instead of waiting for the scheduled job.

Endpoint v2: GET /v2/operations/process-shipments

Endpoint v1: GET /v1/operations/process-shipments

Response messages

  • 204 Success, no content body.

Process Credential Request

VERSION 2.0 (Current)

Provides the ability to process and activate the credential request after fulfillment. When activated, the credential is ready to be used for authentication by the end user.

Endpoint: POST /v2/operations/process-credential-requests

Error response body

{
 "error_code": "error type",
 "error_message": "error message",
 "error_data": {
   "key": "value"
  }
}

Response messages

  • 200 Success
  • 401 Unauthorized on FIDO Connector
  • 500 Unexpected Error or Failure Authenticating with FPR

Version 1 - Process Credential Requests

Endpoint: POST /v1/operations/process-credential-requests

Response messages

  • 204 Success, no content body

Resend PIN

VERSION 2.0 (Current)

Provides the ability to resend the PIN email for all authenticators and shipment items that have a PIN response available in the Enrollment service.

Endpoint: POST /v2/credential-requests/{credential_request_id}/resend-pin

Error response body

{
 "error_code": "error type",
 "error_message": "error message",
 "error_data": {
   "key": "value"
  }
}

Response messages

  • 200 Success
  • 401 Unauthorized on FIDO Connector
  • 500 Unexpected Error or Failure Authenticating with FPR

Version 1 - Resend PIN

Endpoint: POST /v1/credential-requests/{credential_request_id}/resend-pin

Provides the ability to resend a PIN if this exists for a credential request. If there are multiple user IDs (userId) in the request, the IDs are provided in the email as a non-URL encoded comma-separated list.

Endpoint: GET /v1/operations/resend-pin/{shipment_id}

Provides the ability to resend the PIN email for a shipment_id. For a shipment request in complete or pending_pin_sending status, this operation retrieves the PIN response from the Delivery service and decrypts it to resend the PIN email.

Response messages

  • 204 Success, no content body

FIDO Connector API and FIDO Pre-reg

The YubiKey as a Service API provides an integration option to initiate the delivery of YubiKeys pre-enrolled by Yubico, using the FIDO Pre-reg service. This integration option does not involve the FIDO Connector, and is only used for shipment of physical YubiKeys.

The FIDO Connector extends the FIDO pre-reg part of the YubiKey as a Service API, and the same POST /v1/fpr/shipments endpoint is called by the FIDO Connector during the workflow processing. See example in the following.

Create Shipment Request

VERSION 1.0

Endpoint: POST /v1/fpr/shipments

Request body

{
"user_id": "firstname.lastname@example.com",
"pin_request": {
    "type": "generate",
    "length": 6,
},
 "enrollment_contacts": {
   "emails_to": ["firstname.lastname@example.com","itadmin@example.com"]
},
"yubico_shipment_request": {
    "reseller_organization_id": "123456",
    "delivery_type": 1,
    "address_validation_bypass": false,
    "recipient": {
        "recipient_company": "Company name",
        "recipient_email": "firstname.lastname@example.com",
        "recipient_firstname": "First name",
        "recipient_lastname": "Last name",
        "recipient_telephone": "+123456789"
    },
    "mailing_address": {
        "street_line1": "#123 Street Name",
        "street_line2": "Unit #456",
        "city": "City Name",
        "region": "MA",
        "postal_code": "98765",
        "country_code_2": "US"
    },
    "shipment_items": [
       {
            "product_id": 1,
            "inventory_product_id": 18,
            "product_quantity": 1,
            "customization_id": "ABC123",
            "fc_additional_data": {
              "yubikey_name": "MyYubiKey"
        }
       }
    ]
  }
 }

Parameters

  • user_id Can be provided either as Object ID, for example “user_id”: “123456-abc-123456-xyz”, or as UPN (User Principal Name), for example “user_id”: “firstname.lastname@example.com”.

  • pin_request Value can be between 4 and 63, inclusive.

  • enrollment_contacts.emails_to List of strings of email addresses. Provides the ability to enter a list of email addresses to which the PIN can be sent. Using the enrollment_contacts object is optional for every IdP implementation.

    Note

    If using enrollment_contacts.emails_to with Microsoft Entra, the default “Send Shipment Pin Azure Logic App” must be appropriately modified to use emailsTo.

  • reseller_organization_id Optional, the organization ID of the channel partner (distributor/reseller) in the Delivery service. Use the Get all channel partners relevant to an org API to retrieve this.

  • recipient_email The email to receive the PIN (not the principle object name).

  • product_id Required, ID of the YubiKey product model, see Product and Inventory Identifiers.

  • inventory_product_id Required, the subscription ID associated with the delivery, see Product and Inventory Identifiers.

  • product_quantity The number of YubiKeys to include.

  • customization_id Optional, ID associated with the programming, see Customizations.

  • yubikey_name Optionally provides the ability to add a custom passkey name in a pre-registration request. The field will be displayed together with the serial number of the YubiKey. For example, if the input name is “Secondary” and the serial number is “1234567890”, this displays as “Secondary YubiKey: 1234567890”.

    If a custom name is provided, all characters must be ASCII and the field length must not exceed 18 characters. If a custom name is not provided, the default name “Pre-Reg YubiKey: {SERIAL}” is displayed.

Success response

  • 201
  • Response body:
Created shipment_id from Delivery service
{"data":{"shipment_id":"String"}}

Error response

  • 401 Unauthorized
  • 400 Bad Request
  • Response body examples:
{"error_code":"ye_error","error_message":"Validation error when creating YED shipment","error_data":{"code":"validation_error","message":"Input for Last Name exceeded limit of 20 characters"}}

{"error_code":"api_error","error_message":"PIN `length` must be between 4 and 8","error_data":{"error_type":"validation"}}

{"error_code":"idp_error","error_message":"Could not find user: 7dc95e2f-53-..."}

Get Shipment Request Status

VERSION 1.0

Provides the ability to get the processing state of a shipment_id created through the Create Shipment Request API.

Endpoint: GET /v1/fpr/shipments/{shipment_id}

Success response

  • 200

  • Response body:

    {
 "shipment_id": "R9SJFBzFbMw...",
 "shipment_state": "processing"
}

Error response

  • Response body:

    {
 "shipment_id": "string",
 "shipment_state": "string",
 "error_kind": "string",
 "error_message": "string"
}

The request can have the following states in the FIDO Connector:

shipment_state Description
ongoing
The request has been created in the Delivery
Service with a Shipment ID.
Fulfillment operations and credential
creation are in progress with the IdP.
complete
Response from the Delivery Service has been
received, the credential has been
created on the YubiKey and successfully
registered with the IdP.
pending_pin_sending
The credential has been activated but
there is a PIN sending failure.

If a processing error has been encountered it will be saved in the fprshipments table and returned by the API. Details about the encountered error are provided in error_kind and error_message as described in the following.

Error Description
error_kind
This field will contain a string value
“GENERAL” if an error has been
encountered during processing.
error_message
This field will contain a string value
that has the detailed error message
returned by the Delivery Service or
the IdP.