Secure access to the EPR Partner API is managed through authentication tokens and configuring the partner page for API connectivity. This setup ensures that interactions with the API are securely authorized and properly connected to your 3rd party back-office solutions.
1️⃣ Configure the Partner Page
Before obtaining an API token, ensure that the Partner Page is correctly configured to enable API connectivity.
Login to EPR as an Administrator and navigate to Settings > Environment > Partners
Configure the following settings:
Partner Name: Enter the Partner Name as provided by e-PlanSoft. This is a defined format that will need to be adhered to for proper functionality.
Ensure Partner is Active: Toggle to the 'on' position.
Incoming API Integration: For the Partner's system to access EPR.
Client/Agency: Enter the Client/Agency that will be using the integration. For developmental environments, utilize the connecting software name as a placeholder.
Username: Defined here recommended to use qa, uat, or prod suffix for easy distinction.
Outgoing API Integration: Provide the administrator-level user credentials from the Partner's system. These credentials should have administrative-level access and must match those configured in the Partner’s system.
Endpoint URL without a trailing '/'. For example, 'https://eplansoft.com'.
Retry Attempts: Set between 1 and 5, which defines the number of login attempts before timing out (default is 3).
Timeout (ms): Set a timeout in milliseconds to define the pause between connection attempts (default is 500 ms).
Click the 'Save' button to apply the configurations
Connection Status:
Check the connection status indicator; a green check means the configuration is successful, while a red X suggests revalidation of the settings.
Note: If outgoing API requirements and configuration have not been completed, you will not receive a green check mark for connections. You can proceed to test all incoming APIs but any outgoing actions/requirements from EPR will not be successful. Please contact the Integration Manager with all your Outgoing requirements for EPR to connect to your application.
2️⃣ Obtain an API Token
Partner Login
Once the partner page is configured, obtain your API token using the /login endpoint. Provide your partner username and password as follows:
{
"name": "your_partner_name"
"username": "your_username",
"password": "your_password"
}
Note: Email can be provided here. It is not required, as the Partner Credentials created on the Partner Page default to a defined user. It is recommended that the Partner access be used for all “system” actions so that those actions in the system reflect the Partner as the one executing the step and avoid non-authorization conflicts arising with other users. If an email is provided, this can be used to conduct actions on behalf of that said user or to generate SSO links from your application into EPR.
3️⃣ Using the Token
Include the obtained JWT in the x-access-token header for every API request:
Example:
GET /partner/purposes Headers: x-access-token: your_jwt_token
Token Characteristics and Management
Self-Documenting Expiration
Our Tokens follow the JWT format. JWTs inherently document their own expiration. The token itself contains the expiration time (exp), which can be checked programmatically to determine if the token is still valid.
Invalidity on Logout
Tokens will become invalid if a logout event occurs for the user to whom the token was issued. It is important to note that partners are not expected to log in or out via the user interface, hence a logout event causing token invalidation should not normally occur. However, if it does, the token will be invalidated immediately, even if it has not reached its expiration time.
Token Expiry and Refresh
While tokens have a set expiry (typically 12 hours), they may become invalid sooner due to logout events or other security measures. It is recommended to handle token refresh proactively by:
Monitoring for any API errors that suggest a token has become invalid.
Automatically re-authenticating to obtain a new token when needed, rather than waiting for the token's scheduled expiry.
This proactive refresh strategy helps avoid interruptions in API access due to unexpectedly invalidated tokens. Tokens can be checked via this API call:
Post /auth/checkToken
{
"token": "stored_partner_token"
}
Security Best Practices
Store tokens securely and never expose them in client-side code or public repositories.
Transmit all API requests over HTTPS to protect the token and other sensitive data from being intercepted.
Error Handling for Token Issues
In case of token-related errors (such as 401 Unauthorized or token expiry indications), immediately initiate a token refresh sequence to maintain API access continuity.
Need Help?
For support and inquiries, reach out to:
Channel Partner - Scott Garner sgartner@eplansoft.com
Integration Manager - Eric Niday eniday@eplansoft.com
General Support - support@eplansoft.com