Authentication

AgentQ's API supports two authentication methods:

Method	Header	Best for
Company API key (recommended)	X-API-Key: <your_api_key>	CI/CD pipelines, test automation, integrations
JWT bearer token	Authorization: Bearer <token>	Interactive sessions, the AgentQ web app

Getting Your API Key

1. Sign in to AgentQ
2. Open your account profile
3. Copy your company API key

The key is scoped to your company: it can read and write test data (projects, test runs, test results) belonging to your company only.

Using the API Key

Include the key in the X-API-Key header:

curl -X PATCH "https://backend-app.agentq.id/projects/YOUR_PROJECT_ID/test-runs/YOUR_TESTRUN_ID/test-results/tcId/YOUR_TC_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "passed", "actualResult": "Updated via API"}'

With the agentq-playwright library, set AGENTQ_API_KEY as an environment variable instead — see the Playwright guide.

Attributing results to a person

API-key requests are machine authentication, so results are not tied to a user by default. Add the X-Actor-Email header (or the AGENTQ_EMAIL environment variable when using agentq-playwright) with the email of a member of your company — owner or invited member — and pushed results will show that person as Created By:

curl -X PATCH "https://backend-app.agentq.id/projects/.../test-results/tcId/1" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Actor-Email: member@yourcompany.com" \
  -H "Content-Type: application/json" \
  -d '{"status": "passed"}'

If the email is not a member of the API key's company, the header is ignored and the request still succeeds.

JWT Bearer Token

Obtain a token by logging in, then send it as a bearer token:

TOKEN=$(curl -s -X POST "https://backend-app.agentq.id/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "..."}' | jq -r .access_token)

curl "https://backend-app.agentq.id/projects/YOUR_PROJECT_ID/test-runs" \
  -H "Authorization: Bearer $TOKEN"

Tokens expire; API keys are the better fit for automation.

API Key Best Practices

✅ Do's

• Store the key in environment variables or your CI provider's secret store (e.g. GitHub Actions secrets)
• Treat it like a password — it grants write access to all of your company's test data

❌ Don'ts

• Never hardcode the key in source code or commit it to version control
• Never share the key in logs, error messages, chat, or terminal commands that get saved to history
• Never embed it in client-side/browser code

If your key is ever exposed, contact support@agentq.id to rotate it.

Troubleshooting

401 Unauthorized

• Check the key is sent in the X-API-Key header (not Authorization)
• Check for extra spaces or truncation — keys are long hex strings
• If using an environment variable, verify it is actually set in the environment running the request

404 Not Found

• The project, test run, or test case doesn't exist — or belongs to a different company than the API key

"Created By" shows unknown

• Add X-Actor-Email / AGENTQ_EMAIL with the email of a member of the API key's company

Support

Need help with authentication?

• Email: support@agentq.id
• Docs: https://docs.agentq.id