SDK Authentication

How verify-access calls are authenticated and how caller metadata is forwarded.

/api/agents/verify-access is authenticated — every call must identify the caller so attribution, rate limits, and the Discovered flow work correctly. Authenticate with an API key:

API key

Authorization: Bearer kya_<api-key>

SDK config: new ExpressMiddleware({ apiKey: process.env.ASTRASYNC_KEY, ... }). The Express and Next.js adapters auto-wire this.

What authenticates — and what doesn't

• An API key (kya_…), or a full dashboard session's access token.
• An agent id is never a credential. X-Astra-Id / X-Astra-Agent-Id: ASTRA-… identifies an agent; agent ids are public. A request that offers only an agent id is refused with 401 agent_identity_not_a_credential.
• Partial or special-purpose tokens are refused (401): the interim token from the first sign-in step (before the second factor), refresh tokens, and passkey elevation tokens. Only the access token of a completed sign-in authenticates.

Rate limits

Every request to the AstraSync API counts against a budget over a rolling 15-minute window:

Need more for one key? Contact support — AstraSync can give an individual key its own budget.

Over the budget, the API answers 429 with the standard rate-limit headers (RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset) and Retry-After. Wait for Retry-After seconds before retrying; read RateLimit-Remaining to pace yourself before you hit the limit.

Caller metadata forwarding

When the SDK runs inside a counterparty server, the backend otherwise sees the counterparty server's own IP/UA — useless for endpoint-owner forensics. The Express and Next.js adapters auto-forward the agent-side fingerprint:

{
  "callerMetadata": {
    "sourceIp": "203.0.113.42",           // First X-Forwarded-For hop or req.ip
    "userAgent": "Mozilla/5.0 (…)",
    "referer": "https://example.com/…",
    "host": "api.yourservice.com",
    "forwardedFor": "203.0.113.42, 10.0.0.1",
    "agentCardUrl": "https://agent.example.com/.well-known/agent-card.json"
  }
}

Probe access — AstraSync-Probe/1.0

AstraSync reserves the User-Agent string AstraSync-Probe/1.0 for future endpoint health-checks and webhook-delivery validation. The probe is opt-in — nothing fires today — but if you operate a WAF, security gateway, or restrictive robots.txt, allow this UA on the paths you registered with AstraSync. Match-by-prefix (AstraSync-Probe/) so future versions don't need a config change.

# robots.txt
User-agent: AstraSync-Probe/1.0
Allow: /
Crawl-delay: 5

See https://astrasync.ai/robots.txt for the canonical declaration on our own surface.