Getting Started

1. Choose your Connection Method

For customers wanting to directly access Contract Eagle data, both a REST API and GraphQL API are available.

For most customers that choose to integrate directly with Contract Eagle, the REST API provides the simplest method, however the GraphQL API provides rich, configurable data sets that can be customised to your needs. There are also some features and data available via the GraphQL API that are not available via REST.

Both APIs are available for customer use and a combination of both can be used.

  • Document binary data is only available via the REST API

2. Determine your API Authentication Settings

Authentication Method

Customers can choose to use either a Client Key/Secret, provided on each request, or use the Client Key/Secret to request a JWT Bearer Token and use the bearer token for subsequent requests.

Either option, or a combination of both, can be enabled from the Contract Eagle UI.

  • The JWT Bearer Token expires after 60 minutes and must be refreshed with a request for a new token.
  • Customers wishing to integrate via Zapier must enable the Client Key/Secret

Auto-Disable Settings

The API can be configured to automatically disable access after a specified number of invalid login attempts within a time period. Once disabled, a notification is sent to a system notification email address that you specify and the API must be manually re-activated via the Contract Eagle UI.

Each customer can set these values for access to their API.

IP Access Restrictions

The API can be configured to only allow access to specified IP address range(s), provided in CIDR notation. These can be specified as either IPv4 or IPv6.

If an IP address outside of the specified range is used the following error will be displayed, indicating the source IP address that failed.

                    {
                        "code": "AR001",
                        "message": "Invalid address range [123.123.123.123]"
                    }

Clearing the IP restrictions will allow access to the API from any IP address.

If your IP address is hidden, the IP restrictions will need to be cleared to allow access (or can be set to the Contract Eagle proxy server address)

IP Address Guide Conversion Tool

Specifying allowed IP addresses may not be feasible for clients using third-party products (eg: Power Automate, Zapier, Power BI) where a range of IP addresses can be used and/or change frequently.

3. Determine User Access

The API is accessed within the context of a user configured in the Contract Eagle UI.

Security access assigned to a user within the application (Security Groups and Business Units) are applied to all actions carried out via the API.

New security groups are created with the upgrade to assist implementation:

  • API Read-Only Access
  • API Read-Write Access

however, use of these groups is optional - you can customise the access assigned to these groups or use existing security groups to control API access.

Multiple users can be granted access to the API - each will have their own API Key. For example, three users could be configured to meet different security requirements:

  • A user with full access to contracts, but no user access, may be used for maintaining contracts
  • A user with read-only access may be used for extracting data to a data warehouse
  • A user with full access to maintain users but no contract access may be used for maintaining user access

4. Setup Access in the Contract Eagle UI

Before you can start using the API a user with System Administrator privileges will need to configure access.

  • Configure the connection and authentication settings determined above from the Admin > System Preferences > API Settings option.
    • During initial setup you may wish to turn off the auto-disable function by setting the invalid login attempts to 0.
  • Configure the system notification email address from the Admin > System Preferences > System Email option.
  • Setup user access from the Admin > Maintain Users option and then generate the API key / secret from the Actions > API Keys option for the user.

5. Test Access

You're ready to test connection to the API.

REST API

See the API Overview documentation for information on how to connect to the REST API.

GraphQL

See the GraphQL Overview documentation for steps to get started with the GraphQL API.