---
title: Authentication
description: How to authenticate against the AgentPing API.
section: api
order: 1
---

# 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. |

:::warning
Use a ping token (`ping_...`) for anything that places the credential in a URL: cron lines, shell scripts, browser-pasted links, webhook configs. Reserve the full API key (`apk_...`) for SDKs that send it in a header. Query strings leak through access logs, browser history, referer headers, and `.bash_history`; a leaked ping token compromises one agent's heartbeat, a leaked API key compromises the whole team.
:::

## 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
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
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.