Skip to main content

​
Credentials

API keys are organization-scoped machine credentials. Store them in an approved secret source, redact them from logs, and never place them in a URL, a source file, or a command-line argument, where shell history and process listings expose them. Credential kinds, scopes, and authorization errors are covered in Authentication. The operational point here is that only the service can tell you whether a credential still works, and it does so with a structured error rather than a status code alone.

​
Organization boundaries

Organization access and Run visibility are evaluated for every request. A Run ID is a locator, not authorization, so possession of an ID grants nothing. This is why a permission error is never fixed by creating a second Run. Fix the membership, credential, or scope instead, and recover the existing assessment through its saved ID.

​
Local versus remote control

AbortSignal, request deadlines, and waitTimeoutMs stop local work only. They never change a Run that Antigen has already accepted. run.cancel() and POST /v1/runs/{runId}/cancel are the remote terminal operations. Read the current state before retrying any ambiguous mutation. Turning a local timeout into a lifecycle action converts an unknown into a real change to the assessment record.

​
Continuity

Keep the Run ID and the last handled event position outside the requesting process. A network failure changes what the client knows, not the Run’s state. After a gap, read the Run, then resume events strictly after the saved sequence. Persist a sequence only once its evidence has been handled: saving first can skip unprocessed work, and never saving makes the same evidence look new after every interruption.

​
Failure handling

Handle structured service errors rather than status codes alone, and preserve requestId for support. Validate a successful response before updating local state. failed and cancelled are both terminal but mean different things: one is an execution outcome, the other a decision someone made. Record which one occurred with the assessment.