Onboard one AWS account

POST 
/accounts/onboard

Onboards a single AWS account: Prism assumes its role into the account, creates or updates the SAML identity provider inside it, and writes the result to its own record of the account.

This is the operation that makes Prism able to reach into an AWS account. A database record of an account on its own creates no trust; this is what creates it. Prism does not have to hold a record for the account first; onboarding creates one if it is missing and updates it if it is not.

It is synchronous and it changes things in your AWS account. The request blocks until the AWS work has finished, and by the time it returns:

• A SAML identity provider exists in the target account, created or updated with Prism's current metadata. If this step fails, the whole onboarding fails.
• An IAM OIDC identity provider may also exist. A failure here is swallowed: it is logged server-side and the onboarding is still reported as a success, SAML-only. A 200 does not promise the OIDC provider was created; read data.account.oidc_status to see whether it was.
• Prism's record of the account has been created or updated, with status: "active" and idp_status: "created".

Nothing is queued and nothing continues after the response; there is no job to poll. What the response says happened is what happened.

Re-onboarding an already-onboarded account is safe and is the intended repair path, but it is not inert: it overwrites the stored name with whatever accountName resolves to, refreshes the identity provider, and clears any recorded error.

An AWS-side failure is a 502, not a 400 or a 500: the account number was already validated, so the blame is upstream of Prism. Note that POST /accounts/validate reports the same class of failure as a 400 instead. The two operations genuinely disagree about which status an unreachable AWS account deserves, so handle each on its own terms rather than assuming one convention across the group.

Returns 200, not 201, and sends no Location header.

Request

Responses

200

The account onboarded, or would have on a dry run. A response reaches here only when the account genuinely succeeded: unlike the bulk operation, there is no partial success to hide in the payload.

The OIDC caveat above is the one thing a 200 does not cover.

400

The request was rejected before anything was attempted. Nothing in AWS and nothing in Prism changed.

The causes are a body that is not valid JSON; an accountId that is absent, not all digits, or not exactly twelve digits; and an accountName containing a character outside ^[a-zA-Z0-9\-_.\s]+$. message says which, and error repeats it prefixed with the field name.

Note the shape: these are ordinary error envelopes with an error string, not the errors array of a validation failure.

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. An AWS account Prism cannot reach is not a 404; see the 502.

500

The onboarding run itself could not be carried out, or it reported no result at all. Distinct from the 502: this means Prism failed, not that the AWS account refused.

502

The normal failure. The account was reachable as a request but the AWS work did not succeed, most often because Prism could not assume its role in the target account, or was not allowed to create the SAML identity provider there.

message carries the verbatim underlying reason, which is the only place the real cause survives. Read it before anything else.

Partial damage is possible: the identity provider may have been created before a later step failed. Re-running the onboarding is the repair, and is safe.