.. API_Onboarding_Playbook.rst .. _api-onboarding-pb-label: ======================== API Onboarding Playbook ======================== .. _working-with-YED-API-label: Introduction ============ While YubiEnterprise Delivery can be driven entirely through the pre-built console, it also comes with an API that provides the ability to extend the functionality to custom applications. This API will enable your organization's developers to integrate the API into custom solutions that precisely meet the requirements of your business. .. _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`. Setting up API Caller and Generating Token ========================================== With regard to the API token, .. include:: includes/api-access-control.rst :Step 1: Set up a sub-account for the application that will be calling the YubiEnterprise Delivery API. Detailed instructions for b and c below are given in :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. The system automatically sends an email with login instructions to the new user. b. Use the YubiEnterprise Delivery Console (GUI) to create an account used *solely* by the API caller, for example, jan+api@example.com. c. Assign to the API caller's account the **YubiDelivery Admin** role. :Step 2: Activate the new API-calling account by clicking the login link in the email and following the on-screen prompts. :Step 3: Associate a YubiKey for the API caller account with the YubiEnterprise login credentials: a. On the upper right of any YubiEnterprise Console page, go to the profile page of the API caller by clicking the initial for that account. b. Click **Manage login credentials** and enroll a YubiKey as a roaming credential. .. Note:: Consider registering a second YubiKey in case the first YubiKey becomes unavailable due to loss or theft. :Step 4: Generate the API token: a. On the YubiEnterprise Console **Profile** page, click **Generate new API token**. b. Make a copy of the token and store it in a secure location. The token is displayed on the Console *only at this time*. Once you navigate away from the page you will no longer be able to view it. .. Note:: The API token is tied to an account AND an organization. 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. ------------------------------------- To file a support ticket for YubiEnterprise Delivery, click `Support `_.