API Reference

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

Authentication

To authenticate to the Yubico FIDO Pre-reg and Delivery services, you will use a Yubico API authentication token (YED_API_Token). To create a Yubico API authentication token, sign in to the Customer Portal with the account for the application that will be calling the FIDO Pre-reg and Delivery services (YubiEnterprise API). See API Caller Account Setup.

FIDO Connector API

The FIDO Connector is deployed in the customer’s Azure environment, and provides APIs for interacting with the IdP. 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 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 pre-programming of credentials onto a YubiKey using a mobile device. If desired, the request can include shipment requests for one or more pre-enrolled YubiKeys. You can add multiple credentials to the same YubiKey, and request pre-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 pre-programmed FIDO Pre-reg shipments, while authenticators is used for local on-site pre-programming of credentials onto a YubiKey without involving any shipping.

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.

Endpoint: POST /v2/credential-requests

Request body

  {
 "recipient": {
   "email": "required",
   "first_name": "required",
   "last_name": "required",
   "company": "optional",
   "telephone": "required",
   "external_id": "optional"
 },
 "enrollment_contacts": {
   "emails_to": [
     "required"
   ]
 },
 "shipment": {
   "delivery_type": 1,
   "reseller_organization_id": "optional",
   "customer_reference": "optional",
   "address_validation_bypass": false,
   "mailing_address": {
     "street_line1": "required",
     "street_line2": "optional",
     "postal_code": "required",
     "city": "required",
     "region": "optional",
     "country_code": "required"
   },
   "shipment_items": [
     {
       "name": "optional",
       "customization_id": "optional",
       "product_id": "required",
       "inventory_product_id": "required",
       "pin_request": {
         "length": 0,
         "type": "required"
       },
       "credentials": [
         {
           "idp_id": "idp-1",
           "relying_party_id": "rp-1",
           "user_id": "user-id-1"
         },
         {
           "idp_id": "idp-2",
           "relying_party_id": "rp-2",
           "user_id": "user-id-2"
         }
       ]
     }
   ]
 },
 "authenticators": [
   {
     "name": "optional",
     "customization_id": "optional",
     "preferred_authenticator_type": "hardware",
     "pin_request": {
       "min_length": 0,
       "entry_method": "optional",
       "delivery_method": "optional"
     },
     "credentials": [
       {
         "idp_id": "idp-1",
         "relying_party_id": "rp-1",
         "user_id": "user-id-1"
       },
       {
         "idp_id": "idp-2",
         "relying_party_id": "rp-2",
         "user_id": "user-id-2"
       }
     ]
   }
 ]
}

Parameters

  • recipient Information used by the Delivery service.

  • recipient.external_id Optional, used to track requests.

  • enrollment_contacts. Required, a list of email addresses to which the PIN can be sent. Provided email addresses must be valid.

  • shipment Optional, required if authenticators is not provided (shipment-only request). Both shipment and authenticators can be included in a request.

  • shipment.delivery_type Optional, if provided should be either “1” - standard (default), or “2” - expedited.

  • shipment.customer_reference Optional, customer-provided reference information associated with the shipment.

  • shipment.address_validation_bypass Optional, see Address Validation Override.

  • shipment_items.name Optional, YubiKey name, if not provided, the default ”Pre-Reg YubiKey” will be used.

  • shipment_items.customization_id Optional, associated Customization ID for the pre-programmed YubiKey, must not be blank if provided.

  • shipment_items.pin_request Optional, defines whether a PIN is required or not. See pin_request for supported parameters. 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, default values are “6” for both shipment items and authenticators.

  • shipment_items.credentials Required, IDs of the associated IdP(s), authenticators, and end users, cannot contain items with repeated pair of user_id + relying_party_id.

  • authenticators Optional, required if shipment is not provided (credential-only request). Both shipment and authenticators can be included in a request.

  • authenticators.name Optional, provides the ability to add a custom authenticator “nick name” in the request. If not provided, the default ”Pre-Reg YubiKey” will be used.

  • authenticator.customization_id Optional, associated Customization ID for the credential, if provided must not be blank.

  • authenticators.preferred_authenticator_type Optional, if provided should be either "hardware" (default) or "software".

  • pin_request.min_length Optional, if provided, should be equal to or greater than “4” and equal or less than “63”. The default value is “6”.

  • pin_request.entry_method Optional, if provided, should be either “generated” or “user_entered” where an end user adds their own PIN in an on-site credential issuance workflow, to avoid sending the PIN via email. Only “generated” is supported for shipments of physical YubiKeys.

  • pin_request.delivery_method Optional, if provided should be either “none”, “app”, or “email”.

  • authenticators.credentials Required, cannot contain items with repeated pair of user_id + relying_party_id.

    Note

    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.

  • credentials.idp_id Optional, default value is configurable through the IDP_DEFAULT environment variable, see the identity provider integration guides identity provider integration guides.

  • credential.relying_party_id Optional, default value can be configured in the IdP implementation, see the identity provider integration guides identity provider integration guides.

For input values in shipment requests, see the following references:

Success response body

{
"data": {
  "credential_request_id": "123-abc-...",
  "shipment_id": "123-xyz..."
}
  • 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: Shipment-only Request

The following shows a request for a single pre-enrolled YubiKey shipment to an end user. The YubiKey is pre-programmed by Yubico and shipped to the end user. The PIN is delivered via the FIDO Connector.

 {
 "recipient": {
   "email": "username@yubico.com",
   "first_name": "Firstname",
   "last_name": "Lastname",
   "company": "Company",
   "telephone": "999999999",
   "external_id": "username@yubico.com"
 },
 "enrollment_contacts": {
   "emails_to": [
     "user@yubico.com"
   ]
 },
 "shipment": {
   "delivery_type": 1,
   "customer_reference": "customer reference",
   "address_validation_bypass": false,
   "mailing_address": {
     "street_line1": "St Example, 123",
     "street_line2": "Unit Example",
     "postal_code": "1234567",
     "city": "Santa Clara",
     "region": "CA",
     "country_code": "US"
   },
   "shipment_items": [
     // Uncomment this to submit 2 shipment items
     // {
     //   "name": "Backup YubiKey",
     //   "customization_id": "123456",
     //   "product_id": "29",
     //   "inventory_product_id": "133",
     //   "pin_request": {
     //     "min_length": 8,
     //     "entry_method": "generated",
     //     "delivery_method": "email"
     //   },
     //   "credentials": [
     //     // Uncomment to submit 2 credentials
     //     // {
     //     //   "user_id": "test_user_b@yubico.com"
     //     // },
     //     {
     //       "user_id": "test_user_a@yubico.com"
     //     }
     //   ]
     // },
     {
       "name": "Primary YubiKey",
       "customization_id": "123456",
       "product_id": "1",
       "inventory_product_id": "133",
       "pin_request": {
         "min_length": 8,
         "entry_method": "generated",
         "delivery_method": "email"
       },
       "credentials": [
         // Uncomment to submit 2 credentials
         // {
         //   "user_id": "test_user_b@yubic.com"
         // },
         {
           "user_id": "test_user_a@yubico.com"
         }
       ]
     }
   ]
 }
}

Example: Shipment and Credential Request

The following shows a request for a single user account shipping one pre-enrolled YubiKey and a second YubiKey enrolled by a trusted agent using a mobile app. The shipped YubiKey PIN will be provided via email by the FIDO Connector and the YubiKey PIN enrolled by a trusted agent will be provided in person.

 {
 "recipient": {
   "email": "username@yubico.com",
   "first_name": "Firstname",
   "last_name": "Lastname",
   "company": "Yubico",
   "telephone": "999999999",
   "external_id": "username@yubico.com"
 },
 "enrollment_contacts": {
   "emails_to": [
     "username@yubico.com"
   ]
 },
 "shipment": {
   "delivery_type": 1,
   "customer_reference": "customer reference",
   "address_validation_bypass": false,
   "mailing_address": {
     "street_line1": "St Example, 123",
     "street_line2": "Unit Example",
     "postal_code": "1234567",
     "city": "Santa Clara",
     "region": "CA",
     "country_code": "US"
   },
   "shipment_items": [
     {
       "name": "Backup YubiKey",
       "customization_id": "123456",
       "product_id": "1",
       "inventory_product_id": "133",
       "pin_request": {
         "min_length": 12,
         "entry_method": "generated",
         "delivery_method": "email"
       },
       "credentials": [
         {
           "user_id": "test_user_a@yubico.com"
         }
       ]
     }
   ]
 },
 "authenticators": [
   {
     "name": "Primary YubiKey",
     "customization_id": "123456",
     "preferred_authenticator_type": "hardware",
     "pin_request": {
       "min_length": 12,
       "entry_method": "user_entered",
       "delivery_method": "app"
     },
     "credentials": [
       {
         "user_id": "test_user_a@yubico.com"
       }
     ]
   }
 ]
}

Example: Multiple Credential-only Request

The following shows a credential-only request by a trusted agent for creating credentials for two different users, “User 1” and “User 2”, on a default IdP. The credentials are added to a YubiKey (authenticator type “hardware”), and as a mobile app passkey (authenticator type “software”).

In this scenario, on-site pre-programming is used where the end user enters their desired PIN (entry method “user_entered”). The trusted agent already has the physical YubiKey, so no shipment is involved in this case.

The PIN for the YubiKey Credential is delivered to the end user via email. The PIN for the mobile app passkey is delivered in the app.

  • Uncomment the authenticator to add a second authenticator with preferred_authenticator_type as “hardware”.
  • Uncomment the credential object in the authenticators`.credentials array to add a second credential.
  • For each authenticator with preferred_authenticator_type “software”, an email with the fulfillment QR code will be sent to all emails in enrollment_contacts.emails_to.
 {
 "recipient": {
   "email": "username@yubico.com",
   "first_name": "Firstname",
   "last_name": "Lastname",
   "company": "Company",
   "telephone": "999999999",
   "external_id": "username@yubico.com"
 },
 "enrollment_contacts": {
   "emails_to": [
     "name1@yubico.com"
   ]
 },
 "authenticators": [
   // Uncomment to submit 2 authenticators
   // {
   //   "name": "User 2",
   //   "customization_id": "123456",
   //   "preferred_authenticator_type": "hardware",
   //   "pin_request": {
   //     "min_length": 8,
   //     "entry_method": "user_entered",
   //     "delivery_method": "email"
   //   },
   //   "credentials": [
   //     // Uncomment to submit 2 credentials
   //     // {
   //     //   "user_id": "user2@yubico.com"
   //     // },
   //     {
   //       "user_id": "user1@yubico.com"
   //     }
   //   ]
   // },
   {
     "name": "User 1",
     "customization_id": "123456",
     "preferred_authenticator_type": "software",
     "pin_request": {
       "min_length": 8,
       "entry_method": "user_entered",
       "delivery_method": "app"
     },
     "credentials": [
       // Uncomment to submit 2 credentials
       // {
       //   "user_id": "user2@yubico.com"
       // },
       {
         "user_id": "user1@yubico.com"
       }
     ]
   }
 ]
}

Version 1 - Create Credential Request

Version 1 of the Create Credential Request API is a credential-only request supporting local on-site pre-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": "{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}"]
   }
}

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 pre-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": "required",
       "state": "received",
       "authenticators": [
       {
           "id": "required",
           "name": "required",
           "state": "processing",
           "credentials": [
           {
               "idp_id": "idp-1",
               "relying_party_id": "rp-1",
               "user_id": "user-id-1",
               "state": "activation_pending",
               "error_message": "optional"
           }
           ]
       }
       ],
       "shipment": {
       “shipment_id”: “required”,
       "shipment_items": [
           {
           "id": "required",
           "name": "required",
           "state": "processing",
           "credentials": [
               {
               "idp_id": "idp-1",
               "relying_party_id": "rp-1",
               "user_id": "user-id-1",
               "state": "activation_pending",
               "error_message": "optional"
               },
               {
               "idp_id": "idp-2",
               "relying_party_id": "rp-2",
               "user_id": "user-id-2",
               "state": "activation_pending",
               "error_message": "optional"
               }
           ]
           }
       ],
       "mailing_address": {
           "street_line1": "required",
           "street_line2": "optional",
           "postal_code": "required",
           "city": "required",
           "region": "required",
           "country_code": "required"
       }
     }
   }
}

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": "{credential_request_id}",
 "credential_request_state": "processing",
 "credentials": [
     {
         "user_id": "{user_id}",
         "relying_party_id": "{relying_party}",
         "idp_id": "{idp}",
         "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 Pre-reg API

The FIDO Pre-reg API is an extension of the YubiEnterprise API for shipments of pre-enrolled YubiKeys. For example, the POST/v1/fpr/shipments creates a shipment of a pre-enrolled YubiKey, pre-programmed by Yubico. The 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://api.console.yubico.com/

Note

The FIDO Pre-reg API only supports shipment requests for YubiKeys pre-programmed in Yubico facilities, and only one pre-enrolled YubKey can be included in each request. To be able to request multiple pre-programmed YubiKeys in one request, as well as benefit from other enhanced features, use the FIDO Connector v2 API.

Create Shipment Request

VERSION 1.0

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

Endpoint: POST /v1/fpr/shipments

Request body

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

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

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": "string",
 "shipment_state": "string"
}

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.