EPHY API

Before you begin

Your organization must be provisioned for access to the EPHY API before calling protected endpoints.

• Microsoft Entra ID Tenant ID
• Client ID
• Client Secret
• API Base URL
• API Scope / Audience

Base URL

All API endpoints are relative to the API host provided during onboarding.

Base path: /api/ephy

Example: https://<api-host>/api/ephy/employees

Authorization

Protected endpoints under /api/ephy require a bearer token from Microsoft Entra ID.

• Send the token in the HTTP header: Authorization: Bearer <access_token>.
• The token must be issued for this API's audience.
• The token must include the required application permission, such as Access_as_application.
• If the token is missing, expired, or invalid, the API returns 401 Unauthorized.
• If the token is valid but lacks the required permission, the API returns 403 Forbidden.

How to obtain an access token

The EPHY API uses Microsoft Entra ID OAuth 2.0 client credentials flow. Use the Tenant ID, Client ID, Client Secret, and API Scope provided during onboarding.

Token endpoint:

https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token

Required form fields:

• client_id: Your assigned application Client ID.
• client_secret: Your assigned client secret.
• grant_type: client_credentials
• scope: api://<api-client-id>/.default

cURL token request:

curl -X POST "https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=<client_id>" \
  -d "client_secret=<client_secret>" \
  -d "grant_type=client_credentials" \
  -d "scope=api://<api-client-id>/.default"

Successful token response:

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ..."
}

Use the returned access_token in the Authorization header when calling protected endpoints.

Example API request:

curl -X GET "https://<api-host>/api/ephy/employees?pageSize=100" \
  -H "Authorization: Bearer <access_token>"

• Do not send the client secret in API requests.
• Access tokens expire and should be refreshed by requesting a new token.
• Store client secrets securely. Do not place secrets in browser JavaScript or public repositories.

Using Swagger UI Authorization

To test protected endpoints in Swagger UI:

• Obtain an access token using the token flow above.
• Click the Authorize button in Swagger UI.
• Paste the access token.
• Click Authorize.
• Close the dialog and execute requests.

Pagination

Endpoints that return collections support pagination.

• pageSize: Number of records to return. Maximum value is 1000.
• nextCursor: Cursor value returned from the previous response.

Continue requesting pages until no nextCursor is returned.

Example first request:

GET /api/ephy/employees?pageSize=100

Example next page request:

GET /api/ephy/employees?pageSize=100&nextCursor=<nextCursor>

Sample response

Collection endpoints return records and may include a cursor for the next page.

{
  "employees": [
    {
      "employeeId": "12345",
      "firstName": "John",
      "lastName": "Doe",
      "emailAddress": "john.doe@example.com",
      "jobTitle": "Manager",
      "status": "Active",
      "hireDate": "2026-01-15T00:00:00Z"
    }
  ],
  "nextCursor": "eyJjbGllbnRJZCI6..."
}

Date format

Dates are returned using ISO 8601 format.

Example: 2026-07-01T14:30:00Z

Error responses

The API uses standard HTTP status codes.

Rate limits

Clients should avoid excessive concurrent requests. If rate limiting is enabled, the API may return 429 Too Many Requests.

Versioning

• Current API version: v1
• OpenAPI document: /openapi/v1.json
• Base path: /api/ephy

C# example

using System.Net.Http.Headers;

var accessToken = "<access_token>";

using var client = new HttpClient();

client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", accessToken);

var response = await client.GetAsync(
    "https://<api-host>/api/ephy/employees?pageSize=100");

response.EnsureSuccessStatusCode();

var json = await response.Content.ReadAsStringAsync();

Console.WriteLine(json);

Support

If you need API credentials, have trouble obtaining a token, or receive authorization errors, contact PuzzleHR Support.