Start Session

Creates a new session that whitelists the user's IP address on all assigned cloud resources. IP addresses can be auto-detected from the request or explicitly provided. The session applies IP rules asynchronously - poll the session status to track progress.

Request

POST /sessions

Authentication

Requires either:

• Bearer JWT token with USER role, OR
• API Key with sessions:write permission

Authorization: Bearer <access_token>

OR

X-API-Key: <api_key>

Request Body

All fields are optional. If IP addresses are not provided, they will be auto-detected from the request.

{
  "durationHours": 2,
  "ipv4Address": "203.0.113.42",
  "ipv6Address": "2001:db8::1"
}

Request Fields

Field	Type	Required	Description
durationHours	integer	No	Session duration in hours. Defaults to entryguard.session.default-duration-hours from server config. Maximum is tier/role-based (Free: 2h, Business+: 24h).
ipv4Address	string	No	Explicit IPv4 address to whitelist. If omitted, auto-detected from request headers (X-Forwarded-For, X-Real-IP, or remote address).
ipv6Address	string	No	Explicit IPv6 address to whitelist. If omitted, auto-detected if request is over IPv6.

Response

Returns a SessionResponse object. Initial status is PENDING while IP rules are being applied asynchronously.

{
  "id": "3fa85f64-5717-4362-b98f-9ddd36e4b010",
  "userId": "7c8b3f21-4d92-4a8e-9f3a-1e6c5b9d0a2b",
  "userName": "John Doe",
  "userEmail": "[email protected]",
  "ipv4Address": "203.0.113.42",
  "ipv6Address": "2001:db8::1",
  "status": "PENDING",
  "startedAt": "2026-02-18T10:30:00Z",
  "expiresAt": "2026-02-18T12:30:00Z",
  "endedAt": null,
  "endedReason": null,
  "resourceIps": [
    {
      "id": "8e9f2a3b-1c4d-5e6f-7a8b-9c0d1e2f3a4b",
      "resourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "resourceName": "Production Database SG",
      "ipVersion": 4,
      "ipAddress": "203.0.113.42",
      "status": "PENDING",
      "providerRuleId": null,
      "appliedAt": null,
      "removedAt": null,
      "errorMessage": null
    }
  ],
  "createdAt": "2026-02-18T10:30:00Z"
}

Response Fields

Field	Type	Description
id	string (UUID)	Unique session identifier
userId	string (UUID)	ID of the user who started the session
userName	string	Full name of the user
userEmail	string	Email address of the user
ipv4Address	string	IPv4 address whitelisted for this session (if applicable)
ipv6Address	string	IPv6 address whitelisted for this session (if applicable)
status	string	Session status: PENDING, ACTIVE, PARTIAL, FAILED, EXPIRING, EXPIRED, CANCELLED
startedAt	string (ISO 8601)	Timestamp when session was created
expiresAt	string (ISO 8601)	Timestamp when session will automatically expire
endedAt	string (ISO 8601)	Timestamp when session ended (null if active)
endedReason	string	Reason session ended: EXPIRED, MANUAL, ADMIN (null if active)
resourceIps	array	List of IP rules for each resource (see below)
createdAt	string (ISO 8601)	Timestamp when session record was created

ResourceIp Fields

Field	Type	Description
id	string (UUID)	Unique identifier for this resource IP rule
resourceId	string (UUID)	ID of the cloud resource
resourceName	string	Name of the cloud resource
ipVersion	integer	IP version: 4 or 6
ipAddress	string	IP address for this specific rule
status	string	Rule status: PENDING, APPLIED, FAILED, REMOVING, REMOVED
providerRuleId	string	Cloud provider's rule identifier (e.g., AWS SG rule ID)
appliedAt	string (ISO 8601)	Timestamp when rule was successfully applied
removedAt	string (ISO 8601)	Timestamp when rule was removed
errorMessage	string	Error description if status is FAILED

Error Responses

Status Code	Error	Description
400	Bad Request	Invalid IP address format or duration exceeds maximum
401	Unauthorized	Invalid or missing authentication
403	Forbidden	API key lacks sessions:write permission or organization suspended
409	Conflict	Active session already exists for this user and IP combination

Example

Request with Auto-Detection

curl -X POST https://api.entryguard.io/api/v1/sessions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{}'

Request with Explicit IP

curl -X POST https://api.entryguard.io/api/v1/sessions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "durationHours": 4,
    "ipv4Address": "203.0.113.42"
  }'

Request with API Key

curl -X POST https://api.entryguard.io/api/v1/sessions \
  -H "X-API-Key: eg_live_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "durationHours": 2
  }'

Response

{
  "id": "3fa85f64-5717-4362-b98f-9ddd36e4b010",
  "userId": "7c8b3f21-4d92-4a8e-9f3a-1e6c5b9d0a2b",
  "userName": "John Doe",
  "userEmail": "[email protected]",
  "ipv4Address": "203.0.113.42",
  "ipv6Address": null,
  "status": "PENDING",
  "startedAt": "2026-02-18T10:30:00Z",
  "expiresAt": "2026-02-18T14:30:00Z",
  "endedAt": null,
  "endedReason": null,
  "resourceIps": [
    {
      "id": "8e9f2a3b-1c4d-5e6f-7a8b-9c0d1e2f3a4b",
      "resourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "resourceName": "Production Database SG",
      "ipVersion": 4,
      "ipAddress": "203.0.113.42",
      "status": "PENDING",
      "providerRuleId": null,
      "appliedAt": null,
      "removedAt": null,
      "errorMessage": null
    },
    {
      "id": "9f0a1b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c",
      "resourceId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "resourceName": "Staging API SG",
      "ipVersion": 4,
      "ipAddress": "203.0.113.42",
      "status": "PENDING",
      "providerRuleId": null,
      "appliedAt": null,
      "removedAt": null,
      "errorMessage": null
    }
  ],
  "createdAt": "2026-02-18T10:30:00Z"
}

Session Status Flow

1. PENDING - Initial state, IP rules are being applied asynchronously
2. ACTIVE - All IP rules applied successfully
3. PARTIAL - Some rules applied, some failed
4. FAILED - All rules failed to apply
5. EXPIRING - Session is being cleaned up (after expiration or manual stop)
6. EXPIRED - Session ended and all rules removed
7. CANCELLED - Session was manually stopped before expiration

Polling for Status

IP rules are applied asynchronously. Poll GET /sessions/{id} to check status updates:

curl https://api.entryguard.io/api/v1/sessions/3fa85f64-5717-4362-b98f-9ddd36e4b010 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

When all resourceIps have status: "APPLIED", the session is fully active.