Purpose Statement

This article explains how to generate and manage API tokens within First Due, which are essential for establishing secure connections between First Due and external systems. API tokens enable automated data exchange, third-party integrations, and custom applications to interact with your First Due instance while maintaining proper security controls through role-based permissions.

Background Information

API tokens serve as secure authentication keys that allow external systems to communicate with First Due's database and functionality. Each token is unique to a specific user and automatically expires after one year to maintain security standards. The token works in conjunction with role-based permissions to control what data and endpoints can be accessed. This dual-layer security approach ensures that integrations can only perform actions that the associated user account is authorized to complete within the platform.

Required Permissions

To generate and manage API tokens, users need:

• API Token Generation permissions (specific permission object in user role)
• Administrative access to modify user profiles (for enabling API access)
• Appropriate role-based API permissions for intended endpoints and data interactions

Step-by-Step Guide

Enabling API Access for a User

1. Navigate to the individual user record in the Personnel module
2. Locate the "Enable API access token" checkbox
   

1. Check the box to activate API token capability for this user account
2. Save the user record to apply the changes
   

Generating an API Token

1. Navigate to User Menu

   • Click on your name in the upper right-hand corner of the First Due interface
     

1. Open Token Management

   • Click on "USER TOKEN" from the dropdown menu
     

3. Create New Token

   • Click the Play Arrow icon to initiate token generation
   • The system will immediately generate a unique API token
     

3. Manage Your Token

   • Copy Token: Click the Double Paper icon to copy the token to your clipboard
   • Regenerate Token: Click the Reverse Icon to create a new token (invalidates the current one)
   • Remove Token: Click the X icon to delete the current token
     

Token Information and Status

5. Review Token Details
   • The system displays the token status (Active/Expired)
   • Expiration date is shown (tokens are valid for one year from creation)
     

Managing Token Security

1. Restrict API token generation to a single designated user account when possible
2. Maintain a centralized record of which integrations use each token
3. Establish a token renewal schedule with adequate lead time before expiration
4. Store tokens in secure credential management systems, not plain text files

Best Practices

Token Management:

• Use one primary API token for all critical integrations to simplify management and renewal tracking
• Create calendar reminders at 90 days, 30 days, and 7 days before token expiration
• Document which systems and integrations depend on each token
• Establish a backup plan for token renewal to prevent service interruptions

Security Considerations:

• Never share API tokens in email or unsecured communication channels
• Use secure credential storage solutions for production environments
• Regularly audit which users have API token generation capabilities
• Immediately regenerate tokens if compromise is suspected

Permission Planning:

• Review required API permissions before generating tokens to ensure proper access levels
• Test API functionality in development environments before implementing in production
• Coordinate with administrators to ensure appropriate role-based permissions are configured

API Documentation

Troubleshooting & FAQs

Q: My API calls are returning permission errors even though I have a valid token. A: Check the role-based permissions for your user account. API tokens only authenticate your identity; actual data access is controlled through permission objects in the Role configuration. Contact your administrator or Client Success team to review API permission settings.

Q: How do I know when my API token will expire? A: Tokens automatically expire one year from generation. Check the API Token tab in your User Profile to view the expiration date, or maintain your own tracking system with renewal reminders.

Q: Can multiple users have API tokens for the same agency? A: Yes, but this creates management complexity. It's recommended to use a single designated API user account to simplify token tracking and renewal processes.

Q: What happens if my token expires during an active integration? A: All API calls will begin failing immediately. Plan token renewals well in advance and update all systems using the expired token with the new authentication key.

Q: Where can I find documentation about available API endpoints? A: Refer to the API documentation link, which lists supported endpoints and required permissions. Contact Client Success or your Implementation Manager if you need access or have questions about specific functionality.