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 (Forward-side ownership registrations). |
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 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.
Cleaning up Identity-owned resources
Cleanup handles resources owned by this Identity according to their type:
| Resource type | Behavior |
|---|---|
| Environment | Archive without deleting. |
| Vault | Archive every active Credential in the Vault first, then archive the Vault. |
| Memory Store | Follow the existing cleanup behavior. |
completed. Failed archive operations are retried a limited number of times and logged. You can call this endpoint again to continue cleanup.
Archiving the Vault alone does not complete cleanup: all active Credentials in it must be archived first. Credentials are read page by page until none remain active.