Deboard an AWS account

DELETE 
/aws-accounts/:accountId/deboard

Deletes Prism's record of an AWS account, refusing while permission set assignments still point at it. This is the removal path the Prism console uses, and the only one this API documents.

"Deboard" does not mean "tear down in AWS". Despite the name, this operation makes no AWS call whatsoever. Nothing inside the AWS account is undone: the SAML identity provider Prism created, the IAM roles it cut and the policies attached to them all remain, and anything entitled to assume those roles still can. Deboarding removes Prism's record of the account, and nothing else.

The safety check is the point of this operation. Before deleting anything it counts the permission set assignments provisioning into this account, and if there are any it stops with 409 and changes nothing. That is what keeps a record from being removed out from under live assignments, which would leave those rows pointing at an account Prism no longer knows about, still coming back from GET /permission-set-assignments filtered by accountId, with nothing to reconcile them. Clear them with DELETE /permission-set-assignments/{id}, which does unbind each role from its principal in the identity provider, and then deboard.

Once the check passes, the record is removed outright and cannot be recovered. There is no soft delete, no archive and no undo. Onboarding the same account number again creates a fresh record with a new id and none of the old one's onboarding state.

Two limits on the safety check, worth knowing before you lean on it:

• An assignment whose permission set cannot be resolved (because the permission set has since been deleted, or because that lookup errors) is skipped by the check and does not block the deboard.
• The check and the delete are not one transaction, so an assignment created in the moment between them is orphaned rather than caught.

An account number your tenant does not have is not a 404 here. It returns 500: the not-found case has no branch of its own and falls through to the generic failure, so read error to tell a missing account from a genuine database failure, and expect a repeated deboard of the same account number to land there too. The 404 this operation does return comes from the tenant lookup that runs ahead of every operation, and means the tenant itself was not found.

Returns 200 with a body, not 204.

Request

Responses

200

The account had no assignments and its record was deleted. Nothing in the AWS account changed.

401

Authentication failed: the X-API-Token header was missing, malformed, expired or not recognised.

This response is text/plain, not JSON. It is written by http.Error in the authentication middleware, which runs before any handler and therefore before anything that would build a JSON envelope. A client that unconditionally JSON-parses response bodies will fail on this one, so check the status code first.

403

The token is valid, but it is not allowed to act on this tenant.

An API token is minted inside one tenant and stays bound to it for life. Sending it to a path whose tenant segment names a different tenant is refused here, in middleware, before the operation runs, so this says nothing about the resource you asked for, only about which tenant the path named. Check the tenant server variable against the console the token was created in.

404

No tenant matches the tenant segment of the request path, and nothing was deleted. Check the tenant server variable.

An account number that is not registered in your tenant is not reported here; that case is a 500, described below.

409

The account still has permission set assignments and nothing was deleted. The record is untouched and the account is still fully usable.

The error text names how many assignments are in the way, but not which ones. List them with GET /permission-set-assignments filtered by accountId, delete each through DELETE /permission-set-assignments/{id}, and retry.

500

The assignment check or the deletion itself failed. An account number that is not registered in your tenant also lands here, rather than on a 404. Read error to tell a missing account from a genuine database failure.