API keys are powerful tools for building integrations with Awardco. They allow organizations to create custom solutions, such as internal recognition tools or automations, and enable trusted vendors, like ScreenCloud, to integrate with Awardco seamlessly. For example, Awardco Connect uses API keys to link Awardco with external applications for tasks such as certificate printing, retirement automations, spiff automations, and recognition payroll.
Improper handling of API keys can expose sensitive data, disrupt your Awardco platform, or cause fraudulent activities. This article shares best practices to secure your API keys throughout their lifecycle. Follow these tips to protect your platform and employee data. For detailed steps on creating, managing, and revoking API keys, see our Creating and Managing API Keys article.
API Key Management Permissions
API key permissions grant broad access to the Awardco platform. Users with API key management permission have full access to the public API, including capabilities like managing users, recognizing employees, and retrieving reports.
Restrict Access: Restrict this permission to a small group of trusted individuals. By default, only Super Admins have this permission.
Identify Product Use: Engage-only clients have a smaller "access surface" as they do not use financial rewards. However, user data security remains a top priority. Notification practices: When an API key is created, all users with API key management permission will receive an email notification. Verify that the key was created for a legitimate business purpose. If a user who created or received an API key is archived, an email notification will be sent to all users with the API key management permission. It’s recommended to rotate the affected key promptly.
Recommendation: Sync your users with Awardco daily to ensure timely notifications and minimize potential disruptions.
API Key Creation
When creating an API key, follow these best practices:
-
Limit permissions: Assign only the permissions necessary for the intended use case. For example:
The Create User, Reset User Password, and Import Users endpoints are sensitive and should be assigned sparingly.
Trusted third parties, such as ScreenCloud, typically require only limited permissions, like access to feed endpoints.
Engage-only customers should limit permissions to user management: activate user, archive user, create user, import users, profile picture, reset password, user exists, and users. Recognition customers may require broader access depending on the integration (e.g., feed endpoints for ScreenCloud).
-
Expiration and rotation:
API keys have expiration dates. Notifications are sent to all users with API key management permission, including Super Admins, approximately one month before a key expires.
Rotate API keys regularly—preferably every year or more frequently.
-
External sharing:
Share API keys only with trusted individuals or vendors.
Use the built-in sharing feature to send keys securely. For example, Awardco Connect uses this feature to send keys to ias@awardco.com.
Do not share keys through email, shared documents, or unapproved methods.
API Key Storage
API keys are only visible when first generated. Ensure they are stored securely:
Save keys in a password manager or a secure key management service.
Avoid unsecure sharing methods such as unencrypted emails, shared documents, or messaging platforms like Microsoft Teams or Slack.
Do not write down keys or store them in plaintext.
If storing API keys in a database, encrypt the keys and decrypt them only when needed for use.
Avoid storing API keys in source code repositories, such as GitHub, to prevent accidental exposure.
API Key Development
Follow these guidelines during development to safeguard your API keys:
Never send API keys to the browser or frontend of your application.
Always use HTTPS for API requests to ensure encrypted communication.
Include the API key in the headers of your API requests. Avoid embedding keys directly in URLs or body parameters.
Follow these best practices to secure your Awardco platform and employee data while optimizing API integrations. For details on creating, editing, or revoking API keys, see our Creating and Managing API Keys article.
If you have any questions, please contact Awardco Admin Support.