.. api-reference.rst .. _api-reference: ============== 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-deploy-status: 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: .. code-block:: c# { "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: .. code-block:: c# { "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: * `Character limits for yubicoShipmentRequest `_ * `Values for product_id and inventory_product_id `_ * `Finding a customization_id in the Customer Portal `_ * `YubiEnterprise API Reference `_ **Request:** .. code-block:: c# { "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-status: 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. .. table:: +---------------------------+-----------------------------------------------+ | 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. .. table:: +---------------------------+------------------------------------------+ | 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*: .. code-block:: c# { "shipment_id": "string", "shipment_state": "string" } * Response body for a shipment request *with processing errors*: .. code-block:: c# { "shipment_id": "string", "shipment_state": "string", "error_kind": "string", "error_message": "string" } .. _process-shipments: 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: 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.