API: Best Practices and FAQ

The following best practices are specific to API use; others are in Best Practices and Troubleshooting.

Control Access to your Accounts

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

Lifecycle Management

API tokens expire precisely one year after generation. Since a user 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.

Notification of API Token Expiry

The system automatically emails notification that the API token will expire:

  • 7 days beforehand
  • 1 day beforehand
  • on the day of expiry.

Notification is emailed to:

  • the user / holder of the API token
  • Org owner (in cc)

Revoking and Deleting an Active API Token

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.

API: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.
Console:While logged in to YubiEnterprise Delivery Console as the user with the relevant API token, go to the profile page by clicking on the profile icon on the top right. Click Revoke and delete active API token. Once you revoke and delete the old token, the button to generate a new token appears.

API: FAQ

Q. Who should use the API?

  1. Customers of YubiEnterprise Delivery.

Q. Does Yubico charge for API calls?

  1. No.

Q. How do I get access to the API?

  1. Get login credentials from the YubiEnterprise Delivery account owner in your organization, and see Onboarding Workflow.

Q. How should I set up an account to call the API?

  1. After you have been given a YubiEnterprise Delivery account, follow the instructions in API Onboarding Playbook.

Q. How do I test the API?

  1. In the API Onboarding Playbook in the current guide, see YubiEnterprise Delivery Self-Service Web Portal and ServiceNow Integrations.

Q. How do I revoke an API token?

  1. See Revoking and Deleting an Active API Token above.

Q. Where do I go if I need help?

  1. Get help now from our support team: to file a support ticket for YubiEnterprise Delivery, click Support, or reach out to the customer success representative who was assigned to your company.

Q. Can I get notification of YubiEnterprise Delivery API changes?

  1. Subscribe to the Yubico Developer Program mailing list. Go to https://www.yubico.com/why-yubico/for-developers/developer-program/. Although this page looks as if it is just for a coupon, it is actually the sign-up page for the mailing list.

Q. Where do I find official Yubico product images and descriptions?

  1. On Yubico’s Press room images and logos page are the logo and product images.

Q. What is the maximum number of YubiKeys that can be included in a shipment request?

  1. It depends on the country to which you are shipping. See Delivery Policies.

Q. Can a shipment request be cancelled?

  1. Shipment requests can be edited or deleted until 2am PST (10am GMT), the day after they were entered.

Q. What shipping delivery options are available?

  1. Depending on the country being shipped to, one or both of the following will be available:

    Normal (standard) shipping: Shipments typically will take 5-7 days for transit in North America and Europe. Other parts of the world will incur longer transit times.

    Expedited (rush) shipping: Shipments typically will take 1 business day for transit in North America. Other parts of the world may incur longer transit times, but will leverage the fastest time frame reasonably available.

Q. Does the country code look-up API return the countries to which Yubico can ship, or does it return all countries in the world?

  1. It returns all the countries in the world. Currently we can ship only to the countries named in Delivery Policies.

Q. What do you do with the zip_code field if it is not applicable, for example, for Canada and the EU countries?

  1. Leave the zip_code field blank and use the postal_code field instead.

Q. Do I need to validate addresses via the API prior to submitting them?

  1. “Pre-qualifying” the address does not eliminate the address validation step. Every shipping request is sent for address validation. Status is updated when address validation is complete. Once the request reaches the “Accepted for Fulfillment” status, it has passed the address validation phase. If the status is “Incomplete Address”, edit or delete the request. See Reviewing Incompletes.

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