# API access administration
Source: https://hfsaa.mintlify.app/admin-operations
Review applications and control HFSAA Developer API keys.
The MVP uses a Cloudflare Worker secret named `ADMIN_API_TOKEN` for HFSAA-only administration. Keep this token in a password manager. HFSAA administrators can open `/admin`, enter the token once, and use the browser review console. The Worker replaces it with an eight-hour signed, secure browser session; the raw token is not stored in the session cookie.
When an applicant verifies their email, Resend notifies `idris.ocasio@hfsaa.org`, `ahmed.qureshi@hfsaa.org`, and `imran.qasim@hfsaa.org` that a request is ready for review. The message links to the admin portal; applicant details remain behind administrator authentication.
The JSON endpoints below remain available for trusted server-side operations.
## Review pending applications
```bash theme={null}
curl "https://hfsaa-public-api.idris-ocasio.workers.dev/v1/admin/api-applications?status=pending_review" \
-H "Authorization: Bearer $HFSAA_ADMIN_TOKEN"
```
## Approve an application
Test applications default to 10 requests per minute and 1,000 requests per month. The per-minute limit is fixed by the deployed environment for this MVP. Omit `monthly_limit` to use the default, or assign an explicit monthly limit during review.
```bash theme={null}
curl -X POST "https://hfsaa-public-api.idris-ocasio.workers.dev/v1/admin/api-applications/APPLICATION_ID/approve" \
-H "Authorization: Bearer $HFSAA_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"monthly_limit":1000}'
```
Approval emails a short-lived, one-time claim link. The API key itself does not expire automatically.
## Inspect keys and usage
List active test keys with their current monthly request totals:
```bash theme={null}
curl "https://hfsaa-public-api.idris-ocasio.workers.dev/v1/admin/api-keys?status=active&environment=test" \
-H "Authorization: Bearer $HFSAA_ADMIN_TOKEN"
```
Use the returned key ID to inspect up to 90 days of per-endpoint daily usage plus the last 12 monthly totals:
```bash theme={null}
curl "https://hfsaa-public-api.idris-ocasio.workers.dev/v1/admin/api-keys/KEY_ID/usage?days=30" \
-H "Authorization: Bearer $HFSAA_ADMIN_TOKEN"
```
## Deny an application
```bash theme={null}
curl -X POST "https://hfsaa-public-api.idris-ocasio.workers.dev/v1/admin/api-applications/APPLICATION_ID/deny" \
-H "Authorization: Bearer $HFSAA_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"reason":"Please provide a more specific integration use case."}'
```
## Revoke a key
```bash theme={null}
curl -X POST "https://hfsaa-public-api.idris-ocasio.workers.dev/v1/admin/api-keys/KEY_ID/revoke" \
-H "Authorization: Bearer $HFSAA_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"reason":"The key was exposed and must be replaced."}'
```
Revocation takes effect on the next API request and sends the owner a notification email. The database stores only the key's SHA-256 hash and display-safe hint.
## Developer self-service
Developers open `/developer/manage` and request a 15-minute sign-in link by email. The resulting secure session lasts eight hours and lets them:
* inspect key status, prefixes, monthly usage, and reset date;
* rotate a key, which immediately revokes the old key and emails a one-time replacement claim link;
* revoke a key permanently; and
* open the production-access application.
The portal never displays an existing raw key because HFSAA does not store it.
# AI integration guide
Source: https://hfsaa.mintlify.app/ai-integration-guide
A precise implementation guide for people and AI coding agents using the HFSAA Public API.
This guide is a compact implementation recipe for applications that display HFSAA-certified locations. It applies equally to human developers and AI coding agents.
## Non-negotiable rules
1. Use the production base URL: `https://hfsaa-public-api.idris-ocasio.workers.dev` and send a production API key as a Bearer token.
2. Keep the API key in a server-side secret; never expose it in browser or mobile application code.
3. Cache API data for no more than one hour, then revalidate or fetch fresh data.
4. Treat the documented API response as the complete HFSAA data contract. Do not infer, scrape, or expose additional fields.
5. When your product states or implies HFSAA certification, identify HFSAA and give users reasonable access to that location's `verification_url`.
6. Do not construct or alter `verification_url` values. Use the exact URL returned by the API.
## Fetch locations
Use one endpoint for restaurants, meat markets, and dining halls. Select a category with the `type` query parameter when needed.
```ts theme={null}
const API_BASE_URL = "https://hfsaa-public-api.idris-ocasio.workers.dev";
const HFSAA_API_KEY = process.env.HFSAA_API_KEY;
type LocationType = "restaurant" | "meat_market" | "dining_hall";
async function listLocations(options: {
type?: LocationType;
state?: string;
city?: string;
limit?: number;
cursor?: string;
} = {}) {
const params = new URLSearchParams();
if (options.type) params.set("type", options.type);
if (options.state) params.set("state", options.state);
if (options.city) params.set("city", options.city);
if (options.limit) params.set("limit", String(options.limit));
if (options.cursor) params.set("cursor", options.cursor);
const response = await fetch(
`${API_BASE_URL}/v1/locations?${params.toString()}`,
{
headers: {
Accept: "application/json",
Authorization: `Bearer ${HFSAA_API_KEY}`
}
}
);
const body = await response.json();
if (!response.ok) {
throw new Error(body.error?.message ?? "HFSAA API request failed");
}
return body;
}
```
For example:
```bash theme={null}
curl "https://hfsaa-public-api.idris-ocasio.workers.dev/v1/locations?type=dining_hall&limit=1" \
-H "Authorization: Bearer $HFSAA_API_KEY"
```
A successful response has this shape:
```json theme={null}
{
"dataset_version": "2ec27a5c-79c4-4fd3-9fd5-95eb2f1fc354",
"data": [
{
"id": "50796ba5-9523-4c7f-a74a-465b4d03f0e1",
"type": "dining_hall",
"name": "NYU Jasper H. Kane Dining Hall",
"verification_url": "https://hfsaa-public-locator.pages.dev/?certificate_id=HFSAA-R-9C3E205780",
"certification_status": "certified",
"chapter_name": "New York",
"address": "6 MetroTech Center",
"city": "Brooklyn",
"state": "NY",
"zip_code": "11201",
"cuisine_type": null,
"google_place_id": "ChIJ85aDTUpawokRxyqHxTnodLI"
}
],
"pagination": {
"limit": 1,
"next_cursor": "eyJpZCI6IjUwNzk2YmE1LTk1MjMtNGM3Zi1hNzRhLTQ2NWI0ZDAzZjBlMSJ9"
}
}
```
## Render verification and attribution
When you state or imply that a location is certified or halal verified by HFSAA, identify HFSAA and provide reasonable access to the exact returned `verification_url`. There is no required wording or placement.
```tsx theme={null}
function HfsaaLocationCard({ location }: { location: Location }) {
return (
);
}
```
The link may instead be associated with an HFSAA name, badge, **Learn more** link, or another clearly related details element. In a digital product it must be clickable. Offline material may print the URL or use a QR code. Do not substitute a generic HFSAA link for the location-specific `verification_url`, and do not suggest that HFSAA endorses your application.
## Handle nullable directory fields
`chapter_name`, `address`, `city`, `state`, `zip_code`, `cuisine_type`, and `google_place_id` may each be `null`. Do not assume that address or chapter information is present. Omit or adapt UI elements that depend on unavailable values.
## Paginate correctly
Responses include `pagination.next_cursor`.
* If it is a string, pass that exact value as `cursor` in the next request.
* If it is `null`, there are no further results.
* Keep the same filters while moving through pages.
* Treat cursors as opaque values. Do not decode, modify, or generate them.
* Every page repeats the same immutable `dataset_version`, even if a newer snapshot is published while you paginate.
* Superseded versions remain available for at least seven days. If a cursor returns HTTP `410`, restart without that cursor.
* `limit` must be an integer from 1 to 100.
```ts theme={null}
const firstPage = await listLocations({ type: "restaurant", limit: 25 });
const secondPage = firstPage.pagination.next_cursor
? await listLocations({
type: "restaurant",
limit: 25,
cursor: firstPage.pagination.next_cursor
})
: null;
```
## Handle validation errors
Correct invalid requests rather than retrying them unchanged. For example, `limit=0` returns HTTP `400`:
```json theme={null}
{
"error": {
"code": "invalid_parameter",
"message": "limit must be an integer between 1 and 100."
}
}
```
An unknown location ID returns HTTP `404`. Rate and monthly limits are assigned per API key; HTTP `429` includes `Retry-After`. Retry `429`, `500`, `502`, `503`, and `504` with bounded exponential backoff and jitter, honoring `Retry-After` when present. Do not retry invalid `400` requests unchanged.
## Download a reproducible snapshot
Fetch `GET /v1/dataset` before downloading a complete dataset. Its response includes:
* an opaque `dataset_version`
* the UTC `generated_at` time
* the exact `location_count`
* a SHA-256 checksum
* a version-specific `download_url`
The checksum covers the exact bytes returned by `download_url`. Use that version-specific URL when storing or redistributing a snapshot.
The one-hour caching limit still applies to version-specific downloads. Revalidate or fetch a fresh copy after one hour even when the same immutable version remains available from the API.
## Google Place IDs
`google_place_id` is optional and is only an identifier. The HFSAA API does not return Google photos, hours, maps, ratings, or other Google content.
If you enrich a listing through Google Places, use your own Google Maps Platform project, credentials, billing, attribution, and policy compliance. HFSAA attribution remains required for the HFSAA data displayed alongside that enrichment.
## Implementation checklist
* [ ] Fetch only from `https://hfsaa-public-api.idris-ocasio.workers.dev`.
* [ ] Send the production API key as a Bearer token from server-side code only.
* [ ] Revalidate or refresh all cached API data within one hour.
* [ ] Filter location listings with `type`, `state`, `city`, `zip_code`, `chapter`, or `q` as needed.
* [ ] Follow `next_cursor` for additional pages.
* [ ] Confirm every page in a pagination sequence has the same `dataset_version`.
* [ ] Restart pagination if an expired cursor returns HTTP `410`.
* [ ] Honor `Retry-After` and use bounded backoff with jitter for retryable responses.
* [ ] Verify complete downloads against the SHA-256 checksum from `GET /v1/dataset`.
* [ ] When claiming HFSAA certification, identify HFSAA and make the exact `verification_url` reasonably accessible.
* [ ] Handle nullable chapter, address, cuisine, and Google Place ID fields.
* [ ] Keep Google Places enrichment separate and use your own provider credentials.
* [ ] Refer to the [API Reference](/api-reference) for the authoritative endpoint and field definitions.
# Approve an application and email a one-time claim link
Source: https://hfsaa.mintlify.app/api-reference/administration/approve-an-application-and-email-a-one-time-claim-link
/openapi.yaml post /v1/admin/api-applications/{applicationId}/approve
# Deny an application and email the reason
Source: https://hfsaa.mintlify.app/api-reference/administration/deny-an-application-and-email-the-reason
/openapi.yaml post /v1/admin/api-applications/{applicationId}/deny
# Inspect usage for an API key
Source: https://hfsaa.mintlify.app/api-reference/administration/inspect-usage-for-an-api-key
/openapi.yaml get /v1/admin/api-keys/{keyId}/usage
# List API access applications
Source: https://hfsaa.mintlify.app/api-reference/administration/list-api-access-applications
/openapi.yaml get /v1/admin/api-applications
# List API keys and current-month usage
Source: https://hfsaa.mintlify.app/api-reference/administration/list-api-keys-and-current-month-usage
/openapi.yaml get /v1/admin/api-keys
# Revoke an API key and notify its owner
Source: https://hfsaa.mintlify.app/api-reference/administration/revoke-an-api-key-and-notify-its-owner
/openapi.yaml post /v1/admin/api-keys/{keyId}/revoke
# List chapters
Source: https://hfsaa.mintlify.app/api-reference/chapters/list-chapters
/openapi.yaml get /v1/chapters
Returns HFSAA chapters represented by public directory locations.
# Claim an approved API key once
Source: https://hfsaa.mintlify.app/api-reference/developer-access/claim-an-approved-api-key-once
/openapi.yaml post /v1/developer/keys/claim
Generates the API key at confirmation time. The raw key is returned once and is never stored by HFSAA.
# Confirm an application email address
Source: https://hfsaa.mintlify.app/api-reference/developer-access/confirm-an-application-email-address
/openapi.yaml post /v1/developer/verify
Consumes the one-time token only after the person submits the confirmation form, preventing email scanners from using it.
# Open accountless API-key management
Source: https://hfsaa.mintlify.app/api-reference/developer-access/open-accountless-api-key-management
/openapi.yaml get /developer/manage
Requests a one-time sign-in link by email; no developer account or password is required.
# Open the API access application form
Source: https://hfsaa.mintlify.app/api-reference/developer-access/open-the-api-access-application-form
/openapi.yaml get /developer/apply
# Open the API-key claim confirmation page
Source: https://hfsaa.mintlify.app/api-reference/developer-access/open-the-api-key-claim-confirmation-page
/openapi.yaml get /v1/developer/keys/claim
Does not generate or consume the key until the confirmation form is submitted.
# Open the email-verification confirmation page
Source: https://hfsaa.mintlify.app/api-reference/developer-access/open-the-email-verification-confirmation-page
/openapi.yaml get /v1/developer/verify
# Request a one-time management link
Source: https://hfsaa.mintlify.app/api-reference/developer-access/request-a-one-time-management-link
/openapi.yaml post /v1/developer/manage/request
Always returns a generic response so callers cannot discover which email addresses are eligible.
# Submit an API access application
Source: https://hfsaa.mintlify.app/api-reference/developer-access/submit-an-api-access-application
/openapi.yaml post /v1/developer/applications
Sends an email-verification link before the request enters manual HFSAA review.
# Get a location
Source: https://hfsaa.mintlify.app/api-reference/locations/get-a-location
/openapi.yaml get /v1/locations/{locationId}
Returns a single HFSAA-certified directory location by its opaque HFSAA ID.
# List locations
Source: https://hfsaa.mintlify.app/api-reference/locations/list-locations
/openapi.yaml get /v1/locations
Returns HFSAA-certified directory locations across all supported types.
# Download a dataset snapshot
Source: https://hfsaa.mintlify.app/api-reference/metadata/download-a-dataset-snapshot
/openapi.yaml get /v1/dataset/locations.json
Downloads the exact immutable JSON artifact identified by a dataset version. Use the version-specific URL returned by GET /v1/dataset to ensure the checksum and artifact refer to the same snapshot.
# Get dataset metadata
Source: https://hfsaa.mintlify.app/api-reference/metadata/get-dataset-metadata
/openapi.yaml get /v1/dataset
Returns metadata about the directory dataset and API contract.
# Check API availability
Source: https://hfsaa.mintlify.app/api-reference/operations/check-api-availability
/openapi.yaml get /health
Public liveness check. It returns service status only and never exposes directory data.
# Data policy
Source: https://hfsaa.mintlify.app/data-policy
Permitted uses, verification requirements, and freshness rules for HFSAA public API data.
## Permitted use
HFSAA permits you to download, cache, reproduce, and display data returned by the public API while that data remains within the one-hour freshness window described below. This includes complete-dataset snapshots and modified or derived datasets used commercially or noncommercially.
When using or redistributing the data:
* Identify HFSAA as the source.
* Preserve `dataset_version` and `generated_at` metadata when the API supplies them.
* Clearly disclose material modifications to the data.
* Do not imply that HFSAA endorses your application, content, organization, or business.
This permission does not grant rights to HFSAA trademarks, service marks, or logos. Separate permission may be required to use an HFSAA logo or official badge.
## Verification and attribution
Whenever your product states or implies that a location is certified or halal verified by HFSAA, identify HFSAA and give users reasonable access to that location's exact `verification_url`.
There is no required wording or placement. The verification link may be associated with the certification statement, the HFSAA name, a badge, a **Learn more** link, or another clearly related details element. In a digital product it must be clickable. In offline material, print the URL or provide a scannable QR code.
Do not construct, shorten, or alter a `verification_url`. Use the exact location-specific URL returned by the API rather than a generic HFSAA link.
## One-hour caching limit
API data may be cached for no more than one hour from the time it is fetched. After one hour, revalidate or fetch a fresh copy before continuing to store, serve, redistribute, or present the data as current HFSAA certification information.
The API may keep immutable versions available for longer to support pagination and checksum verification. That server-side availability does not grant permission to cache or retain a local copy beyond one hour. Longer-term archival or historical storage requires separate written permission from HFSAA.
The public endpoints return only locations whose current public certification status is `certified`. Pending, revoked, and not-certified locations are excluded. A location's status can change during the one-hour cache period, so users should be able to follow its `verification_url` for current verification.
## Public directory fields
The public API exposes a deliberately small set of HFSAA directory fields:
| Field | Description |
| - | - |
| `id` | Opaque HFSAA location identifier |
| `type` | `restaurant`, `meat_market`, or `dining_hall` |
| `name` | Business or facility name |
| `verification_url` | Official HFSAA verification page for that location |
| `certification_status` | Public certification status |
| `chapter_name` | Associated HFSAA chapter, or `null` when unavailable |
| `address`, `city`, `state`, `zip_code` | Directory address components; each may be `null` |
| `cuisine_type` | HFSAA directory classification, or `null` when unavailable |
| `google_place_id` | Google Place ID, or `null` when unavailable |
## Deliberately excluded fields
The API does not return certificate IDs, certificate dates, images, image URLs, Google Maps URLs, hours, phone numbers, websites, delivery links, map coordinates, personal contact details, internal IDs, or operational metadata.
This boundary keeps the API focused on HFSAA-approved directory records. Applications that want third-party enrichment can do so using their own provider relationship and permissions.
# Getting started
Source: https://hfsaa.mintlify.app/getting-started
Use the HFSAA Public API.
> **[Request an API key](https://hfsaa-public-api.idris-ocasio.workers.dev/developer/apply)**
>
> Start with a rate-limited test key for development—no developer account required.
> [!NOTE]
>
> The production endpoint is temporarily `https://hfsaa-public-api.idris-ocasio.workers.dev`. Use this address for production requests and developer management while the custom domain is restored.
> Application verification and management emails may be delayed while email delivery is restored.
## Base URLs
The v1 API is read-only and requires an API key. Use the URL that matches the environment shown when the key is claimed.
| Key | Base URL |
| - | - |
| Test (`hfsaa_test_…`) | `https://hfsaa-public-api-staging.idris-ocasio.workers.dev` |
| Production (`hfsaa_live_…`) | `https://hfsaa-public-api.idris-ocasio.workers.dev` |
## Get an API key
Open the [API access application](https://hfsaa-public-api.idris-ocasio.workers.dev/developer/apply), choose test or production access, and verify your email address. HFSAA manually approves or denies each request.
Test access does not require an account. A test key does not expire automatically, but it only works at the test base URL and is subject to its assigned rate and monthly request limits. Production access is reviewed separately and may require a paid capacity agreement.
Approved applicants receive a short-lived, one-time claim link. The raw API key is shown once, so store it in a server-side secret manager. Never include it in browser or mobile application code.
## Core resource
`Location` is the canonical resource. Every currently certified restaurant, meat market, and dining hall has an opaque HFSAA location ID and a `type`.
```json theme={null}
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": "restaurant",
"name": "Example Restaurant",
"verification_url": "https://hfsaa-public-locator.pages.dev/?certificate_id=HFSAA-R-EXAMPLE",
"certification_status": "certified",
"chapter_name": "Example Chapter",
"address": "123 Main Street",
"city": "Example City",
"state": "NY",
"zip_code": "10001",
"cuisine_type": "Mediterranean",
"google_place_id": "ChIJ..."
}
```
`chapter_name`, `address`, `city`, `state`, `zip_code`, `cuisine_type`, and `google_place_id` may each be `null`. Applications should omit or adapt any corresponding UI when a value is unavailable.
## Make a request
Every directory-data endpoint requires an API key. Send it in the `Authorization` header on every request; query-string keys and anonymous requests are not supported.
```bash theme={null}
curl "$HFSAA_API_BASE_URL/v1/locations?type=restaurant&limit=25" \
-H "Authorization: Bearer $HFSAA_API_KEY"
```
The production API accepts only production keys, and the test API accepts only test keys. A missing, malformed, unknown, or wrong-environment key returns HTTP `401`. A revoked key returns HTTP `403`. The public `/health` check and developer application, email-verification, key-claim, and accountless management pages do not require an API key; they do not expose directory data and use their own one-time-token or session protections where applicable.
## Filtering and pagination
`GET /v1/locations` supports filters for type, state, city, ZIP code, chapter, and free-text search. Lists use a `limit` and cursor-based `cursor` parameter.
Every list response includes a `dataset_version`. A cursor is bound to that immutable version, and subsequent pages repeat the same version even if HFSAA publishes a newer dataset while you paginate. Keep the same filters with every page request and treat cursors as opaque.
Superseded versions remain available for at least seven days. If a cursor's version has expired, the API returns HTTP `410`; restart pagination without the expired cursor.
## Dataset snapshots
`GET /v1/dataset` returns the current `dataset_version`, UTC `generated_at` time, exact `location_count`, a SHA-256 checksum, and a version-specific `download_url`.
The checksum covers the exact bytes returned by that URL. Use the version-specific URL rather than an unversioned download when reproducibility matters.
## Caching
API data may be cached for no more than one hour. Responses use `Cache-Control: private, max-age=3600, must-revalidate`, which permits a private application or browser cache while preventing shared caches from serving authenticated responses without running API-key checks and usage tracking.
After one hour, revalidate or fetch fresh data before displaying it as current HFSAA certification information. A versioned snapshot remaining available for cursor stability does not extend this one-hour caching allowance.
## Rate limits and retries
Test keys default to 10 requests per minute and 1,000 requests per month. HFSAA can assign different limits during production review. Responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` for the monthly allowance.
When a per-minute or monthly limit is exceeded, the API returns HTTP `429` with a `Retry-After` header and a structured JSON error body.
Retry `429`, `500`, `502`, `503`, and `504` responses with bounded exponential backoff and jitter. Honor `Retry-After` whenever it is present. Correct `400` requests rather than retrying them unchanged.
## Verification and attribution
When your product states or implies that a location is certified or halal verified by HFSAA, identify HFSAA and give users reasonable access to the exact `verification_url` returned for that location.
For example, this is one acceptable presentation:
```html theme={null}
Certified by HFSAA
```
The link can instead be associated with a badge, **Learn more** link, or another clearly related details element. No exact wording is required. In digital products the URL must be clickable; offline material may use a printed URL or QR code. See the [data policy](/data-policy) for caching, redistribution, freshness, and verification requirements.
Do not present HFSAA data in a way that implies HFSAA endorses your application.
## Google Place IDs
When supplied, a `google_place_id` is an identifier only. If your application uses Google Places to look up photos, hours, maps, or other Google content, you are responsible for your own Google Maps Platform credentials, billing, attribution, and policy compliance.
# Google Forms intake setup
Source: https://hfsaa.mintlify.app/google-forms-setup
Connect the public API application form to the HFSAA Worker.
Google Forms is an intake channel only. Supabase remains the system of record, and Resend continues to deliver verification, approval, denial, usage, revocation, and management emails.
## Form questions
Create a form that does not require a Google account and add these question titles exactly:
| Question | Type | Required |
| - | - | - |
| Name | Short answer | Yes |
| Email | Short answer with email validation | Yes |
| Organization | Short answer | No |
| Website | Short answer with URL validation | No |
| Access type | Multiple choice: `Test` or `Production` | Yes |
| Expected monthly requests | Short answer with number validation | No |
| How will you use the API? | Paragraph | Yes |
Test access should be described as non-expiring, limited development and early-stage access. Production access should be described as a paid capacity review.
## Connect the form
1. Open the form's Apps Script project.
2. Paste `integrations/google-forms/Code.gs` into the project.
3. In **Project Settings → Script Properties**, add:
* `HFSAA_INGEST_URL`: the target Worker's URL ending in `/v1/integrations/google-forms/applications`.
* `HFSAA_INGEST_TOKEN`: a dedicated random ingestion secret. Never use the administrator token.
4. Run `installFormSubmitTrigger` once and approve the requested Google permissions.
5. Link responses to a restricted Google Sheet for operational review. Limit Sheet and Script access to HFSAA administrators.
The trigger sends each response to the Worker. The Worker validates the dedicated secret, stores the request in Supabase, and asks Resend to verify the applicant's email. Retries use a deterministic verification token and Resend idempotency key, so a repeated trigger does not create multiple active applications or different verification links.
## Staging verification
Submit a test response using an HFSAA-controlled inbox. Confirm that:
1. The form response appears in the restricted Sheet.
2. The Worker returns HTTP `202` to Apps Script.
3. The verification email arrives through Resend.
4. Clicking the verification link moves the Supabase application to `pending_review`.
5. The application appears in the HFSAA admin dashboard.
Do not connect the production Worker until the staging flow passes end to end.
## Production intake
For the MVP, use one public form as the production intake after the staging flow has passed. Keep its existing authorized `onFormSubmit` trigger, create a new production ingestion token, and update the bound script properties to:
* `HFSAA_INGEST_URL`: `https://hfsaa-public-api.idris-ocasio.workers.dev/v1/integrations/google-forms/applications`
* `HFSAA_INGEST_TOKEN`: the production Worker's dedicated `GOOGLE_FORMS_INGEST_TOKEN` value
Publish the form without requiring a Google account and set the production Worker's `DEVELOPER_APPLICATION_FORM_URL` variable to its responder URL. New applications then enter the production review queue. Approved test keys still use the staging API base URL, while approved production keys use `https://hfsaa-public-api.idris-ocasio.workers.dev`.
Run a controlled HFSAA-owned test submission before sharing the form publicly. If a separately isolated staging intake is needed later, copy the form and script and give that copy its own staging-only ingestion token.
## Recovery while the custom domain is unavailable
The October 2026 outage affected `api.hfsaa.org`; the production Worker remained reachable at `https://hfsaa-public-api.idris-ocasio.workers.dev`. While the custom domain is being repaired, use that production Worker for both the form's `HFSAA_INGEST_URL` and the Worker's `PUBLIC_API_BASE_URL`. Updating both keeps verification, claim, management, and administrator links reachable. Keep the existing production ingestion secret and the staging URL.
Add `integrations/google-forms/Recovery.gs` alongside `Code.gs`. Run `enableProductionRecoveryEndpoint` to verify production health and the existing ingestion secret before changing the form URL. It saves the previous URL in `HFSAA_PRE_RECOVERY_INGEST_URL`. Run `checkIntakeConnection` for subsequent checks. These functions send an empty payload that must return `400 invalid_application` after authentication; they do not create applications or send verification emails.
The old DNS zone used `cullen.ns.cloudflare.com` and `iris.ns.cloudflare.com`. Cloudflare's October 4 alert detected a move to `sullivan.ns.cloudflare.com` and `ulla.ns.cloudflare.com`; the old zone was deleted October 11. Identify the administrator of the current authoritative DNS account before restoring the custom domain. Preserve the working website and mail records. After `https://api.hfsaa.org/health` returns the production health response, restore both URL settings together and run `checkIntakeConnection` again.
The form retains submitted responses even when its trigger fails. Review failed executions and the retained responses before retrying specific submissions; a retry may send the applicant a verification email. The recovery checks do not replay submissions. `replayFailedOctoberApplications` is prepared for the two reviewed October 24–26 submissions and must be run only after approving those verification emails. It refuses an unexpected response count and records each successful replay so a later run skips completed submissions.
Resend's `developers.hfsaa.org` sending domain also lost its required DKIM and SPF records. Restore the records shown in Resend's domain settings in the current authoritative DNS zone, then restart domain verification. Until the domain verifies, automatic application, approval, and management emails remain unavailable.
For the two authorized October recovery emails, `prepareManualOctoberVerificationEmails` persists each application and prepares the same deterministic verification link used by the Worker. Links are temporarily kept in `HFSAA_OCTOBER_MANUAL_EMAILS` in Script Properties and never logged. Before sending through the HFSAA mailbox, confirm each prepared token hash matches its saved application's `verification_token_hash` and the application still requires email verification. After both messages appear in Sent, run `completeManualOctoberVerificationRecovery` to mark those responses complete and remove the temporary links. Do not rerun preparation after sending: it may refresh the expiry of an existing link.
# HFSAA Public API
Source: https://hfsaa.mintlify.app/index
A public directory API for HFSAA-certified restaurants, meat markets, and dining halls.
> [!NOTE]
>
> **Production endpoint update.** Use `https://hfsaa-public-api.idris-ocasio.workers.dev` while the custom domain is being restored. Existing production keys continue to work at this address.
The HFSAA Public API makes HFSAA-approved directory data available to approved third-party applications through revocable, usage-tracked API keys.
> **[Apply for API access](https://hfsaa-public-api.idris-ocasio.workers.dev/developer/apply)**
>
> Request a non-expiring, quota-limited test key or apply for production capacity.
## What the API includes
* HFSAA-certified restaurants
* HFSAA-certified meat markets
* HFSAA-certified dining halls
* HFSAA chapter information and an official per-location verification URL
* An optional Google Place ID for developers who choose to enrich their own views through Google Places
## Verification and attribution
When your product states or implies that a location is certified or halal verified by HFSAA, identify HFSAA and give users reasonable access to that location's exact `verification_url`. The URL can be attached to the statement, HFSAA name, badge, **Learn more** link, or another clearly related details element.
The [data policy](/data-policy) permits durable caching, complete snapshots, and online or offline redistribution, subject to its attribution, verification, modification, and one-hour freshness requirements.
## What the API does not include
* Certificate IDs or certificate dates
* Google photos, photo URLs, Google Maps URLs, or Google-derived business details
* Contact names, contact emails, or internal operational data
* Write endpoints
## Production base URL
`https://hfsaa-public-api.idris-ocasio.workers.dev`
> **[Explore the API reference](/api-reference/locations/list-locations)**
>
> Browse the available endpoints, filters, and data schemas.