About

This is the reference for the Exepron REST API. This API is the primary way to interact with Exepron remotely, whether you are building an app, scripting interactions with Exepron or developing any other integration. This page documents the REST resources available in Exepron , along with expected HTTP response codes and sample requests.

A note about the V1 API

The v1 API is currently in beta. Note that while all endpoints from the v1 API are available, they are currently under development. This means that any endpoint can change at any time, although we will not introduce breaking changes without advanced notice.

Getting Started

If you haven't integrated with Exepron before, start by reading "Integrating with Exepron" guide. The guide will introduce you to the Exepron Connect framework, as well as Exepron features and services that you can use when building an app. Then, read our Getting started guide to learn how to set up a development environment and build a Exepron app.

Authentication Overview

Authentication with the Exepron REST API is implemented using the OpenID Connect protocol, which operates as a layer on top of OAuth 2.0. Therefore, some familiarity with OAuth 2.0 concepts and flows is beneficial.

OpenID Connect defines four key roles:

Resource Owner: The entity that grants access to a protected resource.
Resource Server: The server hosting the protected resources.
Client: The application making requests on behalf of the resource owner.
Authorization Server: The server issuing access tokens to the client after successfully authenticating the resource owner.

The following table explains how these roles are applied in the context of the Exepron API:

Role	Description
Resource Owner	The Exepron user who authorizes access to their data.
Resource Server	The Exepron REST API hosting the data being accessed.
Client	Your application accessing the Exepron REST API on behalf of the user.
Authorization Server	The Exepron Identity Server that authenticates users and issues tokens.

Exepron supports common authentication scenarios, including client-side and server-side applications accessing the REST API.

Getting Started with Authentication

To interact with the Exepron API, follow these steps:

Obtain a Client ID and Secret: Contact Exepron Support to register your application and obtain a client ID (and a client secret for server-side applications).
Request an Access Token: Use the client ID to request an access token from the Exepron Identity Server.
Access API Resources: Include the access token in your API requests to authenticate and authorize access.

Authentication Flow

Applications follow these basic steps when accessing the Exepron API using OpenID Connect:

1. Obtain Development Credentials

Contact Exepron Support to register your application and retrieve credentials:

Client ID: Required for all applications.
Client Secret: Required for server-side applications.

2. Obtain an Access Token

Before accessing protected resources, request an access token by authenticating with the Exepron Identity Server. The request includes a scope parameter specifying the level of access required.

Token Request Methods:

Browser-based Applications: Use a browser redirect to authenticate users.
Device Applications: Use web service requests for token exchange.

User Consent:

In cases where user authentication is required:

The user logs in with their Exepron credentials.
The user is prompted to grant permissions requested by your application.

Upon successful authorization:

An access token (or authorization code for server-side applications) is issued.
If the user denies permission, an error response is returned.

Sending Tokens:

Include the access token in the Authorization header of API requests. For example:

Authorization: Bearer {access_token}

Important: Avoid sending tokens as query-string parameters, as they may be exposed in server logs or URL caches.

Token Lifetimes:

Access tokens are valid for a limited duration. Ensure your application is prepared to handle token expiration by requesting new access tokens when needed.

3. Refresh the Access Token

Access tokens have a limited lifetime. To maintain access beyond this period, use a refresh token to request a new access token.

Refresh Token Best Practices:

Store refresh tokens securely.
Use refresh tokens as long as they remain valid.
Be mindful of token limits:
- Per client-user combination.
- Across all clients for a single user.

4. Handle Errors

Your application should handle common authentication errors gracefully:

Invalid Token: Ensure the access token is not expired or malformed. If it is, request a new token.
Insufficient Scope: Update the scope parameter in the token request to include the required permissions.
User Denied Consent: Notify the user of the error and provide instructions to retry the process.

Security Best Practices

Secure Storage: Store client secrets and refresh tokens in secure storage mechanisms appropriate for your platform.
Avoid Query Parameters: Never send sensitive information in query strings.
Minimize Scopes: Request only the permissions your application needs.
Use HTTPS: Always use secure connections to protect data in transit.

Additional Resources

For detailed OpenID Connect protocol definitions, visit the OpenID Connect Documentation.
For API-specific examples, refer to the "Test" section in the menu.

OData protocol operations

Exepron suppprt a variety of OData operations. The following table depicts those operations

Option	Description
$expand	Expands related entities inline.
$filter	Filters the results, based on a Boolean condition.
$inlinecount	Tells the server to include the total count of matching entities in the response. (Useful for server-side paging.)
$orderby	Sorts the results.
$select	Selects which properties to include in the response.
$skip	Skips the first n results.
$top	Returns only the first n the results.

Webhooks

Webhooks are a way for applications to communicate in real-time by sending data to a specified endpoint via http protocol when a particular event occurs. Instead of constantly polling an API for updates, webhooks allow you to receive notifications directly. In the Exepron system, webhooks are used to notify clients about significant account or project events.

The following events are supported by Exepron Webhooks

At the start of a project
When tasks turn red
When projects are frozen
When tasks are available to start
When tasks are finished
When a milestone is achieved
When task status changes
When task remaining duration changes
When a project early warning changes
When a project status changes

How Webhooks Work

Event Detection: Exepron monitors for specific events based on client-defined conditions.
Data Preparation: When an event occurs, relevant data is formatted and sent to the client’s configured endpoint.
Delivery: The webhook is sent as an HTTP request to the specified URL, including an optional secret for authentication.
Response and Retry: The client’s server acknowledges receipt with a 200 OK. Failed requests are retried.

Security

Webhooks include a secret parameter, which is transferred in the Authorization header as a Bearer token in the HTTP requests sent to your endpoint. Clients should validate this token to ensure the authenticity of the request.

Get Started with Webhooks

Create a Webhook Handler:
- Set up an HTTP or HTTPS endpoint function to receive event data as POST requests.
- Ensure the handler can process a JSON payload and quickly return a 200 OK response.
Test Your Webhook Handler:
- Use a local testing tool to simulate webhook events.
- Verify that your handler processes events as expected.
Register Your Endpoint:
- Register the publicly accessible HTTPS URL of your webhook in the Exepron system.
Secure Your Endpoint:
- Validate the Authorization header with the secret key.
- Implement error logging and monitoring.
Register your webhook with Exepron API:
- Use Exepron API to register your endpoint

Webhook Administration

Managing webhooks in Exepron is straightforward and can be done through the Exepron API. You can configure, update, or delete webhook subscriptions to meet your integration needs. For detailed information on webhook administration, visit the Webhook Administration API.

Best Practices

Use secure HTTPS endpoints with valid SSL certificates.
Validate the Authorization header with the secret key.
Handle duplicate events to avoid reprocessing.