Clear configuration, entry points, and bound resources that affect future sessions for an Identity.
POST /api/v1/forward/identities/{identity_id}/clear
The Identity itself is retained after the operation and can continue to create new sessions. New sessions no longer use the previous configuration, schedules, or resource bindings. Historical sessions remain archived.
Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <PAT or SAT> |
Content-Type | No | Use application/json when the request body is not empty. |
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
identity_id | string | Yes | Forward Identity ID. |
Body parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
reason | string | No | Reason for the cleanup. Used only to record the caller's intent. |
Example request
Example response
HTTP 200 OK
Response fields
| Field | Type | Description |
|---|---|---|
identity_id | string | ID of the cleared Identity. |
status | string | Cleanup status. The value is completed on success. |
completed_at | string | Time when Forward completed the cleanup, in RFC 3339 format. |
summary.identity_configs_archived | number | Number of Identity Configs processed. |
summary.resource_bindings_archived | number | Number of resource bindings processed. |
summary.identity_owned_resources_archived | number | Number of Identity-owned resources processed. |
summary.schedules_archived | number | Number of schedules processed. |
summary.schedule_runs_skipped | number | Number of pending Schedule Runs skipped. |
summary.sessions_archived | number | Number of sessions processed. |
Errors
| HTTP | Type | Code | Trigger |
|---|---|---|---|
| 400 | invalid_request_error | - | The request body or parameters are invalid. |
| 401 | authentication_error | authentication_required | The PAT or SAT is invalid, expired, or missing. |
| 404 | not_found_error | - | The Identity does not exist or is not visible to the caller. |
| 409 | conflict_error | ADMIN_IDENTITY_READ_ONLY or - | The target is the read-only Admin Identity, or the Identity has a Schedule Run in progress. |
Notes
- This endpoint does not delete the Identity itself.
- You can create new sessions, configurations, and schedules after the cleanup.
- Repeating the operation does not restore previously processed resources or configurations.