.. API_Onboarding_Playbook.rst .. _api-onboarding-pb-label: ============================ API Onboarding Playbook ============================ While the YubiEnterprise Delivery service can be run entirely through the Enterprise Console, it also comes with an API that provides the ability to extend the functionality to custom applications. The YubiEnterprise API is available for developers associated with customer organizations to integrate custom solutions that meet specific business requirements. The API calls are free of charge. The following sections describe the steps to get up and running and start working with the YubiEnterprise API to integrate with various platforms and solutions to deliver YubiKeys to end users. .. _api-caller-token-setup: API Caller Account Setup ================================== Here you will set up a sub-account for the application that will be calling the YubiEnterprise API, and generate an API token for authentication. Creating the account and the API token is done in the YubiEnterprise Console. For access to the Console for your organization, see :ref:`onboarding`. Prerequisites ---------------- * An email account for the application that will be calling the API. Ensure you have access to this email account since the Console login instructions will automatically be sent to this email address. * Access to the YubiEnterprise Console for your organization. * Console account with Console Owner permission to be able to add user accounts for your organization. .. note:: If your organization has Single sign-on (SSO) enabled, new users do not have to register. Users are immediately added to the organization in the *Active* state and can use the SSO service-provider-initiated login link to log in to the Console. For more information, see :ref:`sso-label`. Creating an Account --------------------- To create a user account with an API token for the API caller, do the following: 1. In the Console, create an account only to be used by the API caller, for example "my-app@example.com". For instructions, see :ref:`add-users-label`. 2. Assign the **Console Admin** role to the API caller's account. 3. Activate the new API caller account by clicking the login link in the email sent by the system, and follow the instructions to log in. .. note:: If your organization is using the single sign-on (SSO) method, you cannot change your password or your authentication method when you log in via SSO. You must use your credentials (username, password and YubiKey) to log in. Only then can you manage your credentials. 4. Associate a YubiKey for the API caller user account with the YubiEnterprise login credentials: a. On the upper right of any **Console** page, click the user icon of the API caller and select **Manage credentials** to open the **Account** page. b. Register at least one YubiKey (WebAuthn credential), for instructions see :ref:`webauthn-creds-label`. It is strongly recommended to register a second YubiKey in case the first one is lost. 5. Generate an API token for the API caller account as described in :ref:`lifecycle-label`. Make a copy of the API token and store it in a secure location for future usage. .. _lifecycle-label: Generating API Tokens ======================= The following section describes how to generate and manage API tokens used by API callers for authentication. To generate an API token for an account, do the following: 1. In the **Console**, click the organization name on the top of the left menu and select **Generate API token**. The **Manage API** token dialog appears showing the generated API token. .. image:: graphics/token-generate1.png :width: 200 3. Make a copy of the token and store it in a secure location. The token is shown *only at this time*, if you navigate away from the dialog you will no longer be able to view it. 4. Click **I have saved my token** to close the dialog. .. note:: The API token is tied to an account AND an organization. If a token does not exist for an account/organization, the menu option under the organization name will be **Generate API token**. If a token exists for an account/organization, the option will be **Manage API token**. Notification of API Token Expiry -------------------------------- API tokens expire one year after generation. Since a user (API caller) can have only one API token at a time, you must have a plan to roll-over to a new API token before the old one expires. The system automatically emails notification that the API token will expire: * 7 days beforehand * 1 day beforehand * On the day of expiry The notification is emailed to: * The user (holder) of the API token * The Console Owner (account owner, in cc) For more information about user roles, see :ref:`user-permissions-label`. .. note:: API tokens are only valid for one year at the time. Generating a new API token can be done at any time, and the generation of a new token will invalidate the old one. Tokens are bound to a user within an organization. If an application is using an API token generated by user A, then user B generating a new API token will not revoke the token generated by user A. .. _revoke-api-token: Revoking and Deleting API Tokens -------------------------------- An account can have 0 or 1 API access (machine) tokens. Once you have a token, it must be revoked and deleted before you can get a new one - *even if the old one has expired*. * **From the API:** You can add logic to renew the token by calling the API to get a new token before the existing one expires. The ``GET /auth/machine-token`` request revokes any existing tokens and creates a new machine token. Note that this could cause outages since ``GET`` in this instance is not a safe idempotent operation. * **From the Console:** While logged in to the Console as the user with the relevant API token, click the organization name and select **Manage API token**. Click **Revoke and delete active API token**. Once you revoke and delete the old token, the button to generate a new token appears. Organizations and API Tokens ------------------------------ API tokens are scoped to organizations. In the case of a multinational organization shipping YubiKeys to both Europe and United States/Canada, two separate organizations will be set up. In this case, two API tokens are required, one for the European organization, and one for the US/CAN organization. An individual user can have one role in one organization and the same or a different role in another organization. Even if the same individual is the Console Owner for both, there is a separate account for each. For example a user could be a Console Owner in a company's US/CAN organization and a Console Admin in the same company's EU organization. However, because these are separate organizations, if the user is logged in to the US/CAN YubiEnterprise, the same user cannot use that login to perform operations in the company's EU YubiEnterprise. The following is important regarding API tokens: * Protect access to the API token, because whoever is in possession of the token is authorized to perform API operations for your organization. * Accounts that use API tokens should have the *Admin* role, not the Owner role. This reduces the risk if the token is compromised, since the token has only the permissions associated with its role. * If a user is removed from an organization and has a token in that organization, the token is revoked. If a user is suspended, all tokens are revoked. The tokens are left untouched if the user is reset or the password is reset. .. _token-authentication: Authenticating with HTTP =========================== The YubiEnterprise API supports the HTTP Bearer Authentication scheme. In order to authenticate with HTTP, you must provide the API token in the header of the request. For instructions on how to generate an API token, see :ref:`lifecycle-label`. To use the API token, copy the token from its secure location and paste it into for example a curl command in a bash script as shown below. .. code-block:: Bash curl "https://api.console.yubico.com/v1/inventory" \ --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." Dates and Times =============== All dates and times in requests from the API are UTC in the `RFC-3339 `_ format. .. _working-with-YED-API-label: .. _custom-label: Working with the API ====================== Consider the points in the following before you begin working with the API. **Shipment flow** Make sure you understand the shipment request "happy path" flow and how to handle any error cases. For more information, see :ref:`shipments-label` and :ref:`best-practices-label`. **Customizations** YubiEnterprise Services include the possibility to custom program and pre-register YubiKeys. To learn more, see :ref:`customizations-label` and :ref:`prereg-label`. **Data model** The API exposes the YubiEnterprise Services data model. It is crucial to understand the difference between product and inventory identifiers. For more information, see :ref:`product-inventory-id`. **Low inventory** Prepare for initial stock running out by setting up pulling from the buffer or replacement stocks. Set up notification to admins of low inventory and automatically roll shipment requests to buffer and replacement stocks. **Testing** Use an isolated sandbox environment to reduce testing time. **API updates** The YubiEnterprise APIs occasionally have breaking changes. Therefore, monitor releases and spin up a project to prepare for migration before the change goes live. To get notified about API changes, see `Release Notes `_ and sign up for the `Yubico Developer Program mailing list `_. The following section provides a starting point and an introduction to the YubiEnterprise API. For full API details, see the `YubiEnterprise API Reference `_. .. _api-shipment-request: .. _single-request-sample: .. _api-tracking-label: .. _track-shipment-label: Shipments --------------------- * **Shipping to a single address:** Use the ``/shipments_exact`` API to ship products to a single address. This API can be used to handle shipment requests both directly from Yubico, or through resellers (channel partners). For more information about the API, see `Create a new shipment `_. .. note:: Shipping to multiple addresses can only be done from the Console. For more information, see :ref:`shipping-multiple-label`. * **Listing shipment requests:** ``GET /shipments_exact`` retrieves a list of all shipments. In cases where there are more than 100 shipments, iterate through the shipments based on the number of shipments provided by the ``total_count`` parameter. Use the optional parameters to obtain more records. For example: .. code-block:: bash // get the first 100 /shipments_exact?limit=100&offset=0 // get the second 100 /shipments_exact?limit=100&offset=100 // get the third 100 /shipments_exact?limit=100&offset=200 For more information about the API, see `List all shipments `_. * **Searching shipments:** The ``/shipments_exact/search-description`` route provides a description of the searchable fields on searchable resources. Returns a metadata object that describes which fields on ``GET /shipments_exact`` are searchable/sortable. For more information about the API, see `List searchable fields `_. * **Tracking shipments:** A successful response from the ``shipments_exact`` resource includes a ``shipment_id`` which can be used with ``GET /shipments_exact/{shipmentId}`` to get the tracking information for a specific shipment request. The response includes a ``tracking_number`` and a ``tracking_link`` for the shipment. For more information about the API, see `Get a shipments by its ID `_. Products --------------------- * **Identifying products:** The ``product_id`` parameter used with ``shipments_exact`` provides the unique identifier for a product in a shipment request. For example "4" represents a YubiKey 5C Nano. For input values, see :ref:`product-inventory-id`. For more information about the API, see `List products `_. .. _verify-inventory: .. _inv-ex-label: .. _custom-config-verify: Inventory --------------------- * **Identifying inventories:** ``inventory_product_id`` specifies which inventory you are drawing from in a shipment request, for example "Base" or "Advanced" tier, relating to the different types of :ref:`purchasing options `. For input values, see :ref:`api-ref-info`. ``inventory_type`` relates to the type of purchase such as "subscription" or ""non-subscription", see :ref:`inventory-options-label`. For input values, see :ref:`product-inv-type`. For more information about the API, see `inventory `_. * **Verifying inventory:** Before creating a shipment request, you can verify that all the products you intend to ship are currently available in your inventory to avoid shipping errors caused by lack of inventory. To get a complete list of products and inventories available to your organization, make a call to ``GET /inventory``. For more information about the API, see `inventory `_. * **Viewing inventory allocations:** On certain occasions, shippable quantities for a product might be allocated by Yubico, for example due to limited availability, see :ref:`shippable-inventory-label`. To view inventory allocations, make a call to ``GET /inventory-allocations``. The response includes an entry for each product with the ``remaining_allocated_inventory`` value representing the amount of keys left which can be shipped. For more information about the API, see `inventory allocations `_. For more API information, see the `YubiEnterprise API Reference `_. .. _api-integration-label: Integrations =============== For an organization that has fully integrated YubiEnterprise Delivery into its own internal systems via the APIs, the fulfillment experience is streamlined. The end user receives an email notifying them that they are eligible for a YubiKey and/or that they are required to use the key for specific system access. The email directs the end user to the corporate fulfillment system, for example ServiceNow. The YubiKey can be pre-registered and shipped directly to a specific end user who received a randomly generated PIN code separately. For shipping delivery integration examples, see :ref:`servicenow-label` and :ref:`prereg-label`. .. _yed-ss-wb: Delivery Self-Service Web Portal =============================================== The YubiEnterprise Delivery Self-Service Portal lets you create a web portal driven by the YubiEnterprise API that allows your customers to order from your organization's inventory. The example in this `GitHub repository `_ demonstrates an end-to-end solution with the ability to integrate the YubiEnterprise API into a web application that users in your enterprise (or beyond) could use to create YubiKey shipment requests drawing on your organization's inventory. In this project you will: 1. Stand up an environment in Amazon Web Services (AWS) to handle the server-side operations for the YubiEnterprise API and for handling user authentication/authorization 2. Use the YubiEnterprise API to create, delete, edit, and retrieve shipment requests as well as verify a shipment address 3. Create a front-end application for your end users to request shipment of a YubiKey that has been defaulted by your organization. .. note:: The project demonstrates a reference architecture showing how you can deploy your own YubiKey ordering portal using the YubiEnterprise API. The application should not be considered “production ready”, and does not implement the :ref:`FIDO2 Pre-Registration Shipments API `. Below are a few considerations to ensure the success of your integration. .. include:: includes/api-considerations.rst * **Configuration based on your security requirements:** This includes swapping the system out to use your identity provider, secrets management in AWS Lambda, and other controls used by your organization. * **People and process impacts to customer service:** If your application is intended for external end users then your internal CX team needs to be prepared to handle inquiries relating to YubiEnterprise Delivery/YubiKey. Either an internal team should be established and trained to handle these items OR you can engage Yubico Professional Services. * **Multi-region PO support:** The current demo is configured for a purchase order covering a single region. You need to use the proper API token for the user’s region. For example, North America / Canada is one region, EMEA is a different region and each have their own associated API token. For more information, see the `repository `_. ------------------------------------- To file a support ticket for YubiEnterprise Delivery, click `Support `_.