API Authentication

Proofarc supports 5 authentication types for API testing. Auth is configured once per scenario and applied automatically to every step.

The most common type. Proofarc calls your login endpoint, extracts the token, and applies it to all subsequent requests.

"authConfig": {
  "authType": "BEARER",
  "tokenSource": "LOGIN_ENDPOINT",
  "loginEndpoint": "/auth/login",
  "tokenJsonPath": "$.accessToken",
  "credentials": {
    "username": "your-user",
    "password": "your-password"
  }
}

Field	Description
`loginEndpoint`	Path appended to baseUrl to get the token
`tokenJsonPath`	JSONPath to extract token from login response
`credentials`	Username/password sent in the login body

OAuth2 Client Credentials

For APIs using OAuth2. Proofarc calls the token endpoint with client credentials.

"authConfig": {
  "authType": "OAUTH2_CLIENT",
  "tokenUrl": "https://auth.example.com/oauth/token",
  "clientId": "your-client-id",
  "clientSecret": "your-secret",
  "scope": "read:users write:users"
}

Static Bearer Token

For CI/CD pipelines or service accounts with pre-generated tokens.

"authConfig": {
  "authType": "BEARER",
  "tokenSource": "STATIC",
  "bearerToken": "your-pre-generated-token"
}

Basic Auth

HTTP Basic Authentication — username and password encoded in the header.

"authConfig": {
  "authType": "BASIC",
  "username": "your-user",
  "password": "your-password"
}

API Key

API key sent in a header or query parameter.

"authConfig": {
  "authType": "API_KEY",
  "apiKeyLocation": "HEADER",
  "apiKeyName": "X-API-Key",
  "apiKeyValue": "your-api-key"
}

apiKeyLocation can be HEADER or QUERY.

Auth Per Environment

When running the same scenario against different environments, auth can be configured per environment target. The scenario uses the environment's auth configuration automatically.

Authenticated Apps: Wiring a Usable Auth Source

When a scenario's application is marked authRequirement=AUTHENTICATED, the platform refuses to execute unless a usable auth source is configured — otherwise the run would 403 on the first protected step. The refusal is an explicit HTTP 400 at execute time with an actionable message (not a silent failure).

A credential alone is not always enough — it must be applicable:

Credential kind	Usable on its own?	What else is needed
Static bearer `token`	✅ Yes	nothing — applied as `Authorization: Bearer …`
API key (`apiKeyName` + `apiKeyValue`)	✅ Yes	nothing — applied as the configured header
`username` / `password`	❌ No	a login endpoint to exchange them for a token
OAuth2 `clientId` / `clientSecret`	❌ No	a token endpoint

So there are three ways to satisfy the gate:

Environment credential + credential_tag. A static-token or API-key credential works immediately. For username/password, also configure the environment login endpoint:

add_environment_credential(environment=<env>, tag="admin", username="admin", password="…")
set_environment_auth_endpoint(environment=<env>, login_endpoint="/auth/login", token_json_path="$.accessToken")
execute_scenario(scenario=<id>, credential_tag="admin")   → COMPLETED

Per-target auth via set_target_auth — the target carries its own login config (no env reconfiguration):

set_target_auth(target=<id>, auth_config={
  "authType": "LOGIN_ENDPOINT", "credentialTag": "admin",
  "loginUrl": "/auth/login", "tokenJsonPath": "$.accessToken"
})

Public-only run. If this execution only hits public endpoints (e.g. a health check), bypass the gate explicitly:
```
execute_scenario(scenario=<id>, allow_unauthenticated=true)
```

If you pass a username/password credential with no login flow anywhere, you get a clear 400:

credential 'admin' resolves to an active credential but it is username/password only and there is NO login flow — use set_environment_auth_endpoint, or a credential that carries a static token or API key.

Shared With Security Scanners

Auth configured on an environment target is shared across the entire platform:

API scenarios — auth header applied to every step
Performance tests — each virtual user authenticates independently
Security scans — ZAP, Nikto, Nuclei, SQLMap all use the same auth

Configure auth once on your target, and every test type uses it automatically. See Authenticated Scanning for details.

Testing Auth

After configuring auth, the first step of your scenario will include the auth header automatically. You don't need to add Authorization headers manually to each step.

Bearer Token (Login Endpoint)​

OAuth2 Client Credentials​

Static Bearer Token​

Basic Auth​

API Key​

Auth Per Environment​

Authenticated Apps: Wiring a Usable Auth Source​

Shared With Security Scanners​

Testing Auth​

Bearer Token (Login Endpoint)