Roles

Deletes a custom role, like Roles → Delete in the app.

Requires ManageRoles and an Idempotency-Key header. The role and its permissions are removed for good on the hosted web app and API (there is no restore); installed desktop and back-office apps that sync the organization may keep listing it until they are reset. Built-in roles (OrganizationAdmin, Manager, User) have no id and cannot be deleted. While any account (active or deactivated) still holds the role the delete is refused with 409, whose detail says how many; either remove it from them first (PATCH /api/v1/users/{id} with the remaining customRoleIds) or repeat with ?unassignUsers=true to take it away from every account in the same call. Those accounts are refused its permission-gated actions at once; menus in a signed-in browser session catch up within about 5 minutes, and API keys minted by them lose the permissions within 60 seconds. A 409 is stored against its Idempotency-Key for 24 hours like any other result, so every retry after a 409 (whether you unassigned the holders first or add ?unassignUsers=true) needs a new Idempotency-Key; resending the old one replays the 409. Example: DELETE /api/v1/roles/4?unassignUsers=true.

delete/api/v1/roles/{id}

Request

  • Base URL: https://app.flexonthejob.com
  • URL: https://app.flexonthejob.com/api/v1/roles/{id}
  • Auth: HTTP bearer

Path parameters

idinteger required

Custom role id (from GET /api/v1/roles). Example: 4.

Query parameters

unassignUsersboolean

When true, remove the role from every account holding it and then delete it; when false (default) the delete is refused with 409 while any account holds it. Example: true.

Response

Deleted; id is the deleted role and message names how many accounts lost it.

idinteger

Id of the resource the operation acted on (e.g. the job id).

messagestring nullable

Human-readable confirmation from the service (e.g. "Job started."). May be null.

warningstring nullable

Non-fatal problem encountered while completing the operation (e.g. a notification email that could not be sent). Null when there was none.

Changes

No recorded changes to this operation across all 1 revision of this API.