Sentinel Pass Service

Sentinel Passes are security credentials (OAuth clients, API keys, and tokens) scoped to a project. The service exposes CRUD operations, key rotation, revocation, and activity log/metrics endpoints. Base URL for CRUD operations is REACT_APP_ORGANIZATIONS_API_BASE_URL (default: https://api.makakoo.com/ma-metrics-wsp-ms/v1/api). Activity log and metrics endpoints are served by the Auth microservice at REACT_APP_AUTH_API_BASE_URL. All requests require Api-Key and Authorization: Bearer <token> headers.

Create Sentinel Pass

POST /organizations/{orgId}/projects/{projectId}/sentinel_passes

Create a new security credential scoped to a project.

orgId

string

required

The organization’s unique ID.

projectId

string

required

The project’s unique ID.

sentinelPass.title

string

required

A human-readable name for the credential.

sentinelPass.description

string

Optional description.

sentinelPass.entityType

string

The entity type this credential is for. Defaults to "project".

sentinelPass.entityId

string

The entity ID. Automatically set to projectId.

sentinelPass.permissions

array

Array of permission strings granted to this credential.

sentinelPass.allowedReferers

array

Array of allowed HTTP referer patterns.

sentinelPass.credentialType

string

The credential type. Defaults to "api_key".

sentinelPass.scopes

array

Array of OAuth scopes.

sentinelPass.expiresAt

string

Optional ISO 8601 expiration datetime.

sentinelPass.tags

array

Optional array of string tags.

curl -X POST https://api.makakoo.com/ma-metrics-wsp-ms/v1/api/organizations/org-123/projects/proj-456/sentinel_passes \
  -H "Authorization: Bearer <token>" \
  -H "Api-Key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "sentinelPass": {
      "title": "Production API Access",
      "description": "Read-only access for production service",
      "credentialType": "api_key",
      "permissions": ["read:data"],
      "scopes": ["read"],
      "tags": ["production"]
    }
  }'

Response: The created Sentinel Pass in unified asset format (see Response Shape).

List Sentinel Passes

GET /organizations/{orgId}/projects/{projectId}/sentinel_passes

orgId

string

required

The organization’s unique ID.

projectId

string

required

The project’s unique ID.

active

boolean

Filter by active status.

credential_type

string

Filter by credential type.

string

Filter by name substring.

Get Sentinel Pass

GET /organizations/{orgId}/projects/{projectId}/sentinel_passes/{passId}

orgId

string

required

The organization’s unique ID.

projectId

string

required

The project’s unique ID.

passId

string

required

The Sentinel Pass ID.

Update Sentinel Pass

PUT /organizations/{orgId}/projects/{projectId}/sentinel_passes/{passId}

orgId

string

required

The organization’s unique ID.

projectId

string

required

The project’s unique ID.

passId

string

required

The Sentinel Pass ID.

sentinelPass

object

required

Updated Sentinel Pass data. Accepts the same fields as Create.

Delete Sentinel Pass

DELETE /organizations/{orgId}/projects/{projectId}/sentinel_passes/{passId}

Permanently delete a Sentinel Pass. To disable without deleting, use Revoke instead.

orgId

string

required

The organization’s unique ID.

projectId

string

required

The project’s unique ID.

passId

string

required

The Sentinel Pass ID.

Rotate Key

POST /organizations/{orgId}/projects/{projectId}/sentinel_passes/{passId}/rotate_key

Invalidate the current API key and generate a new one. The Sentinel Pass remains active.

orgId

string

required

The organization’s unique ID.

projectId

string

required

The project’s unique ID.

passId

string

required

The Sentinel Pass ID.

curl -X POST https://api.makakoo.com/ma-metrics-wsp-ms/v1/api/organizations/org-123/projects/proj-456/sentinel_passes/pass-789/rotate_key \
  -H "Authorization: Bearer <token>" \
  -H "Api-Key: <your_api_key>"

Response: The updated Sentinel Pass with a new key.

Revoke Sentinel Pass

POST /organizations/{orgId}/projects/{projectId}/sentinel_passes/{passId}/revoke

Disable a Sentinel Pass without deleting it. The credential can be re-activated later.

orgId

string

required

The organization’s unique ID.

projectId

string

required

The project’s unique ID.

passId

string

required

The Sentinel Pass ID.

Activate Sentinel Pass

POST /organizations/{orgId}/projects/{projectId}/sentinel_passes/{passId}/activate

Re-enable a previously revoked Sentinel Pass.

orgId

string

required

The organization’s unique ID.

projectId

string

required

The project’s unique ID.

passId

string

required

The Sentinel Pass ID.

Get Activity Logs

GET /oauth/agent/activity/logs

Fetch paginated activity logs for a Sentinel Pass agent. Served by the Auth microservice.

agent_user_id

string

required

The agent user ID associated with the Sentinel Pass.

page

integer

Page number. Defaults to 1.

per_page

integer

Items per page. Defaults to 25.

start_date

string

ISO 8601 start date for filtering.

end_date

string

ISO 8601 end date for filtering.

activity_type

string

Filter by activity type: api_request, token_generation, or error.

endpoint

string

Filter by endpoint path.

success

boolean

Filter by success status.

sort_by

string

Field to sort by.

sort_order

string

Sort order: asc or desc. Defaults to desc.

curl "https://api.makakoo.com/ma-authentication-ms/v1/api/oauth/agent/activity/logs?agent_user_id=agent-123&page=1&per_page=25" \
  -H "Authorization: Bearer <token>" \
  -H "Api-Key: <your_api_key>"

data

array

Array of activity log entries.

Show Log entry fields

string

The log entry ID.

agent_user_id

string

The agent user ID.

endpoint

string

The API endpoint path that was called.

http_method

string

HTTP method: GET, POST, etc.

status_code

integer

HTTP status code of the response.

client_ip

string

Client IP address.

user_agent

string

User agent string.

started_at

string

ISO 8601 timestamp when the request started.

completed_at

string

ISO 8601 timestamp when the request completed.

duration_ms

integer

Request duration in milliseconds.

success

boolean

Whether the request succeeded.

activity_type

string

Activity type: api_request, token_generation, or error.

error_message

string | null

Error message if the request failed.

meta.page

integer

Current page number.

meta.per_page

integer

Items per page.

meta.total_count

integer

Total number of log entries matching the filters.

meta.total_pages

integer

Total number of pages.

Export Activity Logs

GET /oauth/agent/activity/export

Export activity logs as a downloadable file. Returns a binary blob.

agent_user_id

string

required

The agent user ID associated with the Sentinel Pass.

format

string

Export format: json, csv, or jsonl. Defaults to json.

start_date

string

ISO 8601 start date for filtering.

end_date

string

ISO 8601 end date for filtering.

activity_type

string

Filter by activity type.

endpoint

string

Filter by endpoint path.

success

boolean

Filter by success status.

curl "https://api.makakoo.com/ma-authentication-ms/v1/api/oauth/agent/activity/export?agent_user_id=agent-123&format=csv" \
  -H "Authorization: Bearer <token>" \
  -H "Api-Key: <your_api_key>" \
  --output activity-logs.csv

Get Usage Metrics

GET /oauth/agent/activity/metrics

Fetch aggregated usage metrics for a Sentinel Pass agent over a specified time range.

agent_user_id

string

required

The agent user ID associated with the Sentinel Pass.

start_date

string

ISO 8601 start date.

end_date

string

ISO 8601 end date.

group_by

string

Grouping interval: hour, day, or week. Defaults to day.

curl "https://api.makakoo.com/ma-authentication-ms/v1/api/oauth/agent/activity/metrics?agent_user_id=agent-123&group_by=day" \
  -H "Authorization: Bearer <token>" \
  -H "Api-Key: <your_api_key>"

data

array

Array of time-series data points.

Show Data point fields

timestamp

string

ISO 8601 timestamp for the interval.

total_requests

integer

Total number of requests in the interval.

success_count

integer

Number of successful requests.

error_count

integer

Number of failed requests.

avg_latency_ms

number

Average response latency in milliseconds.

p95_latency_ms

number

95th percentile latency in milliseconds.

unique_endpoints

integer

Number of distinct endpoints called.

meta.period.start_date

string

The start of the reported period.

meta.period.end_date

string

The end of the reported period.

meta.period.group_by

string

The grouping interval used.

Response Shape

All CRUD endpoints return Sentinel Passes in the unified asset format:

string

The Sentinel Pass ID.

type

string

Always "studio_tool".

attributes.title

string

The credential name.

attributes.description

string

The credential description.

attributes.assetType

string

Always "security".

attributes.active

boolean

Whether the credential is currently active.

attributes.tags

array

Array of string tags.

attributes.metadata.permissions

array

Array of permission strings.

attributes.metadata.allowedReferers

array

Array of allowed HTTP referer patterns.

attributes.metadata.credentialType

string

The credential type, e.g., api_key.

attributes.metadata.scopes

array

Array of OAuth scope strings.

attributes.metadata.expiresAt

string | null

ISO 8601 expiration datetime, or null for non-expiring credentials.

attributes.metadata.lastRotated

string | null

ISO 8601 timestamp of the last key rotation.

attributes.metadata.usageCount

integer

Total number of times this credential has been used.

attributes.createdAt

string

ISO 8601 creation timestamp.

attributes.updatedAt

string

ISO 8601 last-updated timestamp.

Caching and Rate Limits

Metrics data is cached client-side for 30 seconds.
Activity log results are cached per page and filter combination.
The recommended auto-refresh interval is 30 seconds.
Implement exponential backoff on failures.

Overview

Services

Sentinel Pass Service

Create Sentinel Pass

List Sentinel Passes

Get Sentinel Pass

Update Sentinel Pass

Delete Sentinel Pass

Rotate Key

Revoke Sentinel Pass

Activate Sentinel Pass

Get Activity Logs

Export Activity Logs

Get Usage Metrics

Response Shape

Caching and Rate Limits

Build docs developers (and LLMs) love

Overview

Services

​Create Sentinel Pass

​List Sentinel Passes

​Get Sentinel Pass

​Update Sentinel Pass

​Delete Sentinel Pass

​Rotate Key

​Revoke Sentinel Pass

​Activate Sentinel Pass

​Get Activity Logs

​Export Activity Logs

​Get Usage Metrics

​Response Shape

​Caching and Rate Limits

Build docs developers (and LLMs) love

Create Sentinel Pass

List Sentinel Passes

Get Sentinel Pass

Update Sentinel Pass

Delete Sentinel Pass

Rotate Key

Revoke Sentinel Pass

Activate Sentinel Pass

Get Activity Logs

Export Activity Logs

Get Usage Metrics

Response Shape

Caching and Rate Limits