API Onboarding Playbook

While YubiEnterprise Delivery 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.

Note

The following sections describe how to onboard and work with the YubiEnterprise API, and provide some examples of shipment request features using the API. However, you can also use the API for example to manage users and work with customizations. For an overview of the entire API, see the YubiEnterprise API Reference.

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 the error cases. For more information, see Shipment Requests.
Data model
The API exposes the YubiEnterprise Services data model. It is crucial to understand the difference between product identifiers and form factor identifiers. For more information, see Product and Inventory 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.
Testing
Use an isolated sandbox environment to reduce testing time.
App maintenance
The YubiEnterprise API occasionally makes breaking changes. Therefore, monitor all release notes and spin up a project to prepare for migration before the change goes live. For more information, see Release Notes. To get notified about API changes, you can also sign up for the Yubico Developer Program mailing list.

When you have received your YubiEnterprise Delivery account and gained access to the YubiEnterprise Console, follow the instructions below to get started.

Setting up an API Caller

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 Managing Passwords with SSO.

To set up an API caller user account with an associated API token, do the following:

  1. Set up a sub-account for the application that will be calling the YubiEnterprise 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.

  2. Activate the new API caller account by clicking the login link in the email sent by the system, and follow the instructions.

    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.

  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.

  4. Generate an API token as described in Generating API Tokens. Make a copy of the token and store it in a secure location.

Generating API Tokens

To generate an API token for an account, do the following:

  1. In the Console, click the organization name in the top left corner.
_images/token-generate.png
  1. Select Generate API token. The Manage API token dialog appears showing the generated API token.
  2. 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.
  3. 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 Roles and Permissions.

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.

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.

Controlling Account Access

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

Authenticating with HTTP

The YubiEnterprise 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..."

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

Because it is possible to change the role of a user already in an organization, be aware that deleting a user does the following:

  • Deletes that user’s association with the organization.
  • Removes from that user the permissions associated with their role.

It is therefore not recommended for a user to be a member of an organization without having a role. For more information, see User Management.

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 FIDO2 Pre-Registration Shipments API.

Below are a few considerations 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 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.

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.

For shipping delivery integration examples, see ServiceNow Integrations and Shipping Pre-registered Keys.

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