API Integration Guide

The EduTAP Admin API (Ops API) is a backend REST API that lets external partners query and integrate EduTAP data into their own systems. This guide targets partner developers who want to load EduTAP data into their BI tools or data lakes.

Domains at a Glance

5-Minute Quickstart

1. Sign in — Send client_member credentials to POST /ops/v1/auth/signin and receive access_token, refresh_token.
2. Store the token — Save the access_token in a secure secret store.
3. Call protected endpoints — Attach Authorization: Bearer {access_token} to every protected endpoint.
4. Refresh the token — On a 401 response, call POST /ops/v1/auth/refresh to obtain a new access/refresh pair (rotation).

Authentication

All protected endpoints require a Bearer token.

• Header format: Authorization: Bearer {access_token}
• Token type: Only client_member JWTs are accepted. Internal staff/superadmin tokens are rejected.
• On expiry: When you receive a 401 NotAuthorized response, call /ops/v1/auth/refresh to renew the token.
• Auth failures: Distinguish causes via the 401 error_code (NotAuthorized, InvalidAuthHeader, InvalidRefreshToken).

Common Conventions

Time zone / date format

• All datetime fields are in UTC ISO 8601 format (e.g. 2026-06-25T09:00:00Z).
• Period query parameters (start_date, end_date) use the YYYY-MM-DD format (KST (Asia/Seoul) — the server interprets the range as KST 00:00:00 ~ 23:59:59 and converts it to UTC internally).

Pagination

• Query parameters: page (1-based, default 1), page_size (default 10, max 100).
• Response pagination object:

{
  "current_page": 1,
  "total_pages": 7,
  "page_size": 20,
  "total_items": 132,
  "is_next": true,
  "is_prev": false
}

Error responses

All error responses share the same body structure.

{
  "error_code": "NotAuthorized",
  "message": "Authentication required."
}

• 400: Business validation failure — e.g. credential mismatch (MismatchedPassword), inactive member (NotActivatedClientMember).
• 401: Token authentication failure — refresh via /ops/v1/auth/refresh and retry.
• 404: Resource not found / permission mismatch — e.g. NotExistSession.
• 422: Request validation failed — the details array describes each invalid field.
• 5xx: Internal server error — retry with the same payload is recommended.

Integration Scenarios

1) Daily usage sync

1. POST /ops/v1/auth/signin to obtain a token.
2. GET /ops/v1/dashboard/user-count?start_date=2026-06-01&end_date=2026-06-25 — daily user count for the period.
3. GET /ops/v1/dashboard/message-count?start_date=2026-06-01&end_date=2026-06-25 — daily message count for the period.
4. Load into your BI system.

2) Session dump ingestion (incremental)

1. GET /ops/v1/sessions/dumps?start_date=2026-06-24&end_date=2026-06-25 — sessions within a range.
2. Or GET /ops/v1/sessions/dumps/since-last — only new sessions created since the last call (incremental).
3. Ingest the payload into your data lake.

3) User activity summary

1. GET /ops/v1/users — returns per-learner activity summaries in one batch (no pagination).
2. Use the user_id partial-match filter to search for a specific user.
3. When both start_date and end_date are specified, only activity within that period (KST) is aggregated.

Next Steps