API Reference

The FIDO Pre-reg API is an extension of the YubiEnterprise API for the Yubico Delivery service. These calls go to the YubiEnterprise API https://portal.yubico.com/api/v1…. Using this API you can create shipment requests for pre-enrolled YubiKeys.

For example, the POST/v1/fpr/shipments call returns a Shipment ID which you can use together with a Yubico API token to call the Delivery service API’s directly to get additional shipment information.

The FIDO Connector API is used by the FIDO Connector in the customer’s Azure environment. Each deployment of the FIDO Connector will have its own instance of the API. The base URL will depend on the URL provided by the Container app service, and will be unique for each deployment.

Base URL: API calls will go to something like in this example: https://company-fido-connector.azurecontainerapps.io/v1/…

The different APIs are described in more detail in the following.

Check Deployment Component Status

GET /v1/status (FIDO Connector API)

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

As part of the testing, you can first do a call to /v1/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.

Response: On success HTTP 200.

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"
}

Example with PingOne PingID 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"
 "LOGGING_LEVEL_COM_YUBICO":"INFO"
 "PINGONE_ENVIRONMENT":"c15efa10..."
 "PINGONE_DEFAULT_RELYING_PARTY":"pingone.com"
 "PINGONE_AUTH_BASE_URL":"https://auth.pingone.com"
 "PINGONE_CLIENT_ID":"ac4b171c..."
 "PINGONE_API_BASE_URL":"https://api.pingone.com/v1"
 "PINGONE_PRE_REGISTRATION_TIMEOUT_DAYS":"15"
 "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"
}

Create Shipment Request

POST /v1/fpr/shipments (FIDO Pre-reg API)

Provides the ability to place a request for shipment of pre-enrolled YubiKeys. For input values in shipment requests, see the following references:

Request:

{
 "user_id": "Either User Principal Name (UPN) or Object ID",
 "pin_request": {
     "type": "generate",
     "length": 8, //value can be between 4 and 63, inclusive
 },
  "enrollment_contacts": {
    "emails_to": ["email1","email2"] //List of strings with email addresses
 },
 "yubico_shipment_request": {
     "reseller_organization_id": "Optional ID for the reseller",
     "delivery_type": 1,
     "address_validation_bypass": false,
     "recipient": {
         "recipient_company": "Company name",
         "recipient_email": "Email address", //Should be email to receive PIN, not principle object name
         "recipient_firstname": "First name",
         "recipient_lastname": "Last name",
         "recipient_telephone": "5555555555"
     },
     "mailing_address": {
         "street_line1": "Street address",
         "street_line2": "Apt / unit #",
         "city": "City",
         "region": "2 char state",
         "postal_code": "Postal code",
         "country_code_2": "2 char country code"
     },
     "shipment_items": [
         {
             "product_id": 1, //YubiKey model ID
             "inventory_product_id": 18, //Subscription ID
             "product_quantity": 1, //# of keys to include
             "customization_id": "CUSTID" //Customization ID
             "fc_additional_data": {
               "yubikey_name": "MyYubiKey"
          }
         }
      ]
   }
}

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": "username@yubico123.sample.com".

enrollment_contacts.emails_to 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) is the Base58 Organization ID for the reseller that a shipment’s inventory was purchased through. It can be omitted or sent as an empty string if no value needs to be provided.

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 “12345678”, this displays as “Secondary: 12345678”. 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.

Response:

On success:
- HTTP 201
- Response body: Created shipment_id from the Delivery service
  
  {"data":{"shipment_id":"String"}}
On error:
- HTTP 401 Unauthorized
- HTTP 400 Bad Request
- 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 63","error_data":{"error_type":"validation"}}
  
  {"error_code":"idp_error","error_message":"Could not find user: 7dc95e2f-53-..."}

Get Shipment Request Status

GET /v1/fpr/shipments/{shipment_id} (FIDO Pre-reg API)

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

The request in the FIDO Connector App has two distinct states: “ongoing” and “complete”. The states are described in more detail in the following.

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 MS Entra ID.
complete	Response from the Delivery Service has been received, the credential has been created on the YubiKey and successfully registered with MS Entra ID.

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 MS Entra ID.

Response:

On success:

HTTP 200

Response body for a shipment request without errors:

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

Response body for a shipment request with processing errors:

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

Process Shipments

GET /v1/operations/process-shipments (FIDO Connector API)

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.

Response: On success HTTP 204, no content body.

Resend PIN

GET /v1/operations/resend-pin/{shipment_id} (FIDO Connector API)

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

Response: On success HTTP 204, no content body.