Authentication

All public Phonefarm endpoints currently use one shared bearer secret.

Request Authentication

Send:

Authorization: Bearer <shared secret>

In the current implementation, this shared secret is configured as INGEST_SECRET in the runtime environment, even for non-ingest APIs. For docs and integrations, treat it as one shared public API bearer secret. Workspace-scoped API keys are part of the target architecture, but they are not the public authentication model for the documented endpoints until those endpoints are added to these docs and openapi.json.

Authenticated Endpoints

POST /capability-requests/enqueue
POST /maintenance/requests
GET /processes/{process_id}
POST /processes/{process_id}/cancel
POST /ingest
POST /cancel
POST /runtime-snapshots/upsert

Example

curl "$PHONEFARM_BASE_URL/processes/$PROCESS_ID" \
  -H "Authorization: Bearer $PHONEFARM_API_KEY"

Callback Signing

If PHONE_FARM_WEBHOOK_SECRET is configured, Phonefarm signs outbound callbacks with:

X-PhoneFarm-Timestamp
X-PhoneFarm-Signature

Signature input:

${timestamp}.${rawJsonBody}

Signature algorithm:

HMAC-SHA256

Example Verification

import crypto from "node:crypto";

function verifyPhonefarmSignature({ timestamp, rawBody, signature, secret }) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected, "utf8"),
    Buffer.from(signature, "utf8"),
  );
}

Failure Behavior

Missing auth header returns 401.
Invalid bearer token returns 401.
Missing server-side secret configuration returns 500.

Getting Started

Concepts

API

OpenAPI Reference

Guides

Reference

Authentication

Authentication

Request Authentication

Authenticated Endpoints

Example

Callback Signing

Example Verification

Failure Behavior

Read Next

​Authentication

​Request Authentication

​Authenticated Endpoints

​Example

​Callback Signing

​Example Verification

​Failure Behavior

​Read Next

Authentication

Request Authentication

Authenticated Endpoints

Example

Callback Signing

Example Verification

Failure Behavior

Read Next