Our platform provides access to a Public API that follows the OpenAPI specification, enabling customers to interact programmatically with their data and perform various operations through API endpoints.

‍

‍

Accessing the OpenAPI documentation

‍

To explore and understand available API routes, you can access the API documentation hosted on your specific domain.

‍

1. Go to https://{subdomain}.epochapp.com/api/v1/docs/, replacing {subdomain} with your actual domain (e.g. company.epochapp.com).
2. The documentation outlines all available endpoints, including parameters, request/response formats, and other relevant details.

‍

Note: Currently, any customer can view other subdomains' API documentation. However, viewing API documentation does not grant access to other customers’ data or systems. Authentication via a valid API token is required to interact with any endpoints.

‍

‍

Generating an API token

‍

In order to use the Public API endpoints, you must generate an API token. The token acts as a unique identifier and allows secure interaction with your API.

‍

1. Log in to your Epoch account as a Super Admin.
2. Go to the Settings page.
3. Scroll to the API access section.
4. Click Generate token to create a new API token.
5. Assign the token a name. We recommend using names that correlate to how you'll be using the API.

‍

‍

Token management best practices

‍

1. Copy your token immediately

‍

Once generated, the API token is displayed only once. It won't be retrievable later on, so please copy and securely store it immediately.

‍

2. Token expiry

‍

API tokens are time-bound and include an expiration date. Be aware of the token’s expiry and generate a new token before it expires to ensure uninterrupted access to the Public API.

‍

Once a token expires, any API calls using that token will fail.

‍

3. Security measures

‍

Treat API tokens like passwords. Do not share them with unauthorized users.

‍

Store tokens in a secure location (e.g. a password manager or encrypted storage).

‍

Regularly audit API tokens and regenerate them as needed to maintain security.

‍

‍

Using the API

‍

Once you have your API token, you can include it in your requests to authenticate API calls.

‍

Example request header:

‍

Include the token in the Authorization header using the following format:

‍

Authorization: token <your_api_token>

‍

Example cURL request:

‍

curl -X GET "https://{subdomain}.epochapp.com/api/v1/example_endpoint" \
-H "Authorization: token YOUR_API_TOKEN"

‍

Replace {subdomain} with your domain and YOUR_API_TOKEN with the token you generated.

‍

‍

Troubleshooting

‍

Why isn't my token working?

‍

Verify the token has not expired. Ensure you are including the token in the correct request header format.

‍

I lost my API token. What do I do now?‍

‍
If you lose your API token, you can generate a new one from the Settings page.

‍

‍

More questions?

‍

If you have a question about Epoch's API that wasn't answered here, contact support@epochapp.com.