.. API_Onboarding_Playbook.rst .. _api-onboarding-pb-label: ======================== API Onboarding Playbook ======================== Introduction ============ YubiEnterprise Delivery APIs enable turnkey delivery of Yubico products to your users. For a full description of YubiEnterprise Delivery functionality, see the :ref:`overview-label` in the Introduction to this guide. Anyone can write code against the YubiEnterprise Delivery API to develop their own integration against their service catalog. If you have a YubiEnterprise Delivery account, you can generate an API key and call the functions via API. Once the account has a purchase order counted against it, it will be stocked with Yubico products and you can have them sent out. .. _api-integration-label: API 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). To integrate your app or software platform with Yubico Enterprise Delivery, you will need to register an account and get an API access token. Contact api_sales@yubico.com to get started. Working with the YubiEnterprise Delivery Public API =================================================== .. _working-with-YED-API-label: Using the REST API ------------------ YubiEnterprise Delivery provides a set of methods and resources for checking your inventory of keys, validating mailing addresses, and having keys shipped to your users. The REST API responses can be returned in the JSON format. :Step 1: Begin by contacting the YubiEnterprise Delivery account owner in your organization to get your YubiEnterprise Delivery account, or contact api_sales@yubico.com. :Step 2: Familiarize yourself with YubiEnterprise Delivery functionality by either: * Exploring the `Console `_ itself, or * Reviewing the other chapters of the current guide (https://console.yubico.com/help/, available without logging in), which describe the functionality in detail. :Step 3: (Optional, but see :ref:`best-practices-label` below) Create an account used solely by the API caller to represent the calling application (e.g., jan+api@example.com). Use the YubiEnterprise Console to create this new user, and give it the **YubiDelivery Admin** role (for instructions on creating a new user, see :ref:`add-users-label`). :Step 4: Activate the new API-calling account by clicking the login link for the YubiEnterprise console in the email automatically sent to every new user/member. :Step 5: If the API caller did not already have a YubiKey associated with the YubiEnterprise login credentials, go to the profile page of the API caller (jan+api@example.com) by clicking the initial for that account on the upper right of any YubiEnterprise Console page. Click **Manage login credentials** and enroll a YubiKey as a roaming credential. Consider registering a second YubiKey in case the first YubiKey becomes unavailable due to loss or theft. :Step 6: Generate the API token: on the YubiEnterprise Console **Profile** page, click **Generate new API token**. 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 the token, so make a copy of it and store it in a secure location. -- .. IMPORTANT:: Whoever has this API token is authorized to make YubiKey shipping requests on behalf of your organization via the API. .. Note:: The API token is tied to both an account AND an organization. .. Warning:: The ``GET /auth/machine-token`` request revokes any existing tokens and creates a new machine token. This could therefore cause outages. GET in this instance is not a safe idempotent operation. 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 `_.