API Reference — Batch 12

API Reference — Batch 12

This batch documents auth security endpoints and model registry status management endpoints.

Base URL: https://api.arbitex.ai

Authentication: All endpoints require a Bearer token. Admin endpoints require a token belonging to a user with the admin or security_auditor role unless noted.

---

Auth Security Endpoints

GET /v1/audit/events

Retrieve audit log events. Supports the user_id=me alias for self-service access and action=auth.* wildcard for filtering to authentication events.

Authentication: Any authenticated user (self-service with user_id=me); admin role required for arbitrary user_id.

Query Parameters

Parameter	Type	Required	Description
user_id	string	No	Filter by user ID. Use the literal string me to query the authenticated user’s own events. Admin role required for any other value.
action	string	No	Filter by action. Supports exact match (auth.login.success) and wildcard suffix (auth.*). Multiple values comma-separated.
from	ISO 8601	No	Start of date range (inclusive). Default: 90 days ago.
to	ISO 8601	No	End of date range (inclusive). Default: now.
limit	integer	No	Maximum records to return. Range: 1–1000. Default: 100.
cursor	string	No	Pagination cursor from a previous response’s next_cursor field.

Auth Action Values

The action=auth.* wildcard matches all 12 auth event types:

auth.login.success
auth.login.failure
auth.login.mfa_required
auth.login.mfa_success
auth.login.mfa_failure
auth.logout
auth.session.revoked
auth.session.expired
auth.token.issued
auth.token.revoked
auth.password.changed
auth.saml.sso

Request

# Self-service: authenticated user's own auth events
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.arbitex.ai/v1/audit/events?user_id=me&action=auth.*&limit=50"

# Admin: auth events for a specific user
curl -H "Authorization: Bearer $ADMIN_TOKEN" \
  "https://api.arbitex.ai/v1/audit/events?user_id=user_abc123&action=auth.*"

# All org auth events in a date range
curl -H "Authorization: Bearer $ADMIN_TOKEN" \
  "https://api.arbitex.ai/v1/audit/events?action=auth.*&from=2026-03-01T00:00:00Z&to=2026-03-13T23:59:59Z"

Response

{
  "events": [
    {
      "id": "evt_01HXK2M3N4P5Q6R7S8T9",
      "time": "2026-03-13T18:42:11Z",
      "action": "auth.login.success",
      "actor": {
        "user_id": "user_abc123",
        "email": "alice@example.com"
      },
      "target": {
        "type": "session",
        "id": "sess_01HXK2M3N4P5Q6R7"
      },
      "src": {
        "ip": "203.0.113.42",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"
      },
      "geo": {
        "city": "New York",
        "region": "New York",
        "country_name": "United States",
        "country_code": "US",
        "latitude": 40.7128,
        "longitude": -74.0060
      },
      "detail": {
        "mfa_used": true,
        "mfa_method": "totp"
      }
    }
  ],
  "total": 142,
  "limit": 50,
  "next_cursor": "eyJvZmZzZXQiOjUwfQ=="
}

Field Reference

Field	Type	Description
id	string	Unique event ID (ULID format)
time	ISO 8601	Event timestamp UTC
action	string	Event type from the 12-value enum
actor.user_id	string	User ID of the authenticating principal
actor.email	string	Email address of the authenticating principal
target.type	string	Resource type affected (session, token)
target.id	string	Resource ID affected
src.ip	string	Source IP address
src.user_agent	string	Raw HTTP User-Agent string
geo.*	object	GeoIP-enriched location; may be absent for private IPs
detail	object	Event-specific supplementary fields (varies by action)

Error Responses

Status	Code	Description
400	invalid_filter	action wildcard pattern is malformed or from/to not valid ISO 8601
403	forbidden	Non-admin user specified a user_id other than me
404	user_not_found	Specified user_id does not exist in the organization

---

GET /api/admin/sessions

List active sessions. Returns all currently valid sessions for the organization (admin) or filtered by user.

Authentication: Admin role required.

Query Parameters

Parameter	Type	Required	Description
user_id	string	No	Filter to sessions belonging to a specific user
limit	integer	No	Maximum records. Range: 1–500. Default: 100.
cursor	string	No	Pagination cursor

Request

# All active sessions in the org
curl -H "Authorization: Bearer $ADMIN_TOKEN" \
  "https://api.arbitex.ai/api/admin/sessions"

# Sessions for a specific user
curl -H "Authorization: Bearer $ADMIN_TOKEN" \
  "https://api.arbitex.ai/api/admin/sessions?user_id=user_abc123"

Response

{
  "sessions": [
    {
      "id": "sess_01HXK2M3N4P5Q6R7",
      "user_id": "user_abc123",
      "user_email": "alice@example.com",
      "created_at": "2026-03-13T18:42:11Z",
      "last_active_at": "2026-03-13T20:15:33Z",
      "expires_at": "2026-03-20T18:42:11Z",
      "src_ip": "203.0.113.42",
      "user_agent": "Mozilla/5.0 ...",
      "geo": {
        "city": "New York",
        "country_code": "US"
      },
      "device": {
        "browser": "Chrome",
        "browser_version": "122",
        "os": "macOS",
        "device_type": "desktop"
      }
    }
  ],
  "total": 47,
  "limit": 100,
  "next_cursor": null
}

Field Reference

Field	Type	Description
id	string	Session ID
user_id	string	Owner user ID
user_email	string	Owner email address
created_at	ISO 8601	Session creation time
last_active_at	ISO 8601	Most recent authenticated request on this session
expires_at	ISO 8601	Hard expiry time
src_ip	string	IP at session creation
user_agent	string	User-Agent at session creation
geo	object	GeoIP location at session creation
device	object	Parsed device information

Error Responses

Status	Code	Description
403	forbidden	Caller does not have admin role
404	user_not_found	Specified user_id does not exist

---

DELETE /api/admin/sessions/{id}

Force-terminate a single session by ID.

Authentication: Admin role required.

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Session ID to terminate

Request

curl -X DELETE \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  "https://api.arbitex.ai/api/admin/sessions/sess_01HXK2M3N4P5Q6R7"

Response

{
  "id": "sess_01HXK2M3N4P5Q6R7",
  "status": "revoked",
  "revoked_at": "2026-03-13T21:00:00Z",
  "audit_event_id": "evt_01HXK9Z1A2B3C4D5"
}

The session is invalidated immediately. Subsequent requests using this session token receive 401 Unauthorized.

An auth.session.revoked audit event is created. The event’s actor is the calling admin; target.id is the revoked session ID; detail.target_user_id is the session owner.

Error Responses

Status	Code	Description
403	forbidden	Caller does not have admin role
404	session_not_found	Session ID not found or already expired/revoked
409	session_already_revoked	Session was already revoked before this call

---

DELETE /api/admin/users/{id}/sessions

Force-logout all active sessions for a user. This is a bulk operation: all currently valid sessions belonging to the user are terminated atomically.

Authentication: Admin role required.

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	User ID whose sessions should all be terminated

Request

curl -X DELETE \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  "https://api.arbitex.ai/api/admin/users/user_abc123/sessions"

Response

{
  "user_id": "user_abc123",
  "sessions_revoked": 3,
  "revoked_at": "2026-03-13T21:00:00Z",
  "audit_event_id": "evt_01HXK9Z1A2B3C4D6"
}

Field Reference

Field	Type	Description
user_id	string	Target user ID
sessions_revoked	integer	Count of sessions terminated by this call
revoked_at	ISO 8601	Timestamp of the bulk revocation
audit_event_id	string	ID of the auth.session.revoked audit event created (one event with detail.bulk: true)

Returns { "sessions_revoked": 0 } (HTTP 200) if the user has no active sessions — not an error.

Error Responses

Status	Code	Description
403	forbidden	Caller does not have admin role
404	user_not_found	Specified user ID does not exist

---

Model Registry Status Endpoints

POST /api/admin/models/{id}/status

Update the status of a model in the model registry. This endpoint drives the model validation lifecycle state machine.

Authentication: Admin role required.

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Model registry ID

Valid Status Transitions

The model lifecycle follows this state machine:

draft → pending_review → validated
draft → deprecated
pending_review → validated
pending_review → draft          (send back for revision)
validated → deprecated
deprecated → draft              (re-activate for re-validation)

Attempting an invalid transition returns 409 invalid_transition.

Request Body

{
  "status": "validated",
  "reason": "Passed all validation checks including red-team evaluation.",
  "effective_at": "2026-03-14T00:00:00Z"
}

Field	Type	Required	Description
status	string	Yes	Target status. One of: draft, pending_review, validated, deprecated
reason	string	No	Human-readable reason for the transition. Stored in the status history.
effective_at	ISO 8601	No	When the status change takes effect. Defaults to the time of the API call. Future-dated transitions are scheduled but not yet enforced until the effective time.

Request

curl -X POST \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "validated",
    "reason": "Completed red-team review and bias evaluation. Approved for production use."
  }' \
  "https://api.arbitex.ai/api/admin/models/model_abc123/status"

Response

{
  "model_id": "model_abc123",
  "previous_status": "pending_review",
  "status": "validated",
  "reason": "Completed red-team review and bias evaluation. Approved for production use.",
  "effective_at": "2026-03-13T21:00:00Z",
  "updated_by": "admin@example.com",
  "updated_at": "2026-03-13T21:00:00Z"
}

Field Reference

Field	Type	Description
model_id	string	Model registry ID
previous_status	string	Status before this transition
status	string	New status after this transition
reason	string	Reason text as submitted
effective_at	ISO 8601	When the status is/was applied
updated_by	string	Email of the admin who made the change
updated_at	ISO 8601	Timestamp of this API call

Error Responses

Status	Code	Description
400	invalid_status	status value not in the valid enum
403	forbidden	Caller does not have admin role
404	model_not_found	Model ID not in the registry
409	invalid_transition	The requested status transition is not permitted by the state machine

---

GET /api/admin/models/{id}/status/history

Retrieve the full status transition history for a model. Returns all transitions from creation to present in chronological order.

Authentication: Admin role required.

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Model registry ID

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Maximum records. Range: 1–200. Default: 50.
cursor	string	No	Pagination cursor

Request

curl -H "Authorization: Bearer $ADMIN_TOKEN" \
  "https://api.arbitex.ai/api/admin/models/model_abc123/status/history"

Response

{
  "model_id": "model_abc123",
  "current_status": "validated",
  "history": [
    {
      "id": "hist_01HXK2M3N4P5Q6R7",
      "from_status": null,
      "to_status": "draft",
      "reason": "Auto-discovered via audit log scan.",
      "effective_at": "2026-03-01T10:00:00Z",
      "updated_by": "system",
      "updated_at": "2026-03-01T10:00:00Z"
    },
    {
      "id": "hist_01HXK3M4N5P6Q7R8",
      "from_status": "draft",
      "to_status": "pending_review",
      "reason": "Submitted for red-team evaluation.",
      "effective_at": "2026-03-10T14:30:00Z",
      "updated_by": "admin@example.com",
      "updated_at": "2026-03-10T14:30:00Z"
    },
    {
      "id": "hist_01HXK9Z1A2B3C4D7",
      "from_status": "pending_review",
      "to_status": "validated",
      "reason": "Completed red-team review and bias evaluation.",
      "effective_at": "2026-03-13T21:00:00Z",
      "updated_by": "admin@example.com",
      "updated_at": "2026-03-13T21:00:00Z"
    }
  ],
  "total": 3,
  "limit": 50,
  "next_cursor": null
}

Field Reference

Field	Type	Description
model_id	string	Model registry ID
current_status	string	Current status of the model
history[].id	string	Unique transition record ID
history[].from_status	string | null	Previous status; null for initial creation
history[].to_status	string	Status after this transition
history[].reason	string	Reason text as recorded
history[].effective_at	ISO 8601	When this status became effective
history[].updated_by	string	Email or "system" for auto-discovered transitions
history[].updated_at	ISO 8601	Timestamp of the API call that recorded this transition

Error Responses

Status	Code	Description
403	forbidden	Caller does not have admin role
404	model_not_found	Model ID not in the registry

---

Related Reference

• API Reference — Batch 11 (Model Registry)
• Model Registry API Reference
• Account Security Monitor
• Model Risk Management Guide