API Onboarding Playbook

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.

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.

Policies to prevent abuse:
 This demo will allow a user to request shipment of as many keys as they desire. Additional logic will need to be built in to limit the number of shipment requests based on your requirements.
Selectable security Key:
 This demo is configured to order the YubiKey 5 NFC, and can be extended a variety of ways to allow different keys.
Error handling:There is one section in this guide that describes handling methods if an error is sent during the initial order. For a production deployment, there are a variety of different error cases that should be considered such as low inventory, shipment failure, undeliverable address, etc.
Auto-filling address:
 Currently this guide assumes that the user will be shipping their key to the address listed in ServiceNow. The catalog item may need to be extended to allow the user to input their personal address (for example, if they are not located at one of your main offices). You may want to consider leveraging the YubiEnterprise Delivery Verify Address API to allow your users to correct any address errors prior to submitting a shipment request.
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.

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 API: ServiceNow Integrations.

Setting up API Caller and Token

Consider the following 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 machine 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.
  • The fact that API tokens can easily be issued and revoked helps to assure the security of accounts that use machine tokens.
  • To handle machine token expiry, we recommend using the API (/auth/machine-token) to renew the API token. Ideally, logic should be put in to renew by calling the API to get a new token before the existing one expires.
  • 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.
  • Before an API token expires, the system generates and sends a notification to the associated email address. The email notifies that the token will expire in 7 days/1day and will not be accepted by our system after that.

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 Adding or Deleting Users.

  1. 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.
  2. In the Console, create an account only to be used by the API caller, for example, my-app@example.com.
  3. 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:

  1. 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.
  2. Register a YubiKey as a roaming credential, see Adding WebAuthn Credentials. Consider registering a second YubiKey in case the first one is lost.
Step 4:

Generate the API token:

  1. In the Console, click the organization name in the top left corner and select Manage API token.
  2. Make a copy of the token and store it in a secure location. For more information on API tokens, see Managing API Tokens.

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).

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 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.

Shipment Request Creation: Address Information

Deprecated Replacement
street_line3
Starting with release 2.8.0 this field in the recipient
address information will be deprecated and will only be
available until September 2024.
There is no replacement API for this functionality.

Shipping Requests: Bulk Shipment to Multiple Addresses

Deprecated Replacement
GET /v1/shipments/bulk
POST /v1/shipments/bulk
POST /v1/shipments/bulkvalidate
From July 2024, the only method to create
bulk shipment requests is to use the
YubiEnterprise Console
There is no replacement API for this functionality.

Shipping Requests: Listing, Tracking, Searching, Status etc.

Deprecated Replacement
GET /shipments GET /shipments_exact
POST /shipments POST /shipments_exact
GET /shipments/{shipmentId} GET /shipments_exact/{shipmentId}
PUT /shipments/{shipmentId} PUT /shipments_exact/{shipmentId}
DELETE /shipments/{shipmentId} DELETE /shipments_exact/{shipmentId}
/UpdateShipmentById shipments_exact/{shipment_id}
/organization/update-setting None

To file a support ticket for YubiEnterprise Delivery, click Support.