Authentication

AgentPing recognises two credential types. They differ in scope and where you put them.

Credential types

Credential	Format	Scope	Where to use
Team API key	`apk_<region>_<32 hex>`	Full access to every endpoint and every agent on the team	SDKs and any caller that sends the credential in a header
Ping token	`ping_<region>_<32 hex>`	Single agent; can only fire heartbeats	Cron jobs, shell scripts, n8n, GitHub Actions, anything that puts credentials in a URL

Region is eu or us, set when you create the account. Example credentials:

apk_eu_018f3a2b9c1d7e8fa4b9c2d7e8f1a3b6
ping_eu_018f3a2b9c1d7e8fa4b9c2d7e8f1a3b6

Sending the credential

Three transports are accepted.

Method	Example	Notes
`Authorization` header	`Authorization: Bearer apk_eu_018f3a2b9c1d7e8fa4b9c2d7e8f1a3b6`	Preferred for SDKs and any API key.
`X-AgentPing-Key` header	`X-AgentPing-Key: ping_eu_018f3a2b9c1d7e8fa4b9c2d7e8f1a3b6`	Alias of the above. Use when a proxy strips `Authorization`.
`?key=` query parameter	`https://eu.ingest.agentping.io/v1/ping?key=ping_eu_...&agent=daily-summary`	Allowed only on `GET /v1/ping`. Never put `apk_` keys here.

Errors you might see

Region mismatch. Credentials are region-scoped. An apk_us_... key sent to an EU endpoint (or vice versa) is rejected:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "region_mismatch",
  "message": "Credential region 'us' does not match endpoint region 'eu'. Send this request to https://eu.ingest.agentping.io/v1/... from the us region, or use an eu credential."
}

Ping token scope violation. A ping token issued for one agent cannot fire heartbeats for another:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "scope_violation",
  "message": "This ping token is scoped to agent 'daily-summary'. You attempted to fire a heartbeat for 'competitor-scan'."
}

Bad credential format. Anything that doesn't match apk_<region>_<32 hex> or ping_<region>_<32 hex> returns 400 Bad Request.

Revoked or unknown credential. Returns 401 Unauthorized. Rotations and revocations take effect within about a minute. For emergency revocation, contact support.

Ping token lifecycle

Issued from the agent's settings page in the dashboard. The full token is shown once at creation; afterwards only the prefix and last 4 characters are displayed.
Rotated with one click. The old token continues working for 24 hours after rotation so cron schedules roll over without coordination.
Revoked instantly when the agent is deleted.