API Reference

Auto-generated

Sessions

API reference for sessions endpoints.

Auto-generated

This page was generated from the OpenAPI spec. Runmake generate-docs to refresh after spec changes.

GET /api/v1/sessions/alerts/preferences

GET

/api/v1/sessions/alerts/preferences

Get session alert preferences

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/sessions/alerts/preferences \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "email_on_new_ip": true,
  "email_on_unusual_volume": true,
  "email_on_every_use": true,
  "email_on_failure_streak": true,
  "herald_alerts": true
}

PUT /api/v1/sessions/alerts/preferences

PUT

/api/v1/sessions/alerts/preferences

Update session alert preferences

Parameters

Name	Type	Required	Description
email_on_new_ip	`boolean`	Optional	email_on_new_ip
email_on_unusual_volume	`boolean`	Optional	email_on_unusual_volume
email_on_every_use	`boolean`	Optional	email_on_every_use
email_on_failure_streak	`boolean`	Optional	email_on_failure_streak
herald_alerts	`boolean`	Optional	herald_alerts

Request Example

Bash

curl -X PUT https://api.alterlab.io/api/v1/sessions/alerts/preferences \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "email_on_new_ip": true,
  "email_on_unusual_volume": true,
  "email_on_every_use": true,
  "email_on_failure_streak": true,
  "herald_alerts": true
}

POST /api/v1/sessions/health-check

POST

/api/v1/sessions/health-check

Trigger Session Health Check

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/sessions/health-check \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "total_checked": 0,
  "expiring_soon": 0,
  "already_expired": 0,
  "needs_revalidation": 0,
  "notifications_sent": 0
}

POST /api/v1/sessions/kill-all

POST

/api/v1/sessions/kill-all

Emergency: deactivate all sessions

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/sessions/kill-all \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "deactivated_count": 0,
  "deactivated_session_ids": [],
  "propagated": true
}

GET /api/v1/sessions/org

GET

/api/v1/sessions/org

List organization sessions

Parameters

Name	Type	Required	Description
organization_id	`string`	Required	Organization ID to list sessions for

Request Example

Bash

curl -X GET 'https://api.alterlab.io/api/v1/sessions/org?organization_id=<organization_id>' \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "personal_sessions": [],
  "team_sessions": [],
  "total_personal": 0,
  "total_team": 0
}

POST /api/v1/sessions/privacy/consent

POST

/api/v1/sessions/privacy/consent

Record Consent

Parameters

Name	Type	Required	Description
consent	`boolean`	Required	Explicit consent to process session cookie data. Must be true to create sessions.

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/sessions/privacy/consent \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "consent": false
  }'

Response Example

JSON

{
  "consent_given_at": "example",
  "message": "example"
}

DELETE /api/v1/sessions/privacy/delete-all

DELETE

/api/v1/sessions/privacy/delete-all

Delete All Session Data

Request Example

Bash

curl -X DELETE https://api.alterlab.io/api/v1/sessions/privacy/delete-all \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "sessions_deleted": 0,
  "audit_entries_redacted": 0,
  "redis_keys_purged": 0,
  "completed_at": "example"
}

GET /api/v1/sessions/privacy/export

GET

/api/v1/sessions/privacy/export

Export Session Data

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/sessions/privacy/export \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "user_id": "example",
  "exported_at": "example",
  "sessions": [],
  "total_sessions": 0,
  "data_processing_info": "example"
}

GET /api/v1/sessions/privacy/retention

GET

/api/v1/sessions/privacy/retention

Get Retention Policy

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/sessions/privacy/retention \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "inactive_retention_days": 0,
  "expired_retention_days": 0,
  "warning_days_before_deletion": 0,
  "data_region": "example"
}

DELETE /api/v1/sessions/privacy/{session_id}/hard-delete

DELETE

/api/v1/sessions/privacy/{session_id}/hard-delete

Hard Delete Single Session

Parameters

Name	Type	Required	Description
session_id	`string`	Required	Session integration ID

Request Example

Bash

curl -X DELETE https://api.alterlab.io/api/v1/sessions/privacy/<session_id>/hard-delete \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "sessions_deleted": 0,
  "audit_entries_redacted": 0,
  "redis_keys_purged": 0,
  "completed_at": "example"
}

GET /api/v1/sessions/profiles

GET

/api/v1/sessions/profiles

List session profiles

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/sessions/profiles \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "profiles": [],
  "categories": {},
  "total": 0
}

GET /api/v1/sessions/profiles/{slug}

GET

/api/v1/sessions/profiles/{slug}

Get a session profile

Parameters

Name	Type	Required	Description
slug	`string`	Required	Profile slug (e.g. 'amazon') or domain (e.g. 'amazon.com')

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/sessions/profiles/<slug> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "slug": "example",
  "display_name": "example",
  "category": "example",
  "icon": "example",
  "domains": [],
  "required_cookies": []
}

GET /api/v1/sessions/public-key

GET

/api/v1/sessions/public-key

Get encryption public key

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/sessions/public-key \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "available": true,
  "key": "example",
  "version": "example",
  "algorithm": "example"
}

GET /api/v1/sessions/{session_id}/access-log

GET

/api/v1/sessions/{session_id}/access-log

Get session access log

Parameters

Name	Type	Required	Description
session_id	`string`	Required	Session integration ID
limit	`integer`	Optional	Max entries to returnDefault: `50`

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/sessions/<session_id>/access-log \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "entries": [],
  "total": 0,
  "known_ip_count": 0
}

PATCH /api/v1/sessions/{session_id}/auto-refresh

PATCH

/api/v1/sessions/{session_id}/auto-refresh

Update auto-refresh settings

Parameters

Name	Type	Required	Description
session_id	`string`	Required	Session integration ID
auto_refresh_enabled	`boolean`	Optional	auto_refresh_enabled
notify_before_expiry	`boolean`	Optional	notify_before_expiry
notify_on_failure	`boolean`	Optional	notify_on_failure

Request Example

Bash

curl -X PATCH https://api.alterlab.io/api/v1/sessions/<session_id>/auto-refresh \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "name": "example",
  "domain": "example",
  "cookie_names": [],
  "header_names": "example",
  "encryption_mode": "example"
}

POST /api/v1/sessions/{session_id}/deactivate

POST

/api/v1/sessions/{session_id}/deactivate

Deactivate a session

Parameters

Name	Type	Required	Description
session_id	`string`	Required	Session integration ID

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/sessions/<session_id>/deactivate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "deactivated": true,
  "propagated": "example",
  "reason": "example"
}

POST /api/v1/sessions/{session_id}/reactivate

POST

/api/v1/sessions/{session_id}/reactivate

Reactivate a session

Parameters

Name	Type	Required	Description
session_id	`string`	Required	Session integration ID

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/sessions/<session_id>/reactivate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "reactivated": true,
  "reason": "example"
}

GET /api/v1/sessions/{session_id}/security

GET

/api/v1/sessions/{session_id}/security

Get session security summary

Parameters

Name	Type	Required	Description
session_id	`string`	Required	Session integration ID

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/sessions/<session_id>/security \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "known_ip_count": 0,
  "recent_access_count": 0,
  "alert_preferences": "example",
  "last_access": "example"
}

Last updated: March 2026

API Reference

Auto-generated

Sessions

API reference for sessions endpoints.

Auto-generated

This page was generated from the OpenAPI spec. Runmake generate-docs to refresh after spec changes.

GET /api/v1/sessions/alerts/preferences

GET

/api/v1/sessions/alerts/preferences

Get session alert preferences

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/sessions/alerts/preferences \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "email_on_new_ip": true,
  "email_on_unusual_volume": true,
  "email_on_every_use": true,
  "email_on_failure_streak": true,
  "herald_alerts": true
}

PUT /api/v1/sessions/alerts/preferences

PUT

/api/v1/sessions/alerts/preferences

Update session alert preferences

Parameters

Name	Type	Required	Description
email_on_new_ip	`boolean`	Optional	email_on_new_ip
email_on_unusual_volume	`boolean`	Optional	email_on_unusual_volume
email_on_every_use	`boolean`	Optional	email_on_every_use
email_on_failure_streak	`boolean`	Optional	email_on_failure_streak
herald_alerts	`boolean`	Optional	herald_alerts

Request Example

Bash

curl -X PUT https://api.alterlab.io/api/v1/sessions/alerts/preferences \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "email_on_new_ip": true,
  "email_on_unusual_volume": true,
  "email_on_every_use": true,
  "email_on_failure_streak": true,
  "herald_alerts": true
}

POST /api/v1/sessions/health-check

POST

/api/v1/sessions/health-check

Trigger Session Health Check

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/sessions/health-check \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "total_checked": 0,
  "expiring_soon": 0,
  "already_expired": 0,
  "needs_revalidation": 0,
  "notifications_sent": 0
}

POST /api/v1/sessions/kill-all

POST

/api/v1/sessions/kill-all

Emergency: deactivate all sessions

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/sessions/kill-all \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "deactivated_count": 0,
  "deactivated_session_ids": [],
  "propagated": true
}

GET /api/v1/sessions/org

GET

/api/v1/sessions/org

List organization sessions

Parameters

Name	Type	Required	Description
organization_id	`string`	Required	Organization ID to list sessions for

Request Example

Bash

curl -X GET 'https://api.alterlab.io/api/v1/sessions/org?organization_id=<organization_id>' \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "personal_sessions": [],
  "team_sessions": [],
  "total_personal": 0,
  "total_team": 0
}

POST /api/v1/sessions/privacy/consent

POST

/api/v1/sessions/privacy/consent

Record Consent

Parameters

Name	Type	Required	Description
consent	`boolean`	Required	Explicit consent to process session cookie data. Must be true to create sessions.

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/sessions/privacy/consent \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "consent": false
  }'

Response Example

JSON

{
  "consent_given_at": "example",
  "message": "example"
}

DELETE /api/v1/sessions/privacy/delete-all

DELETE

/api/v1/sessions/privacy/delete-all

Delete All Session Data

Request Example

Bash

curl -X DELETE https://api.alterlab.io/api/v1/sessions/privacy/delete-all \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "sessions_deleted": 0,
  "audit_entries_redacted": 0,
  "redis_keys_purged": 0,
  "completed_at": "example"
}

GET /api/v1/sessions/privacy/export

GET

/api/v1/sessions/privacy/export

Export Session Data

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/sessions/privacy/export \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "user_id": "example",
  "exported_at": "example",
  "sessions": [],
  "total_sessions": 0,
  "data_processing_info": "example"
}

GET /api/v1/sessions/privacy/retention

GET

/api/v1/sessions/privacy/retention

Get Retention Policy

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/sessions/privacy/retention \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "inactive_retention_days": 0,
  "expired_retention_days": 0,
  "warning_days_before_deletion": 0,
  "data_region": "example"
}

DELETE /api/v1/sessions/privacy/{session_id}/hard-delete

DELETE

/api/v1/sessions/privacy/{session_id}/hard-delete

Hard Delete Single Session

Parameters

Name	Type	Required	Description
session_id	`string`	Required	Session integration ID

Request Example

Bash

curl -X DELETE https://api.alterlab.io/api/v1/sessions/privacy/<session_id>/hard-delete \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "sessions_deleted": 0,
  "audit_entries_redacted": 0,
  "redis_keys_purged": 0,
  "completed_at": "example"
}

GET /api/v1/sessions/profiles

GET

/api/v1/sessions/profiles

List session profiles

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/sessions/profiles \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "profiles": [],
  "categories": {},
  "total": 0
}

GET /api/v1/sessions/profiles/{slug}

GET

/api/v1/sessions/profiles/{slug}

Get a session profile

Parameters

Name	Type	Required	Description
slug	`string`	Required	Profile slug (e.g. 'amazon') or domain (e.g. 'amazon.com')

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/sessions/profiles/<slug> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "slug": "example",
  "display_name": "example",
  "category": "example",
  "icon": "example",
  "domains": [],
  "required_cookies": []
}

GET /api/v1/sessions/public-key

GET

/api/v1/sessions/public-key

Get encryption public key

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/sessions/public-key \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "available": true,
  "key": "example",
  "version": "example",
  "algorithm": "example"
}

GET /api/v1/sessions/{session_id}/access-log

GET

/api/v1/sessions/{session_id}/access-log

Get session access log

Parameters

Name	Type	Required	Description
session_id	`string`	Required	Session integration ID
limit	`integer`	Optional	Max entries to returnDefault: `50`

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/sessions/<session_id>/access-log \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "entries": [],
  "total": 0,
  "known_ip_count": 0
}

PATCH /api/v1/sessions/{session_id}/auto-refresh

PATCH

/api/v1/sessions/{session_id}/auto-refresh

Update auto-refresh settings

Parameters

Name	Type	Required	Description
session_id	`string`	Required	Session integration ID
auto_refresh_enabled	`boolean`	Optional	auto_refresh_enabled
notify_before_expiry	`boolean`	Optional	notify_before_expiry
notify_on_failure	`boolean`	Optional	notify_on_failure

Request Example

Bash

curl -X PATCH https://api.alterlab.io/api/v1/sessions/<session_id>/auto-refresh \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "name": "example",
  "domain": "example",
  "cookie_names": [],
  "header_names": "example",
  "encryption_mode": "example"
}

POST /api/v1/sessions/{session_id}/deactivate

POST

/api/v1/sessions/{session_id}/deactivate

Deactivate a session

Parameters

Name	Type	Required	Description
session_id	`string`	Required	Session integration ID

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/sessions/<session_id>/deactivate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "deactivated": true,
  "propagated": "example",
  "reason": "example"
}

POST /api/v1/sessions/{session_id}/reactivate

POST

/api/v1/sessions/{session_id}/reactivate

Reactivate a session

Parameters

Name	Type	Required	Description
session_id	`string`	Required	Session integration ID

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/sessions/<session_id>/reactivate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "reactivated": true,
  "reason": "example"
}

GET /api/v1/sessions/{session_id}/security

GET

/api/v1/sessions/{session_id}/security

Get session security summary

Parameters

Name	Type	Required	Description
session_id	`string`	Required	Session integration ID

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/sessions/<session_id>/security \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "known_ip_count": 0,
  "recent_access_count": 0,
  "alert_preferences": "example",
  "last_access": "example"
}

Last updated: March 2026