Generating and Managing API Keys

Purpose

An API key lets another system, such as your own software or a partner's integration, read and send data to your UZIO account through UZIO's API. This article explains how to create a key, find it again, and delete it, and what to do with it once you have it.

Who can do this:

• Employer Administrators can add, view, copy and delete API keys.
• Other employer users do not see the API Keys option. Ask your Employer Administrator.
• Brokers cannot manage API keys for a client.
• UZIO Support can see the list and delete a key, but cannot create or view one.

Where to find API Keys

In the Employer Portal, open the Profile Menu and select API Keys.

The page lists every API key on your account in a table with three columns:

If your companies are linked: the page manages keys for all your linked companies at once. As the page says, "A common API key can be used to access data for all your linked companies." See Using a key for how the other system chooses which company it is working with.

Add an API key

1. On the API Keys page, click Add API Key.
2. Enter a Name.
• The name is only for your reference. Use something that says what the key is for, such as the partner or system that will use it.
• Up to 200 characters.
3. Click Generate API.
4. The Add API Key window shows the Name and the new API Key. Click Copy Key and paste it into the other system, or hand it to your partner securely.
5. Click Done. The key now appears in the list.

You can add as many keys as you need. One key per integration is the easiest to manage. If one partner's key has to be replaced, the others keep working.

View or copy a key later

1. On the API Keys page, open Actions on the key's row.
2. Select View API Key.
3. Click Copy Key, then Done.

Delete a key

Delete a key when an integration is no longer used, or if the key may have been seen by someone who should not have it.

1. On the API Keys page, open Actions on the key's row and select Delete.
2. Read the confirmation and click Yes.

The confirmation explains what happens next: "Once you delete this key, All API calls being made using this key will no longer return your company data." Any integration still using that key stops working until it is given a new one. You see "The API key deleted successfully" when it is done.

To replace a key without downtime:

1. Add a new key.
2. Update the integration to use the new key.
3. Delete the old key.

Using a key

The system or partner using the key needs these details. They are also in UZIO's API documentation.

• How to send the key: use the API key as the username in the request's authorization header. No password is needed; leave it blank or enter any value.
• Company identifier: most API calls also need a companyID, so UZIO knows which company the request is for. The Get Company Details API returns the companyID for your company and any linked companies.
• Connection: all calls use HTTPS and JSON.
• Wrong keys: if an unknown key is used repeatedly, UZIO blocks API access for a period and returns HTTP 403 Forbidden. Signing in to the UZIO portal is not affected.
• Volume: UZIO limits the rate of requests when they exceed its threshold.

Keep your keys private

As the API Keys page explains, a key lets anyone who has it access your company's data.

• Share a key only with the system or partner that needs it.
• Do not paste keys into emails, documents, chat messages or screenshots.
• Store keys somewhere with limited access.
• If a key may have been exposed, replace it as described above.

Common problems

I don't see API Keys in the Profile Menu

Only Employer Administrators see it. Ask your Employer Administrator to create the key, or to give you that role. See Managing Users and Roles.

"Enter a valid API key name."

The Name field is empty. Enter a name and click Generate API again.

An integration stopped working after I deleted a key

That is expected. Add a new key, give it to the integration, and test the connection again.

Our partner gets "403 Forbidden"

The key they are sending is not recognised, often because it was deleted or copied incorrectly. After repeated attempts with an unknown key, UZIO blocks API access for a period. Check the key with View API Key, send the partner a fresh copy, and ask them to wait before retrying.

Still stuck?

For help with API keys on your account, please reach out to us at support@uzio.com or call +1-571-601-1752. Include your company name and the name of the key. Never send the key itself. For questions about specific API endpoints, see the API documentation.

Related articles

• Integrations Overview
• Managing Users and Roles
• Understanding Roles and Access in UZIO