.. api-reference.rst .. _api-reference: ============================== 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-deploy-status: 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: .. code-block:: c# { "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. ``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"``. ``reseller_organization_id`` is the optional 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. All other fields in request are required. Input value references: * `Character limits for yubicoShipmentRequest `_ * `Values for product_id and inventory_product_id `_ * `Finding a customization_id in the Enterprise Console `_ * `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 }, "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 } ] } } **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-status: 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. .. table:: +---------------------------+------------------------------------------+ | 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. .. 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 YubiEnterprise 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" } .. _resend-pin: 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: 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.