Skip to main content

REST API

Updated

🔌 REST API Interface

Seamlessly connect external systems and processes with E-Coach

E-Coach provides a comprehensive REST API that serves as an interface for external applications, automations, and integrations. With this API, you can connect third-party programs, exchange data automatically, and create custom workflows.

⚡ Quickstart

1. Create or use a valid E-Coach user account

2. Generate a Bearer Token via the authentication endpoint

3. Include the token in the header of all API requests

4. Use the interactive API documentation for testing: api.ecoach.cloud/swagger

🔒 Security Measures

The API interface is protected by multiple security layers to prevent unauthorized access and ensure the integrity of your data.

TLS Encryption (HTTPS)

All API requests are transmitted exclusively via an encrypted HTTPS connection. This ensures that sensitive data, such as access information and user content, is protected from unauthorized access during transmission.

Token-based Authentication

Every request requires a valid Bearer Token. This token is generated after successful authentication with email and password and must be sent in the header with every API request.

Rate Limiting

The API has intelligent limiting of allowed requests per unit of time. This protects the system from overload and Denial-of-Service attacks, while standard usage scenarios are supported without issues.

🔑 Authentication

Using the API requires a valid E-Coach user. The role assignment of this user determines which endpoints and data the API can access.

How authentication works:

1. Send a POST request to the auth endpoint with email and password

2. Upon successful authentication, you will receive a JSON Web Token (JWT)

3. Use this token as a Bearer Token in the Authorization header for all subsequent requests

4. Use the refresh token to obtain a new access token upon expiration

Example: Generate Token

Request:

curl -X POST "https://api.ecoach.cloud/api/auth" \
  -H "Tenant: <<TENANT>>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "<<EMAIL>>",
    "password": "<<PASSWORD>>"
  }'

Successful Response:

{
  "token": "eyJh*****mqBES_8_o",
  "refreshToken": "KYARbBeOEw4+pkAGb7r7HHXjNgZshJlYqGbpVWBi1zo=",
  "refreshTokenExpiryTime": "2025-07-30T10:45:41.4599978Z"
}

Example: Use Token in API Requests

The received token must be passed as a Bearer Token in the Authorization header for all subsequent API requests:

curl -X GET "https://api.ecoach.cloud/api/users/me" \
  -H "Authorization: Bearer <<TOKEN>>" \
  -H "Content-Type: application/json"

💡 Tip: Store the token securely in your application and renew it automatically via the refresh token before it expires. Never hardcode tokens or access credentials directly in your code.

📋 Data Format

All API responses are output in JSON format. JSON (JavaScript Object Notation) is a lightweight, text-based data format supported by nearly all modern programming languages and frameworks.

• Content-Type: application/json

• Character Encoding: UTF-8

• Structured: Clear hierarchies for easy parsing

🌐 API Endpoints & Documentation

The complete API documentation is available interactively via Swagger. Here you can view all available endpoints, test requests, and try out responses directly in the browser.

🔗 Interactive API Documentation (Swagger UI)

Use the Swagger interface to explore all endpoints, understand parameters, and test requests directly:

→ https://api.ecoach.cloud/swagger 

📥 Download OpenAPI Specification

Download the API specification as OpenAPI JSON and import it into tools like Postman, Insomnia, or generate client code automatically:

→ https://api.ecoach.cloud/swagger/v1/swagger.json 

📦 Commonly Used API Functions

• Create, edit, and manage users

• Retrieve and assign teams and projects

• Manage courses and learning content

• Query evaluations and progress

• Send notifications

• Export reports and statistics

💡 Best Practices

Token Management

• Store tokens securely (e.g., in environment variables or secure vaults)

• Implement automatic token refresh

• Avoid hardcoding credentials

Error Handling

• Implement retry logic for temporary errors

• Check HTTP status codes and respond accordingly

• Log API errors for easier debugging

Performance

• Use pagination for large datasets

• Cache frequently accessed, static data

• Avoid unnecessary API calls through intelligent batching

Testing & Development

• Test new integrations in the Swagger UI first

• Use tools like Postman for structured API tests

• Document your custom API workflows

🎯 Typical Use Cases

→ HR System Integration: Automatic import of new employees from the HR system

→ Learning Management: Assignment of courses based on job profiles

→ Reporting: Automatic extraction of learning progress for management reports

→ Notifications: Sending personalized reminders via external systems

→ Single Sign-On: Integration with existing identity management solutions

Need support with API integration?
Our technical support team is happy to help you with the implementation!

Related to