.. API_Onboarding_Playbook.rst .. _api-onboarding-pb-label: ======================== API Onboarding Playbook ======================== .. _working-with-YED-API-label: While YubiEnterprise Delivery can be driven entirely through the prebuilt console, it also comes with an API that provides the ability to extend the functionality to custom applications. The YubiEnterprise Delivery API enables your organization's developers to integrate the API into custom solutions that meet the specific requirements of your business. The following points are important to master before working with the API: **Shipment flow** Make sure you understand the shipment request happy path flow and how to handle the error cases. **Testing** Use an isolated sandbox environment to reduce testing time. **Data model complexity** The API exposes the YubiEnterprise Services data model. It is crucial to understand the difference between product identifiers and form factor identifiers. **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. **App maintenance** The YubiEnterprise Services API occasionally makes breaking changes. Therefore, monitor all release notes and spin up a project to prepare for migration before the change goes live. .. _yed-ss-wb: YubiEnterprise Delivery Self-Service Web Portal =============================================== This `example in YubicoLabs GitHub repository `_ will demonstrate an end-to-end solution with the ability to integrate the YubiEnterprise Delivery 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 Delivery API and for handling user authentication/authorization 2. Use the YubiEnterprise Delivery 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. Guide ----- `GitHub Repository `_: This repository contains the code and steps required to stand up an application in AWS capable of sending requests to your organization's instance of YubiEnterprise Delivery. Considerations -------------- The aim of this guide is to demonstrate a barebones application that utilizes the YubiEnterprise Delivery API. The application should not be considered “production ready”. Below are a few of the considerations to keep in mind 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 will need to use the proper API token for the user’s region, e.g. North America / Canada is one region, EMEA is a different region and each have their own associated API token. More information can be found `here `_. .. _api-integration-label: ServiceNow Integration ====================== 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 (e.g., ServiceNow). For more information, see :ref:`servicenow-label`. .. _api-caller-token-setup: Setting up API Caller and Token =============================== Consider the following regarding API tokens: .. include:: includes/api-access-control.rst Follow the steps below to set up an API caller user account with an associated API token. :Step 1: Set up a subaccount for the application that will be calling the YubiEnterprise Delivery API. For instructions regarding b and c below, see :ref:`add-users-label`. a. Set up an email account for the application that will be calling the API. Ensure that you have access to it. An email with login instructions will automatically be sent to this email address by the system. b. In the Console, create an account only to be used by the API caller, for example, my-app@example.com. c. Assign the **Console Admin** role to the API caller's account. :Step 2: Activate the new API caller account by clicking the login link in the email sent by the system, and follow the instructions. :Step 3: Associate a YubiKey for the API caller 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 a YubiKey as a roaming credential, see :ref:`webauthn-creds-label`. Consider registering a second YubiKey in case the first one is lost. :Step 4: Generate the API token: a. In the **Console**, click the organization name in the top left corner and select **Manage API token**. b. Make a copy of the token and store it in a secure location. For more information on API tokens, see :ref:`lifecycle-label`. Authenticating with HTTP ------------------------ The YubiEnterprise Delivery API supports the HTTP Bearer Authentication scheme. In order to authenticate with HTTP, you must provide your API token in the header of the request. Copy your API token from its secure location and paste it into into a curl command in a bash script as shown below (the full token is not shown here). .. code-block:: Bash curl "https://api.console.yubico.com/v1/inventory" \ --header "Authorization: Bearer eyJhb..." Once you are logged into YubiEnterprise Delivery, you can view the YubiEnterprise Delivery public API at https://console.yubico.com/apidocs. Dates and Times =============== All dates and times in requests from the API are UTC in the `RFC-3339 `_ format. Users, Roles, and Organizations =============================== Since API tokens are scoped to organizations, if an organization is shipping YubiKeys to both United States/Canada and to Europe, two API tokens are required: one for the US/CAN organization and one for the European organization. An individual user can have one role in one organization and the same or a different role in another organization; for example, user Jan could be an owner in a company's US/CAN organization and an Admin in the same company's EU organization. However, because these are separate organizations, if Jan is logged in to the US/CAN YubiEnterprise, Jan cannot use that login to perform operations in the company's EU YubiEnterprise. Because it is possible to change the role of a user already in an organization, it is worth noting that deleting a user both: * Deletes that user's association with the organization, and * Removes from that user the permissions associated with their role. It is therefore possible in theory (though undesirable) for a user to be a member of an organization without having a role. .. _deprecated-api-list-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. 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 ------------------------------------- To file a support ticket for YubiEnterprise Delivery, click `Support `_.