Extend Session

Extends an active session's expiration time by the specified number of hours. The new expiration time cannot exceed the organization's tier-based maximum duration (Free: 2 hours, Business+: 24 hours). Use this when the user needs more time without creating a new session.

Request

POST /sessions/{id}/extend

Path Parameters

Parameter	Type	Required	Description
id	string (UUID)	Yes	Unique identifier of the session to extend

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

{
  "additionalHours": 2
}

Request Fields

Field	Type	Required	Description
additionalHours	integer	Yes	Number of hours to add to the current expiration time. Minimum: 1. Total duration cannot exceed tier/role maximum.

Response

Returns a SessionResponse object with the updated expiresAt timestamp.

{
  "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": "ACTIVE",
  "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": "APPLIED",
      "providerRuleId": "sgr-0123456789abcdef0",
      "appliedAt": "2026-02-18T10:30:15Z",
      "removedAt": null,
      "errorMessage": null
    }
  ],
  "createdAt": "2026-02-18T10:30:00Z"
}

Response Fields

All fields are identical to the Start Session endpoint response. The expiresAt field reflects the new expiration time.

Error Responses

Status Code	Error	Description
400	Bad Request	additionalHours is less than 1, or extension would exceed maximum allowed duration for the user's tier/role
401	Unauthorized	Invalid or missing authentication
403	Forbidden	Session belongs to different user (or API key lacks sessions:write)
404	Not Found	Session does not exist
409	Conflict	Session is not in an extendable state (already expired, cancelled, or expiring)

Example

Request with JWT

curl -X POST https://api.entryguard.io/api/v1/sessions/3fa85f64-5717-4362-b98f-9ddd36e4b010/extend \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "additionalHours": 2
  }'

Request with API Key

curl -X POST https://api.entryguard.io/api/v1/sessions/3fa85f64-5717-4362-b98f-9ddd36e4b010/extend \
  -H "X-API-Key: eg_live_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "additionalHours": 4
  }'

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": "ACTIVE",
  "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": "APPLIED",
      "providerRuleId": "sgr-0123456789abcdef0",
      "appliedAt": "2026-02-18T10:30:15Z",
      "removedAt": null,
      "errorMessage": null
    }
  ],
  "createdAt": "2026-02-18T10:30:00Z"
}

Maximum Duration Limits

Tier	Maximum Total Duration
Free	2 hours
Business	24 hours
Premium	24 hours
Enterprise	24 hours

The additionalHours value plus the time already elapsed since startedAt cannot exceed the maximum for the user's tier.

Error Example - Exceeding Maximum

curl -X POST https://api.entryguard.io/api/v1/sessions/3fa85f64-5717-4362-b98f-9ddd36e4b010/extend \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "additionalHours": 10
  }'

Response (for Free tier user):

{
  "status": 400,
  "error": "Bad Request",
  "message": "Extension would exceed maximum session duration of 2 hours for Free tier",
  "timestamp": "2026-02-18T11:15:30Z"
}

Use Cases

• User needs more time to complete work without interruption
• Avoiding the overhead of stopping and restarting a session
• Maintaining continuous access during long-running operations
• "Keep alive" functionality in client applications
• Responding to user notification that session is about to expire