Authentication

Every Antigen request is authorized against an organization. There are two credential kinds, and which one you want depends on whether a person or an application is acting.

Credential	Use it for	Sent as
Organization API key	Applications, services, and automation	`x-api-key`
User access token	An interactive member at a terminal	`authorization: Bearer <token>`

API keys begin with atg_sk_ and belong to the organization rather than to the person who created them. Your organization administrator issues and revokes them. An interactive member does not need a key at all: antigen login stores a user access token for the CLI.

Configure a credential

Read the key from your secret source at startup. Keep it out of URLs, source files, command arguments, and logs, where shell history and process listings expose it. From TypeScript:

import Antigen from "@antigenco/sdk";

const apiKey = process.env.ANTIGEN_API_KEY;
if (!apiKey) throw new Error("Set ANTIGEN_API_KEY to an organization API key.");

const antigen = new Antigen(apiKey);

From the CLI, sign in once as a member. The organization ID is a UUID:

antigen login --organization-id 00000000-0000-0000-0000-000000000000

Over HTTP, send the key in x-api-key on every request:

curl --fail-with-body --silent --show-error \
  -H "x-api-key: $ANTIGEN_API_KEY" \
  https://api.antigen.sh/v1/targets | jq .

The SDK also accepts a user access token through its object form. Pass exactly one of apiKey and accessToken; see new Antigen for the full option set.

Confirm it works

The atg_sk_ prefix identifies the credential kind, not its validity, expiry, or scope, so a shape check cannot tell you whether a key still works. Read your approved targets instead. It is the cheapest authenticated call and it returns something you need anyway. Use antigen targets, GET /v1/targets, or getApprovedTargets(). An empty list means the credential authenticated but your organization has no approved target yet, which is a question for your administrator rather than an integration bug.

Scopes

A credential carries scopes, and each endpoint requires one:

Scope	Grants
`targets:read`	Reading the approved target list.
`runs:read`	Listing Runs, reading one Run, and streaming its events.
`runs:write`	Creating Runs, sending guidance, and every lifecycle action.
`findings:read`	Reading a Run’s findings.

Scopes are checked per request, so a credential that can create a Run cannot necessarily read its findings. Grant the narrowest set each integration needs.

Resolve an authorization error

Code	Meaning	Do this
`UNAUTHENTICATED`	The credential is missing, malformed, or expired.	Check the header name, then re-read the key or run `antigen login`.
`FORBIDDEN`	The credential is valid but lacks permission or scope.	Fix the membership or scope. Do not create a second Run.
`TARGET_NOT_APPROVED`	A submitted target is not approved for the organization.	Re-read the approved list rather than editing the rejected target.

None of these are fixed by retrying or by starting a new assessment. A Run ID is a locator, not a credential, so possession of an ID grants nothing and a permission problem follows you to the next Run. Fix the credential and recover the existing assessment through its saved ID. Keep the requestId from any error response with the saved Run ID. It lets support identify the failing request without exposing the credential. Related: Get started, Reliability and security, and the TypeScript SDK, CLI, and HTTP API references.

Start

Build an assessment

Developer tools

Operate safely

Configure a credential

Confirm it works

Scopes

Resolve an authorization error

​Configure a credential

​Confirm it works

​Scopes

​Resolve an authorization error

Configure a credential

Confirm it works

Scopes

Resolve an authorization error