Analytics API

Endpoints for retrieving login and authentication analytics including user patterns, service usage monitoring, and OAuth provider adoption tracking.

Updated Nov 15, 2025
Edit on GitHub
analytics metrics reporting insights

Analytics API

The Analytics API provides endpoints to retrieve login and authentication analytics for your organization. These endpoints allow you to track user authentication patterns, monitor service usage, and analyze OAuth provider adoption.

Overview

All analytics endpoints require authentication and organization membership. They track login events that occur when users authenticate with your organization’s services through OAuth providers or password-based authentication.

Key Features:

  • Track login trends over time
  • Analyze authentication activity by service
  • Monitor OAuth provider usage (GitHub, Google, Microsoft)
  • View recent login events with detailed information

Default Date Range: When date parameters are not specified, all analytics endpoints default to the last 30 days.

Endpoints Summary

Method Path Description
GET /api/organizations/:org_slug/analytics/login-trends Get daily login counts over time
GET /api/organizations/:org_slug/analytics/logins-by-service Get login counts grouped by service
GET /api/organizations/:org_slug/analytics/logins-by-provider Get login counts grouped by OAuth provider
GET /api/organizations/:org_slug/analytics/recent-logins Get most recent login events

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

Best Practices

Date Range Selection

# Last 7 days
curl "https://sso.example.com/api/organizations/acme-corp/analytics/login-trends?start_date=$(date -u -d '7 days ago' +%Y-%m-%d)&end_date=$(date -u +%Y-%m-%d)" \
  -H "Authorization: Bearer eyJhbGc..."

# Current month
START_DATE=$(date -u +%Y-%m-01)
END_DATE=$(date -u +%Y-%m-%d)
curl "https://sso.example.com/api/organizations/acme-corp/analytics/login-trends?start_date=$START_DATE&end_date=$END_DATE" \
  -H "Authorization: Bearer eyJhbGc..."

Combining Multiple Analytics

# Fetch all analytics data in parallel for a dashboard
ORG="acme-corp"
TOKEN="eyJhbGc..."
BASE_URL="https://sso.example.com"

curl "$BASE_URL/api/organizations/$ORG/analytics/login-trends" \
  -H "Authorization: Bearer $TOKEN" &

curl "$BASE_URL/api/organizations/$ORG/analytics/logins-by-service" \
  -H "Authorization: Bearer $TOKEN" &

curl "$BASE_URL/api/organizations/$ORG/analytics/logins-by-provider" \
  -H "Authorization: Bearer $TOKEN" &

curl "$BASE_URL/api/organizations/$ORG/analytics/recent-logins?limit=20" \
  -H "Authorization: Bearer $TOKEN" &

wait

Pagination for Large Result Sets

For recent logins with high volume:

# First 100 results
curl "https://sso.example.com/api/organizations/acme-corp/analytics/recent-logins?limit=100" \
  -H "Authorization: Bearer eyJhbGc..."

# Note: The API does not support offset-based pagination
# To get older records, use date-filtered queries on login-trends