Contact Support

Creating and Managing API Keys

Updated

Manual tasks in the Awardco platform, such as uploading user files or generating reports, can be tedious and time-consuming. By using API keys, you can automate these processes, saving time and effort. This article explains what API keys are, their capabilities, and how you can use them within your organization through the API Key Management Tool.

Note: The permissions you select for your API key will depend on which Awardco products you use:

  • Awardco Recognition: You may require a wide range of permissions, including social feeds, recognition posting, and reporting.
  • Awardco Engage: Since Engage focuses on employee surveys, your API needs are likely limited strictly to User Management to keep your survey audiences up to date.

 

  1. What is API?
  2. Enabling the API Key Permission
  3. Accessing the API Key Management Tool
  4. Creating a New API Key
  5. Managing API Keys
  6. Transitioning from Classic API Keys
  7. Integrations Required Permissions

 

What is API?

API (Application Programming Interface) is a way for two programs to communicate. It provides a set of commands and requests that a program (such as Awardco) can accept from outside sources. Most mobile apps use APIs to communicate with their parent systems.

Awardco's API uses HTTP, the same protocol used by websites, simplifying communication and enabling API calls to be made directly from a browser.

Awardco’s API supports two main request types:

  • GET: Requests information from the database, such as retrieving reports in .csv or .json format.
  • POST: Updates information in the database. For example, it allows you to update users, post recognitions, or manage rewards.

 

What’s Possible with API?

Common use cases include:

  • User Management: Syncing employee data (Essential for both Engage and Recognition).
  • Automation: Automating awards and recognitions (Recognition only).
  • Social Feeds: Retrieving feed information for external displays (Recognition only).

 

To send a file using an API, the file must be accessible and properly encoded. There are three primary methods to handle this:

  1. Store the file on an FTP or publicly accessible server.
  2. Use an API service (e.g., Postman) to construct the request.
  3. Use programming languages like C#, cURL, or JavaScript to send the request.

 

While the API provides powerful access to the Awardco platform, clients are fully responsible for its use.

 

To learn more, visit our Public API Documentation.

 

Enabling the API Key Permission

By default, only Super Admin users can manage API keys. To allow other roles to manage and create API keys:

  1. On the homepage, select the Admin button at the bottom of the left navigation menu.
  2. Select “Users,” then “Permissions” from the left navigation menu.
  3. Click the three-dot icon next to the role you want to edit and choose Edit.
  4. Navigate to the Permissions settings and check the box next to ‘API Keys’.
  5. Click Save & Apply.

 

 

Accessing the API Key Management Tool

Awardco provides a dedicated API Key Management Tool that allows you to manage specific API keys for various actions, such as sending recognitions, pulling feeds, or creating users. Rather than using a single all-powerful API key, Awardco breaks keys into separate actions based on your needs.

 

To access the API Key Management tool:

  1. On the homepage, select the Admin button at the bottom of the left navigation menu.
  2. Select “Platform”, then “Integrations,” then “API Settings” from the left navigation menu.

 



 

In the API Key Management Tool, you can:

  • View and manage specific API keys for different tasks (e.g., sending recognitions, pulling reports).
  • Assign roles and permissions for who can manage API keys within your organization.
  • Track who created each API key and when it was created.
  • Ensure that API keys are hashed and salted for security (they are not stored in plain text).
  • Delete API keys as needed.
  • Note that impersonating users cannot generate API keys.
  • Securely send API keys to trusted individuals.

 

Creating a New API Key

To create a new API key:

  1. Click the “+ New API Key” button on the API Keys page.
  2. Enter a Key Name.
  3. Select the permissions  the key should have .
  • For Recognition Customers: Select permissions relevant to your integration (e.g., Custom Feed for ScreenCloud).
  • For Engage-Only Customers: You typically only need permissions related to user data transfers to keep your survey audiences up to date. We recommend selecting only:
    • activate user, archive user, create user, import users, profile picture, reset password, user exists, and users.
  1. Set the key's expiration period or date.
    • The maximum expiration date is three years from today’s date. It’s recommended to regularly swap out API keys.
  2. Click Next.
  3. Choose to generate the key immediately or send it securely to another person.
  4. Review the details and complete the process by clicking Generate API Key or sending it securely.

 

 

Important: Copy and securely store the API key immediately after generating it. For security reasons, it will not be displayed again. For more information on API Key best practices and tips, reference this support article.  

 

Managing API Keys

Viewing and Editing API Key Details

To view details of an API key, click the API Key name to open a details window showing:

  • Key name.
  • First six digits of the key.
  • Creator name.
  • Status.
  • Permissions.
  • Creation date.
  • Expiration date.
  • Last used date.

 

 

To edit an API key’s name or expiration date, click Edit and make changes. Save your changes when done.

 

 

Revoking an API Key

Revoking an API key deactivates it permanently, making any associated integrations non-functional. This action cannot be undone.

 

To revoke an API key:

  1. Click the three-dot icon next to the key.
  2. Select “Revoke.”
  3. Confirm by clicking “Revoke API Key.”

 

Revoked keys will move to the Archived tab.

 

 

Resending an API Key

If an API key shows a “Not Accepted” status or wasn’t accepted within 24 hours, you can resend it.

  1. Click the three-dot icon next to the key.
  2. Select “Resend.” The API key will be resent to the email address specified when the key was created.

 

Cloning an API Key

To clone an API key:

  1. Click the three-dot icon next to the key and select “Clone.”
  2. Update the name, permissions, or expiration date as needed.
  3. Follow the same process to generate or send the key as described in “Creating a New API Key.”

 

 

Viewing Archived Keys

To view revoked or archived API keys, navigate to the Archived tab in the API Keys settings. Revoked keys cannot be restored, but they can be cloned to create a duplicate.

 

 

Transitioning from Classic API Keys

While classic API keys will continue to function for now, we recommend migrating to the new system for enhanced security and better control over your integrations.

 

Finding Your Classic API Key

Your classic API key has been moved to the new API Key Management Page. You can now find it at the bottom of the API Settings page.

 

 

How to Migrate from Classic API Keys

To transition securely from your classic API key:

  1. Create New Permissioned Keys: Generate separate API keys for each integration using the steps in "Creating a New API Key" above. Ensure each key has only the specific permissions needed for its integration.
  2. Update Your Integrations: Replace the classic API key in each integration with the appropriate new permissioned key.
  3. Delete Your Classic API Key: Once all integrations are updated, click the "Delete Classic API Key" button at the bottom of the API Settings page.

 

Integration Required Permissions

A list of integrations using API keys and the required permission for each:

 

 

 

If you have any questions, please contact Awardco Admin Support.

Related to