Analytics Endpoint Reference

Request and response contracts for organization login trends, service and provider counts, and recent logins.

AuthOS release 0.8.2 API v1 Latest-only documentation
Updated Jul 15, 2026
On this page

Retrieve daily login counts grouped by date. This endpoint returns a time series of authentication events, useful for visualizing login activity trends over time.

Authentication: Required (JWT)

Permissions: Must be a member of the organization (any role: Owner, Admin, or Member)

Path Parameters:

Parameter Type Description
org_slug string Organization slug

Query Parameters:

Parameter Type Required Default Description
start_date string No 30 days ago Start date in YYYY-MM-DD format
end_date string No Today End date in YYYY-MM-DD format

Request Headers:

Authorization: Bearer {jwt_token}

Example Request:

# Get login trends for the last 30 days (default)
curl https://sso.example.com/api/organizations/acme-corp/analytics/login-trends \
  -H "Authorization: Bearer eyJhbGc..."

# Get login trends for a specific date range
curl "https://sso.example.com/api/organizations/acme-corp/analytics/login-trends?start_date=2025-01-01&end_date=2025-01-31" \
  -H "Authorization: Bearer eyJhbGc..."

Response (200 OK):

[
  {
    "date": "2025-01-01",
    "count": 45
  },
  {
    "date": "2025-01-02",
    "count": 52
  },
  {
    "date": "2025-01-03",
    "count": 38
  }
]

Response Fields:

Field Type Description
date string Date in YYYY-MM-DD format
count number Total number of logins on this date

Error Responses:

Status Code Description
401 Unauthorized Missing or invalid JWT token
403 Forbidden User is not a member of this organization
404 Not Found Organization not found

Notes:

  • Results are ordered chronologically (ascending by date)
  • Only dates with login activity are included in the response
  • Dates with zero logins are omitted from the results

Logins by Service

GET /api/organizations/:org_slug/analytics/logins-by-service

Retrieve login counts grouped by service. This endpoint shows which services in your organization have the most authentication activity.

Authentication: Required (JWT)

Permissions: Must be a member of the organization (any role: Owner, Admin, or Member)

Path Parameters:

Parameter Type Description
org_slug string Organization slug

Query Parameters:

Parameter Type Required Default Description
start_date string No 30 days ago Start date in YYYY-MM-DD format
end_date string No Today End date in YYYY-MM-DD format

Request Headers:

Authorization: Bearer {jwt_token}

Example Request:

# Get logins by service for the last 30 days
curl https://sso.example.com/api/organizations/acme-corp/analytics/logins-by-service \
  -H "Authorization: Bearer eyJhbGc..."

# Get logins by service for January 2025
curl "https://sso.example.com/api/organizations/acme-corp/analytics/logins-by-service?start_date=2025-01-01&end_date=2025-01-31" \
  -H "Authorization: Bearer eyJhbGc..."

Response (200 OK):

[
  {
    "service_id": "550e8400-e29b-41d4-a716-446655440000",
    "service_name": "Main Application",
    "count": 1247
  },
  {
    "service_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "service_name": "Mobile App",
    "count": 856
  },
  {
    "service_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "service_name": "Admin Dashboard",
    "count": 234
  }
]

Response Fields:

Field Type Description
service_id string Unique identifier (UUID) of the service
service_name string Display name of the service
count number Total number of logins for this service

Error Responses:

Status Code Description
401 Unauthorized Missing or invalid JWT token
403 Forbidden User is not a member of this organization
404 Not Found Organization not found

Use Cases:

  • Identify most-used services in your organization
  • Track service adoption and usage patterns
  • Allocate resources based on service demand

Logins by Provider

GET /api/organizations/:org_slug/analytics/logins-by-provider

Retrieve login counts grouped by OAuth provider. This endpoint shows which authentication providers (GitHub, Google, Microsoft) are being used by your users.

Authentication: Required (JWT)

Permissions: Must be a member of the organization (any role: Owner, Admin, or Member)

Path Parameters:

Parameter Type Description
org_slug string Organization slug

Query Parameters:

Parameter Type Required Default Description
start_date string No 30 days ago Start date in YYYY-MM-DD format
end_date string No Today End date in YYYY-MM-DD format

Request Headers:

Authorization: Bearer {jwt_token}

Example Request:

# Get logins by provider for the last 30 days
curl https://sso.example.com/api/organizations/acme-corp/analytics/logins-by-provider \
  -H "Authorization: Bearer eyJhbGc..."

# Get logins by provider for Q1 2025
curl "https://sso.example.com/api/organizations/acme-corp/analytics/logins-by-provider?start_date=2025-01-01&end_date=2025-03-31" \
  -H "Authorization: Bearer eyJhbGc..."

Response (200 OK):

[
  {
    "provider": "github",
    "count": 1523
  },
  {
    "provider": "google",
    "count": 892
  },
  {
    "provider": "microsoft",
    "count": 234
  }
]

Response Fields:

Field Type Description
provider string OAuth provider name (github, google, microsoft)
count number Total number of logins using this provider

Supported Providers:

Provider Value
GitHub github
Google google
Microsoft microsoft

Error Responses:

Status Code Description
401 Unauthorized Missing or invalid JWT token
403 Forbidden User is not a member of this organization
404 Not Found Organization not found

Use Cases:

  • Understand which OAuth providers your users prefer
  • Optimize OAuth configuration based on usage
  • Plan for provider-specific integrations or BYOO setup

Recent Logins

GET /api/organizations/:org_slug/analytics/recent-logins

Retrieve the most recent login events for your organization. This endpoint returns detailed information about individual authentication events, useful for monitoring real-time activity and security auditing.

Authentication: Required (JWT)

Permissions: Must be a member of the organization (any role: Owner, Admin, or Member)

Path Parameters:

Parameter Type Description
org_slug string Organization slug

Query Parameters:

Parameter Type Required Default Description
limit number No 10 Maximum number of login events to return

Request Headers:

Authorization: Bearer {jwt_token}

Example Request:

# Get the 10 most recent logins (default)
curl https://sso.example.com/api/organizations/acme-corp/analytics/recent-logins \
  -H "Authorization: Bearer eyJhbGc..."

# Get the 50 most recent logins
curl "https://sso.example.com/api/organizations/acme-corp/analytics/recent-logins?limit=50" \
  -H "Authorization: Bearer eyJhbGc..."

Response (200 OK):

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": "user_123abc",
    "service_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "provider": "github",
    "created_at": "2025-01-15T14:32:18Z"
  },
  {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "user_id": "user_456def",
    "service_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "provider": "google",
    "created_at": "2025-01-15T14:28:45Z"
  },
  {
    "id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
    "user_id": "user_789ghi",
    "service_id": "550e8400-e29b-41d4-a716-446655440000",
    "provider": "microsoft",
    "created_at": "2025-01-15T14:15:22Z"
  }
]

Response Fields:

Field Type Description
id string Unique identifier (UUID) of the login event
user_id string Unique identifier of the user who logged in
service_id string Unique identifier (UUID) of the service
provider string OAuth provider used (github, google, microsoft)
created_at string ISO 8601 timestamp of when the login occurred

Error Responses:

Status Code Description
401 Unauthorized Missing or invalid JWT token
403 Forbidden User is not a member of this organization
404 Not Found Organization not found

Notes:

  • Results are ordered by created_at in descending order (most recent first)
  • The limit parameter accepts any positive integer (no upper limit enforced)
  • Login events are immutable and represent historical authentication activity

Use Cases:

  • Monitor real-time authentication activity
  • Security auditing and anomaly detection
  • Track user behavior and session patterns
  • Debug authentication issues