Authentication and Partner Configuration

Owned by Eric Niday, created
Last updated: Aug 30, 2024
3 min read

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.

 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 using the integration. For developmental environments, utilize the connecting software name as a placeholder.

    • Username: Defined here, it is recommended to use qa, uat, or prod suffix for easy distinction.

    • Password: Defined at the time of saving, any password entered in this field will be the incoming password used for Partner Token generation.

  • 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.

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.

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.

Constructing Single Sign-On (SSO) URLs

To direct a user to a specific project page via SSO, you must construct a URL that includes the generated user token and the project ID.

Steps to Construct the URL:

  • Authentication API /login endpoint. Include the user’s email in the payload. The user must have an active license in the EPR environment.

  • Generating the URL to the specific project they are launching from your platform is recommended for a seamless experience. If Project ID is not stored on your system, you will need to retrieve it via /projects?applyFilter=true&vendor_id= endpoint to locate the proper Project ID.

  • Construct the URL:

    1. URL Template:

      {baseUrl}/#!/projects/{projectId}/details/info?token={authToken}

    2. Example URL:

      http://apidemo.eplansoftreview.com/#!/projects/1/details/info?token=c5f28048d3ff6bb263c4aace5d2019c9e2b9205b5d56f772

Example End Result

The constructed URL directs the user to the project details page within the e-PlanSoft system, leveraging the SSO functionality.

Please refer to Beyond the MVP documentation for additional Construction URL examples ( assignment page, document page, review page, etc).

Conclusion

This document provides a comprehensive overview of the essential API endpoints necessary for the Minimum Viable Product (MVP) integration with the EPR system. By following the outlined steps and utilizing the provided endpoints, partners can effectively manage project creation, contact and address management, document uploads, and deliverables within the EPR platform.

Next Steps: Beyond the MVP

As you become more familiar with the EPR API and its capabilities, you may find the need to extend beyond the MVP functionalities. For advanced features such as automated document intake, versioning, and assignment management, please refer to our "Beyond the MVP" documentation. This extended guide will provide deeper insights and additional tools to streamline your integration further and enhance the overall efficiency of your workflows.

For detailed guidance on advanced features, visit the "Beyond the MVP" documentation

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

Related articles