.. api-best-practices-faq.rst
===================================
API Reference Information
===================================
The following sections provide input values for various parameters used when working in the Enterprise Console as well as using the `YubiEnterprise API `_.
Country Codes
==============
Creating shipment requests to multiple addresses (bulk shipments) or through the API requires entering a two-letter country code as part of the shipment address. You can :ref:`download a CSV file ` containing country codes for all countries available for shipments for an organization. You can also use the API `GET /countries/csv `_ to get the correct country codes.
USPS Region/State Codes
=========================
Shipments going to the US, Canada, and US international military bases require a standardized two-letter USPS region code. For more information, see :ref:`usps-codes-label`.
.. _api-ref-info:
.. _product-inventory-id:
.. _inv-prod-id-label:
Product and Inventory Identifiers
==================================
The following table lists the ``product_id`` and ``inventory_product_id`` parameters that are used when creating shipment requests with the `shipments_exact `_ API.
.. important:: Not all product IDs are included in the table. To ensure you use the correct product ID when creating shipment requests, you should always obtain the product ID from the `GET /products `_ API call.
.. table:: **Stock/Inventory: product_id and inventory_product_id mapped to Product Name**
+------------------------+---------------------------------------------------+
|| product_id and/or || product_name |
|| inventory_product_id || |
+========================+===================================================+
| 1 | YubiKey 5 NFC |
+------------------------+---------------------------------------------------+
| 2 | YubiKey 5 Nano |
+------------------------+---------------------------------------------------+
| 3 | YubiKey 5C |
+------------------------+---------------------------------------------------+
| 4 | YubiKey 5C Nano |
+------------------------+---------------------------------------------------+
| 5 | YubiKey 5Ci |
+------------------------+---------------------------------------------------+
| 7 | Security Key NFC by Yubico |
+------------------------+---------------------------------------------------+
| 8 | YubiKey FIPS |
+------------------------+---------------------------------------------------+
| 9 | YubiKey Nano FIPS |
+------------------------+---------------------------------------------------+
| 10 | YubiKey C FIPS |
+------------------------+---------------------------------------------------+
| 11 | YubiKey C Nano FIPS |
+------------------------+---------------------------------------------------+
| 12 | Primary Subscr - Base Tier: Initial |
+------------------------+---------------------------------------------------+
| 13 | Primary Subscr - Base Tier: Buffer |
+------------------------+---------------------------------------------------+
| 14 | Primary Subscr - Base Tier: Replacement |
+------------------------+---------------------------------------------------+
| 15 | Primary Subscr - Adv. Tier: Initial |
+------------------------+---------------------------------------------------+
| 16 | Primary Subscr - Adv. Tier: Buffer |
+------------------------+---------------------------------------------------+
| 17 | Primary Subscr - Adv. Tier: Replacement |
+------------------------+---------------------------------------------------+
| 18 | Primary Subscr - Prem. Tier: Initial |
+------------------------+---------------------------------------------------+
| 19 | Primary Subscr - Prem. Tier: Buffer |
+------------------------+---------------------------------------------------+
| 20 | Primary Subscr - Prem. Tier: Replacement |
+------------------------+---------------------------------------------------+
| 21 | Primary Subscr - FIPS Tier: Initial |
+------------------------+---------------------------------------------------+
| 22 | Primary Subscr - FIPS Tier: Buffer |
+------------------------+---------------------------------------------------+
| 23 | Primary Subscr - FIPS Tier: Replacement |
+------------------------+---------------------------------------------------+
| 24 | Non-subscription - Base Tier |
+------------------------+---------------------------------------------------+
| 25 | Non-subscription - Advanced Tier |
+------------------------+---------------------------------------------------+
| 26 | Non-subscription - Premium Tier |
+------------------------+---------------------------------------------------+
| 27 | Non-subscription - FIPS Tier |
+------------------------+---------------------------------------------------+
| 28 | YubiKey Lanyard |
+------------------------+---------------------------------------------------+
| 29 | YubiKey 5C NFC |
+------------------------+---------------------------------------------------+
| 38 | Backup Subscr - Base Tier: Initial |
+------------------------+---------------------------------------------------+
| 39 | Backup Subscr - Base Tier: Buffer |
+------------------------+---------------------------------------------------+
| 40 | Backup Subscr - Base Tier: Replacement |
+------------------------+---------------------------------------------------+
| 41 | Backup Subscr - Adv. Tier: Initial |
+------------------------+---------------------------------------------------+
| 42 | Backup Subscr - Adv. Tier: Buffer |
+------------------------+---------------------------------------------------+
| 43 | Backup Subscr - Adv. Tier: Replacement |
+------------------------+---------------------------------------------------+
| 44 | Backup Subscr - Prem. Tier: Initial |
+------------------------+---------------------------------------------------+
| 45 | Backup Subscr - Prem. Tier: Buffer |
+------------------------+---------------------------------------------------+
| 46 | Backup Subscr - Prem. Tier: Replacement |
+------------------------+---------------------------------------------------+
| 47 | Backup Subscr - FIPS Tier: Initial |
+------------------------+---------------------------------------------------+
| 48 | Backup Subscr - FIPS Tier: Buffer |
+------------------------+---------------------------------------------------+
| 49 | Backup Subscr - FIPS Tier: Replacement |
+------------------------+---------------------------------------------------+
| 54 | YubiKey 5 NFC FIPS |
+------------------------+---------------------------------------------------+
| 55 | YubiKey 5C NFC FIPS |
+------------------------+---------------------------------------------------+
| 56 | YubiKey 5Ci FIPS |
+------------------------+---------------------------------------------------+
| 57 | YubiKey 5 Nano FIPS |
+------------------------+---------------------------------------------------+
| 58 | YubiKey 5C FIPS |
+------------------------+---------------------------------------------------+
| 59 | YubiKey 5C Nano FIPS |
+------------------------+---------------------------------------------------+
| 68 | YubiKey C Bio - FIDO Edition |
+------------------------+---------------------------------------------------+
| 69 | YubiKey Bio - FIDO Edition |
+------------------------+---------------------------------------------------+
| 82 | Security Key NFC by Yubico (Black) |
+------------------------+---------------------------------------------------+
| 83 | Security Key C NFC by Yubico (Black) |
+------------------------+---------------------------------------------------+
| 84 | Security Key NFC by Yubico - Enterprise Edition |
+------------------------+---------------------------------------------------+
| 85 | Security Key C NFC by Yubico - Enterprise Edition |
+------------------------+---------------------------------------------------+
| 86 | Base - Standard - Primary |
+------------------------+---------------------------------------------------+
| 87 | Base - Standard - Backup |
+------------------------+---------------------------------------------------+
| 88 | Base - Standard - Primary - Replacement |
+------------------------+---------------------------------------------------+
| 89 | Base - Standard - Backup - Replacement |
+------------------------+---------------------------------------------------+
| 90 | Base - Plus - Primary |
+------------------------+---------------------------------------------------+
| 91 | Base - Plus - Backup |
+------------------------+---------------------------------------------------+
| 92 | Base - Plus - Primary - Replacement |
+------------------------+---------------------------------------------------+
| 93 | Base - Plus - Backup - Replacement |
+------------------------+---------------------------------------------------+
| 94 | Base/Bio - Standard - Primary |
+------------------------+---------------------------------------------------+
| 95 | Base/Bio - Standard - Backup |
+------------------------+---------------------------------------------------+
| 96 | Base/Bio - Standard - Primary - Replacement |
+------------------------+---------------------------------------------------+
| 97 | Base/Bio - Standard - Backup - Replacement |
+------------------------+---------------------------------------------------+
| 98 | Base/Bio - Plus - Primary |
+------------------------+---------------------------------------------------+
| 99 | Base/Bio - Plus - Backup |
+------------------------+---------------------------------------------------+
| 100 | Base/Bio - Plus - Primary - Replacement |
+------------------------+---------------------------------------------------+
| 101 | Base/Bio - Plus - Backup - Replacement |
+------------------------+---------------------------------------------------+
| 102 | Advanced - Standard - Primary |
+------------------------+---------------------------------------------------+
| 103 | Advanced - Standard - Backup |
+------------------------+---------------------------------------------------+
| 104 | Advanced - Standard - Primary - Replacement |
+------------------------+---------------------------------------------------+
| 105 | Advanced - Standard - Backup - Replacement |
+------------------------+---------------------------------------------------+
| 106 | Advanced - Plus - Primary |
+------------------------+---------------------------------------------------+
| 107 | Advanced - Plus - Backup |
+------------------------+---------------------------------------------------+
| 108 | Advanced - Plus - Primary - Replacement |
+------------------------+---------------------------------------------------+
| 109 | Advanced - Plus - Backup - Replacement |
+------------------------+---------------------------------------------------+
| 110 | Advanced/Bio - Standard - Primary |
+------------------------+---------------------------------------------------+
| 111 | Advanced/Bio - Standard - Backup |
+------------------------+---------------------------------------------------+
| 112 | Advanced/Bio - Standard - Primary - Replacement |
+------------------------+---------------------------------------------------+
| 113 | Advanced/Bio - Standard - Backup - Replacement |
+------------------------+---------------------------------------------------+
| 114 | Advanced/Bio - Plus - Primary |
+------------------------+---------------------------------------------------+
| 115 | Advanced/Bio - Plus - Backup |
+------------------------+---------------------------------------------------+
| 116 | Advanced/Bio - Plus - Primary - Replacement |
+------------------------+---------------------------------------------------+
| 117 | Advanced/Bio - Plus - Backup - Replacement |
+------------------------+---------------------------------------------------+
| 118 | Compliance - Standard - Primary |
+------------------------+---------------------------------------------------+
| 119 | Compliance - Standard - Backup |
+------------------------+---------------------------------------------------+
| 120 | Compliance - Standard - Primary - Replacement |
+------------------------+---------------------------------------------------+
| 121 | Compliance - Standard - Backup - Replacement |
+------------------------+---------------------------------------------------+
| 122 | Compliance - Plus - Primary |
+------------------------+---------------------------------------------------+
| 123 | Compliance - Plus - Backup |
+------------------------+---------------------------------------------------+
| 124 | Compliance - Plus - Primary - Replacement |
+------------------------+---------------------------------------------------+
| 125 | Compliance - Plus - Backup - Replacement |
+------------------------+---------------------------------------------------+
| 152 | YubiKey Bio - Multi-protocol Edition |
+------------------------+---------------------------------------------------+
| 153 | YubiKey C Bio - Multi-protocol Edition |
+------------------------+---------------------------------------------------+
| 202 | YubiKey 5 NFC - Enhanced PIN |
+------------------------+---------------------------------------------------+
| 203 | YubiKey 5C NFC - Enhanced PIN |
+------------------------+---------------------------------------------------+
.. _product-inv-type:
Product Inventory Type Mapping
==================================
Input values for the ``inventory_type`` parameter used with ``/inventory``.
The following applies depending on the purchasing model your organization uses:
* For Subscription 2.0 purchases, use **3** or **5** for ``inventory_type``.
* For non-subscription (perpetual) purchases and/or lanyards, use **1** for ``inventory_type``.
* For Subscription 1.0 (legacy), use **3**, **4**, and/or **5** for ``inventory_type``.
* For non-subscription tiers of virtual keys (legacy), use **2** for ``inventory_type``.
.. table:: **Product <> inventory type mapping**
+--------------------------------------------------+-------------------------------+
|Product or Inventory Name shown on Purchase Order |Value to use for inventory_type|
+==================================================+===============================+
|YubiKey Lanyard |1 |
+--------------------------------------------------+-------------------------------+
|Security Key C NFC by Yubico (Black) |1 |
+--------------------------------------------------+-------------------------------+
|Security Key C NFC by Yubico - Enterprise Edition |1 |
+--------------------------------------------------+-------------------------------+
|Security Key NFC by Yubico (Black) |1 |
+--------------------------------------------------+-------------------------------+
|Security Key NFC by Yubico - Enterprise Edition |1 |
+--------------------------------------------------+-------------------------------+
|YubiKey 5 Nano |1 |
+--------------------------------------------------+-------------------------------+
|YubiKey 5 Nano FIPS |1 |
+--------------------------------------------------+-------------------------------+
|YubiKey 5 NFC |1 |
+--------------------------------------------------+-------------------------------+
|YubiKey 5 NFC FIPS |1 |
+--------------------------------------------------+-------------------------------+
|YubiKey 5 NFC - Enhanced PIN |1 |
+--------------------------------------------------+-------------------------------+
|YubiKey 5C |1 |
+--------------------------------------------------+-------------------------------+
|YubiKey 5C FIPS |1 |
+--------------------------------------------------+-------------------------------+
|YubiKey 5C Nano |1 |
+--------------------------------------------------+-------------------------------+
|YubiKey 5C Nano FIPS |1 |
+--------------------------------------------------+-------------------------------+
|YubiKey 5C NFC |1 |
+--------------------------------------------------+-------------------------------+
|YubiKey 5C NFC FIPS |1 |
+--------------------------------------------------+-------------------------------+
|YubiKey 5C NFC - Enhanced PIN |1 |
+--------------------------------------------------+-------------------------------+
|YubiKey 5Ci |1 |
+--------------------------------------------------+-------------------------------+
|YubiKey 5Ci FIPS |1 |
+--------------------------------------------------+-------------------------------+
|YubiKey Bio - FIDO Edition |1 |
+--------------------------------------------------+-------------------------------+
|YubiKey C Bio - FIDO Edition |1 |
+--------------------------------------------------+-------------------------------+
|Advanced - Plus - Backup |3 |
+--------------------------------------------------+-------------------------------+
|Advanced - Plus - Backup - Replacement |5 |
+--------------------------------------------------+-------------------------------+
|Advanced - Plus - Primary |3 |
+--------------------------------------------------+-------------------------------+
|Advanced - Plus - Primary - Replacement |5 |
+--------------------------------------------------+-------------------------------+
|Advanced - Standard - Backup |3 |
+--------------------------------------------------+-------------------------------+
|Advanced - Standard - Backup - Replacement |5 |
+--------------------------------------------------+-------------------------------+
|Advanced - Standard - Primary |3 |
+--------------------------------------------------+-------------------------------+
|Advanced - Standard - Primary - Replacement |5 |
+--------------------------------------------------+-------------------------------+
|Advanced/Bio - Plus - Backup |3 |
+--------------------------------------------------+-------------------------------+
|Advanced/Bio - Plus - Backup - Replacement |5 |
+--------------------------------------------------+-------------------------------+
|Advanced/Bio - Plus - Primary |3 |
+--------------------------------------------------+-------------------------------+
|Advanced/Bio - Plus - Primary - Replacement |5 |
+--------------------------------------------------+-------------------------------+
|Advanced/Bio - Standard - Backup |3 |
+--------------------------------------------------+-------------------------------+
|Advanced/Bio - Standard - Backup - Replacement |5 |
+--------------------------------------------------+-------------------------------+
|Advanced/Bio - Standard - Primary |3 |
+--------------------------------------------------+-------------------------------+
|Advanced/Bio - Standard - Primary - Replacement |5 |
+--------------------------------------------------+-------------------------------+
|Backup Subscr - Adv. Tier: Buffer |4 |
+--------------------------------------------------+-------------------------------+
|Backup Subscr - Adv. Tier: Initial |3 |
+--------------------------------------------------+-------------------------------+
|Backup Subscr - Adv. Tier: Replacement |5 |
+--------------------------------------------------+-------------------------------+
|Backup Subscr - Base Tier: Buffer |4 |
+--------------------------------------------------+-------------------------------+
|Backup Subscr - Base Tier: Initial |3 |
+--------------------------------------------------+-------------------------------+
|Backup Subscr - Base Tier: Replacement |5 |
+--------------------------------------------------+-------------------------------+
|Backup Subscr - FIPS Tier: Buffer |4 |
+--------------------------------------------------+-------------------------------+
|Backup Subscr - FIPS Tier: Initial |3 |
+--------------------------------------------------+-------------------------------+
|Backup Subscr - FIPS Tier: Replacement |5 |
+--------------------------------------------------+-------------------------------+
|Backup Subscr - Prem. Tier: Buffer |4 |
+--------------------------------------------------+-------------------------------+
|Backup Subscr - Prem. Tier: Initial |3 |
+--------------------------------------------------+-------------------------------+
|Backup Subscr - Prem. Tier: Replacement |5 |
+--------------------------------------------------+-------------------------------+
|Base - Plus - Backup |3 |
+--------------------------------------------------+-------------------------------+
|Base - Plus - Backup - Replacement |5 |
+--------------------------------------------------+-------------------------------+
|Base - Plus - Primary |3 |
+--------------------------------------------------+-------------------------------+
|Base - Plus - Primary - Replacement |5 |
+--------------------------------------------------+-------------------------------+
|Base - Standard - Backup |3 |
+--------------------------------------------------+-------------------------------+
|Base - Standard - Backup - Replacement |5 |
+--------------------------------------------------+-------------------------------+
|Base - Standard - Primary |3 |
+--------------------------------------------------+-------------------------------+
|Base - Standard - Primary - Replacement |5 |
+--------------------------------------------------+-------------------------------+
|Base/Bio - Plus - Backup |3 |
+--------------------------------------------------+-------------------------------+
|Base/Bio - Plus - Backup - Replacement |5 |
+--------------------------------------------------+-------------------------------+
|Base/Bio - Plus - Primary |3 |
+--------------------------------------------------+-------------------------------+
|Base/Bio - Plus - Primary - Replacement |5 |
+--------------------------------------------------+-------------------------------+
|Base/Bio - Standard - Backup |3 |
+--------------------------------------------------+-------------------------------+
|Base/Bio - Standard - Backup - Replacement |5 |
+--------------------------------------------------+-------------------------------+
|Base/Bio - Standard - Primary |3 |
+--------------------------------------------------+-------------------------------+
|Base/Bio - Standard - Primary - Replacement |5 |
+--------------------------------------------------+-------------------------------+
|Compliance - Plus - Backup |3 |
+--------------------------------------------------+-------------------------------+
|Compliance - Plus - Backup - Replacement |5 |
+--------------------------------------------------+-------------------------------+
|Compliance - Plus - Primary |3 |
+--------------------------------------------------+-------------------------------+
|Compliance - Plus - Primary - Replacement |5 |
+--------------------------------------------------+-------------------------------+
|Compliance - Standard - Backup |3 |
+--------------------------------------------------+-------------------------------+
|Compliance - Standard - Backup - Replacement |5 |
+--------------------------------------------------+-------------------------------+
|Compliance - Standard - Primary |3 |
+--------------------------------------------------+-------------------------------+
|Compliance - Standard - Primary - Replacement |5 |
+--------------------------------------------------+-------------------------------+
|Non-subscription - Advanced Tier |2 |
+--------------------------------------------------+-------------------------------+
|Non-subscription - Base Tier |2 |
+--------------------------------------------------+-------------------------------+
|Non-subscription - FIPS Tier |2 |
+--------------------------------------------------+-------------------------------+
|Non-subscription - Premium Tier |2 |
+--------------------------------------------------+-------------------------------+
|Primary Subscr - Adv. Tier: Buffer |4 |
+--------------------------------------------------+-------------------------------+
|Primary Subscr - Adv. Tier: Initial |3 |
+--------------------------------------------------+-------------------------------+
|Primary Subscr - Adv. Tier: Replacement |5 |
+--------------------------------------------------+-------------------------------+
|Primary Subscr - Base Tier: Buffer |4 |
+--------------------------------------------------+-------------------------------+
|Primary Subscr - Base Tier: Initial |3 |
+--------------------------------------------------+-------------------------------+
|Primary Subscr - Base Tier: Replacement |5 |
+--------------------------------------------------+-------------------------------+
|Primary Subscr - FIPS Tier: Buffer |4 |
+--------------------------------------------------+-------------------------------+
|Primary Subscr - FIPS Tier: Initial |3 |
+--------------------------------------------------+-------------------------------+
|Primary Subscr - FIPS Tier: Replacement |5 |
+--------------------------------------------------+-------------------------------+
|Primary Subscr - Prem. Tier: Buffer |4 |
+--------------------------------------------------+-------------------------------+
|Primary Subscr - Prem. Tier: Initial |3 |
+--------------------------------------------------+-------------------------------+
|Primary Subscr - Prem. Tier: Replacement |5 |
+--------------------------------------------------+-------------------------------+
.. _shipment-status-label:
Shipment Status Codes
==================================
Shipment state codes and associated status messages. For information on how to resolve issues with shipment requests, see :ref:`solve-shipment-issue`.
.. include:: includes/shipment-states-incl.rst
.. _shipment-error-msg-label:
Shipment Error Messages
==================================
Error messages accessible via the API. The Explanation column provides the message source: YubiEnterprise Delivery system for internal messages, US Validation for the US Postal Service, and International Validation. Messages originating from the last two are passed on by YubiEnterprise Delivery.
.. include:: includes/shipment-status-messages.rst
Response Request Status Codes
==================================
Explanations of common status codes in responses from the YubiEnterprise API.
.. table:: **Status codes**
+-----+------------+--------------------------------------------------------------------------------------+
|Code |Meaning |Explanation |
+=====+============+======================================================================================+
|200 |OK | | The request was successful and the response |
| | | | body contains the representation requested |
+-----+------------+--------------------------------------------------------------------------------------+
|302 |FOUND | | A common redirect response; this will |
| | | | redirect to the OAUTH login page |
+-----+------------+--------------------------------------------------------------------------------------+
|400 |BAD REQUEST |API validation failed for the request |
+-----+------------+--------------------------------------------------------------------------------------+
|403 |FORBIDDEN | | API denied permission to fulfill the |
| | | | requested resource |
+-----+------------+--------------------------------------------------------------------------------------+
|404 |NOT FOUND |The requested resource was not found |
+-----+------------+--------------------------------------------------------------------------------------+
.. _deprecated-api-list-label:
.. _deprecated-apis-label:
.. _api-bulk-shipment-deprecated-label:
.. _multiple-label:
Deprecated APIs: Overview
=========================
The following tables list deprecated APIs and recommended replacements if available. Deprecated APIs will eventually be removed, and it is therefore recommended that existing implementations be updated. Ensure that your implementation is not using a deprecated version of the API. New implementations should use the recommended replacement methods.
.. include:: includes/deprecated-address-line3.rst
.. include:: includes/api-bulk-shipment-deprecated.rst
.. include:: includes/deprecated-apis+replacements.rst
**User Management**
Starting with release 2.11.0 new APIs for user management were introduced. The old APIs are deprecated and will be available until November 23, 2024.
.. table::
+---------------------------------------------------------+-------------------------------------------------------------+
|Deprecated |Replacement |
+=========================================================+=============================================================+
|| ``POST /v1/users/{userId}`` || ``POST /v1/users/{userId}`` |
|| || body ``{"roles": ["org-owner","distributor","reseller"]}`` |
+---------------------------------------------------------+-------------------------------------------------------------+
|| ``POST /v1/organization/users/reset/{email}`` || ``POST /v1/users/{userId}`` |
|| || body ``{"action": "reset-user"}`` |
+---------------------------------------------------------+-------------------------------------------------------------+
|| ``POST /v1/organization/users/reset-password/{email}`` || ``POST /v1/users/{userId}`` |
|| || body ``{"action": "reset-password"}`` |
+---------------------------------------------------------+-------------------------------------------------------------+
|| ``DELETE /v1/organization/users/{email}`` || ``DELETE /v1/users/{userId}`` |
|| || |
+---------------------------------------------------------+-------------------------------------------------------------+
-------------------------------------
To file a support ticket for YubiEnterprise Delivery, click `Support `_.