API Reference

Each deployment of the Yubico FIDO Connector will have its own instance of the API described in the following.

Base URL: URL provided by the Container App This URL will be dependent on the URL provided by your container app service, and will be unique for each deployment.

Check Deployment Component Status

GET /v1/status

Provides the status of deployment components. 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. Response body:

{
 "AZURE_TABLES_ENDPOINT": "string",
 "AZURE_TABLES_SHIPMENTS_TABLE_NAME": "string",
 "AZURE_KEY_VAULT_ENDPOINT": "string",
 "AZURE_TENANT_ID": "string",
 "CRON_PROCESS_SHIPMENT_SCHEDULE": "string",
 "CRON_DATA_CLEANUP_SCHEDULE": "string",
 "CRON_DATA_CLEANUP_COMPLETED_DAYS": "string",
 "EMAIL_API_SEND_ENDPOINT": "string",
 "ENTRA_FIDO_API_CLIENT_ID": "string",
 "ENTRA_FIDO_API_VERSION": "string",
 "ENTRA_FIDO_API_CHALLENGE_TIMEOUT_MINUTES": "string",
 "FIDO_CONNECTOR_VERSION": "string"
 "LOGGING_LEVEL_COM_YUBICO": "string",
 "YE_API_BASE_URL": "string",
 "YE_JWKS_SIGN_ENDPOINT": "string",
 "YE_JWKS_TRANSPORT_ENDPOINT": "string"
}

Create Shipment Request

POST /v1/fpr/shipments

Provides the ability to place a request for shipment of pre-registered 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 YubiEnterprise 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}

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 YubiEnterprise with a Shipment ID. Fulfillment operations and credential creation are in progress with MS Entra ID.
complete	Response from YubiEnterprise 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 YubiEnterprise 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"
}

Resend PIN

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 status, this operation retrieves the PIN response from the YubiEnterprise Delivery service and decrypts it to resend the PIN email.

Response: On success HTTP 204, no content body.

Process Shipments

GET /v1/operations/process-shipments

Provides the ability to trigger on-demand the process of retrieving shipment responses from the YubiEnterprise 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.