.. api-best-practices-faq.rst .. _best-practices-label: ============================ API: Best Practices and FAQs ============================ The following best practices are specific to the YubiEnterprise Delivery API. For general best practices, troubleshooting and FAQs for the YubiEnterprise Console, see :doc:`Best_Practices_and_Troubleshooting` and :ref:`faqs-label`. Controlling Access to your Accounts =================================== API tokens are used by API caller accounts for authentication when integrating applications with the YubiEnterprise Delivery service. .. include:: includes/api-access-control.rst .. _lifecycle-label: Managing API Tokens =================== The following section describes how to create and delete API tokens, and regenerate them before they expire. .. LAAS-6642 Generating API Tokens --------------------- 1. In the **Console**, click the organization name in the top left corner. .. image:: graphics/token-generate.png :width: 250 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 :ref:`user-permissions-label`. .. _revoke-api-token: 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:** 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. Deprecated APIs =============== Deprecated APIs are not maintained and will eventually be removed. Ensure that your implementation is not using a deprecated version of the API. For information, see :ref:`deprecated-api-list-label`. API: FAQ ======== **Q. Who should use the API?** A. Customers of YubiEnterprise Delivery. **Q. Does Yubico charge for API calls?** A. No. **Q. How do I get access to the API?** A. Get login credentials from the YubiEnterprise Delivery account owner in your organization, and see :ref:`onboarding-label`. **Q. How should I set up an account to call the API?** A. After you have been given a YubiEnterprise Delivery account, follow the instructions in :ref:`api-onboarding-pb-label`. **Q. How do I test the API?** A. In the API Onboarding Playbook in the current guide, see :ref:`yed-ss-wb` and :ref:`servicenow-label`. **Q. How do I revoke an API token?** A. See :ref:`revoke-api-token` above. **Q. Where do I go if I need help?** A. 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?** A. Subscribe to the Yubico Developer Program mailing list. Go to ``_. Although this page looks as if it is just for a coupon, it is actually the sign-up page for the mailing list. **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?** A. It returns all the countries in the world. Currently we can ship only to the countries named in :ref:`del-pol-label`. **Q. Do I need to validate addresses via the API prior to submitting them?** A. "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 :ref:`incompletes-label`. ------------------------------------- To file a support ticket for YubiEnterprise Delivery, click `Support `_.