API Reference

This section describes the different APIs used in integrations with the Yubico Delivery and pre-enrollment services to request shipping and pre-enrollment of YubiKeys.

The following APIs are available:

• The FIDO Pre-reg API is an extension of the YubiEnterprise API for the Yubico Delivery service, and is used to request shipment of pre-enrolled YubiKeys to end users.
• The FIDO Connector API is used by the FIDO Connector app to orchestrate interactions between the IdP (Identity Provider) and Yubico services.
• The Credential Requests API provides the ability for trusted agents to request on-site pre-programming of credentials onto a YubiKey.

FIDO Pre-reg API

The FIDO Pre-reg API lets you create a request for shipment of a pre-enrolled YubiKey, generating a fulfillment request to Yubico. The API supports the communication of encrypted credential registration data between the customer environment orchestration and Yubico.

The FIDO Pre-reg API is an extension of the YubiEnterprise Delivery service API . 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.

Base URL: https://portal.yubico.com/api/v1/fpr/shipments

Create Shipment Request

POST /v1/fpr/shipments

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

• Address field limits for shipment requests
• Values for Product and Inventory IDs
• Finding a Customization ID in the Customer Portal

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

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

FIDO Connector API

The FIDO Connector API is used by the FIDO Connector which is deployed in the customer’s Azure environment. The API is called from processes and workflows to handle orchestration of credential requests and shipment requests.

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. API calls will go to something like in the example below.

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

Check Deployment Status

GET /v1/status

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

Example with PingOne AIC 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"
"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"
"PING_AIC_DEFAULT_RELYING_PARTY": "some-default-rp.com"
"PING_AIC_API_BASE_URL": "https://..."
"PING_AIC_AUTH_BASE_URL": "https://..."
"PING_AIC_CLIENT_ID": "my-client-id...,
"PING_AIC_REALM": "my-realm..."
"PING_AIC_JOURNEY": "my-journey-name..."
"PING_AIC_SCOPE": "write read share print copy delete manage edit"

Process Shipments

GET /v1/operations/process-shipments

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.

Process Credential Request

POST /v1/operations/process-credential-requests

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.

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 or pending_pin_sending 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.

Credential Requests API

The FIDO Pre-reg Credential Request API lets trusted agents create requests for on-site pre-programming of credentials onto a YubiKey using for example a mobile device.

The base URL for the Credential Requests API is derived from the base URL of the FIDO Connector which is unique for each deployment environment. The credential request API calls will go to something like in the example below.

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

Create Credential Request

POST /v1/credential-requests

Provides the ability to create a request for pre-programming of credentials onto a YubiKey. Optionally, you can 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.

Request:

 {
   "recipient": {
       "firstname": "{firstname}",
       "lastname": "{lastname}",
       "email": "{recipient_email}"
   },
   "credentials": [
       {
           "user_id": "{user_id}"
       }
   ],
   "pin_request": {
       "min_length": {min_length}
       "entry_method": "user_entered"
   },
   "authenticator_name": "{authenticator name}",
   "customization_id": "{customization_id}",
   "enrollment_contacts": {
       "emails_to": ["{enrollment_contact_email}"]
   }
}

For PingOne AIC, default relying party is an optional configuration in the request. If credentials.relying_party_id is present in the request, then this will be used. Otherwise, if the PingOne AIC default relying party is configured in the FIDO Connector through the PING_AIC_DEFAULT_RELYING_PARTY environment variable, then this will be used. If non of these are provided, the Journey’s Relying-Party Identifier configuration is used, see Configuring Environment Variables.

Adding "entry_method": "user_entered" to the request lets an end user add their own PIN in the remote credential issuance workflow, to avoid sending the PIN via email. In this scenario, an IT Admin is processing the credential request with the end user in the same location. If entry_method": "user_entered is enabled in the request, the enrollment flow will display a prompt, and the device is handed over to the end user who enter their PIN.

If allowed by the IdP, authenticator_name optionally provides the ability to add a custom authenticator “nick name” in a pre-enrollment request, similarly to providing a custom passkey name for yubikey_name in a pre-enroll shipment request, see Create Shipment Request.

Get Credential Request Status

GET /v1/credential-requests/{credential_request_id}

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

Request:

{
 "credential_request_id": "{credential_request_id}",
 "credential_request_state": "processing",
 "credentials": [
     {
         "user_id": "{user_id}",
         "relying_party_id": "{reling_party}",
         "idp_id": "{idp}",
         "credential_state": "activation_pending"
     }
 ]
}