ClearPass Air
Developer sandbox

ClearPass Air Partner Authorization API

One call tells a vertiport, operator, or ground handler whether an inbound aircraft and the people on board are authorized to arrive — with reason codes that explain exactly why.

Sandbox only — simulated data
API version v1
ClearPass Air is not a government authority. It does not grant TSA, CBP, FAA, or air traffic clearance. Where a decision depends on an external authority, the API relays that authority's status and names the source. All sources in this sandbox are simulated.

Authentication

Send your sandbox key as a bearer token. Every key is partner-bound, endpoint-scoped and expiring: it is issued for one partner, for one or more explicit endpoint scopes, and with an expiry between 1 and 168 hours (72 hours by default). Keys are hashed at rest and rate limited per endpoint. A key is issued once from Partner Admin, shown a single time, and can never be retrieved again. Keys are issued separately from this page and delivered only through an approved secure channel — the value below is a nonworking placeholder.

Requests without a valid, unexpired key return 401. A valid key calling an endpoint outside its scopes returns a generic 403 insufficient_scope that discloses nothing about the partner, the trip, or which scopes the key holds. Requests for another partner's trip return 404.

Authorization: Bearer cp_sandbox_your_key_here

Endpoint scopes

  • authorization:check — POST /api/public/v1/authorization/check
  • arrivals:read — GET /api/public/v1/arrivals
  • decisions:read — GET /api/public/v1/decisions/:id
  • webhooks:test — POST /api/public/v1/webhooks/test
  • /api/public/v1/health requires no key and no scope.

Endpoints

GET
/api/public/v1/health

Service and sandbox status. No authentication required.

POST
/api/public/v1/authorization/check

Evaluate an arrival and return a persisted decision as a minimum-disclosure, partner-safe payload.

GET
/api/public/v1/arrivals

Upcoming arrivals scoped to your partner, with the latest decision per trip.

GET
/api/public/v1/decisions/{id}

Retrieve a previously issued decision record, including its policy version.

POST
/api/public/v1/webhooks/test

Simulate a signed decision webhook delivery in the sandbox.

Examples

Nonworking placeholder — request scoped sandbox access separately. Every host and key in these examples is deliberately fake. https://your-clearpass-host and cp_sandbox_your_key_here will not resolve or authenticate. Sandbox data, external status sources, and webhook deliveries are simulated; ClearPass Air is not a government authority and names no real partner.

curl -X POST https://your-clearpass-host/api/public/v1/authorization/check \
  -H "Authorization: Bearer cp_sandbox_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "trip_id": "00000000-0000-4000-8000-000000000000" }'
{
  "decision_id": "f238aa67-9eaf-42f0-a1bd-88895d3fef12",
  "trip": {
    "trip_reference": "CPA-TRIP-1002",
    "destination": "KTEB",
    "operator": "Meridian Air Mobility",
    "tail_number": "N221CP",
    "passenger_count": 4,
    "billing_responsibility": "operator"
  },
  "decision": "manual_review",
  "external_reason_codes": ["IDENTITY_REQUIREMENTS_NOT_MET"],
  "subject_summary": { "total": 4, "cleared": 3, "action_required": 1 },
  "action_required_subjects": [
    {
      "subject_token": "sub_3f9c21ab6d40e5c7",
      "role": "passenger",
      "status": "manual_review",
      "external_reason_codes": ["IDENTITY_REQUIREMENTS_NOT_MET"]
    }
  ],
  "requirements": {
    "identity_requirements_met": false,
    "manifest_requirements_met": true,
    "data_sharing_authorized": true,
    "operator_requirements_met": true,
    "aircraft_requirements_met": true,
    "location_policy_requirements_met": true
  },
  "arrival_reservation": { "authority": "Vertiport Reservation System (Simulated)", "status": "cleared" },
  "air_traffic_status": {
    "authority": "National Airspace Status Feed (Simulated)",
    "status": "cleared",
    "note": "Received from an external authoritative source. ClearPass Air does not issue air traffic clearance."
  },
  "final_clearpass_decision": {
    "decision": "manual_review",
    "external_reason_codes": ["IDENTITY_REQUIREMENTS_NOT_MET"],
    "summary": "Arrival CPA-TRIP-1002 requires review before arrival. Identity requirements are not met for this arrival.",
    "evaluated_at": "2026-01-01T00:00:00.000Z"
  },
  "environment": "sandbox"
}

Rate limits

Limits are applied per API key, per endpoint. Exceeding one returns 429 rate_limited; retry with exponential backoff.

POST /api/public/v1/authorization/check60 requests / minute / key
GET /api/public/v1/arrivals120 requests / minute / key
GET /api/public/v1/decisions/{id}120 requests / minute / key
POST /api/public/v1/webhooks/test30 requests / minute / key

Sandbox vs production

  • Only the sandbox environment exists today. Every partner, location, trip, credential, and trusted source is fictional.
  • Sandbox keys are prefixed cp_sandbox_ and are issued once from Partner Admin.
  • Health responses report "environment": "sandbox" — check it before wiring the API into an operational workflow.
  • Production access requires a signed agreement and a real data-source integration review. Contact us to start that process.

Partner isolation

  • Every key is bound to exactly one partner and to an explicit set of endpoint scopes; both are enforced server-side on every request.
  • Requesting another partner's trip or decision returns 404 not_found, so identifiers cannot be probed. A scope failure returns a generic 403 insufficient_scope with no partner or trip detail.
  • Keys are stored as SHA-256 hashes and always carry an expiry (1–168 hours). Expired and revoked keys are permanently unusable and cannot be re-enabled; rotate instead. Rotation keeps the original scopes and the original expiry, so access is never silently extended.
  • Each request is logged with its request id, endpoint, status, and latency.

Decision values

authorized

All required checks satisfied for this arrival.

conditionally_authorized

Cleared to arrive with outstanding ground-side conditions.

manual_review

A human decision is required before arrival.

denied

Blocking conditions prevent authorization.

expired

A required credential or window has lapsed.

awaiting_external_clearance

Waiting on a trusted external authority to respond.

Reason categories

Every decision returns machine-readable, partner-safe reason categories. They are stable identifiers — build your ground workflows against them. ClearPass Air keeps finer-grained internal reason codes for its own decision and audit records; those are never disclosed to a partner.

TRIP_AUTHORIZEDAll requirements for this arrival are satisfied.
DATA_SHARING_NOT_AUTHORIZEDData sharing for one or more subjects is not authorized for this partner.
IDENTITY_REQUIREMENTS_NOT_METIdentity requirements are not met for this arrival.
CREDENTIAL_REQUIREMENTS_NOT_METRequired credentials are not currently satisfied.
MANIFEST_REQUIREMENTS_NOT_METManifest requirements are not met for this arrival.
OPERATOR_REQUIREMENTS_NOT_METOperator requirements are not met for this arrival.
AIRCRAFT_REQUIREMENTS_NOT_METAircraft requirements are not met for this arrival.
ARRIVAL_RESERVATION_PENDINGThe arrival reservation is not confirmed.
LOCATION_POLICY_REQUIREMENTS_NOT_METDestination policy requirements are not met.
EXTERNAL_STATUS_PENDINGAn external status source has not yet responded.
GROUND_CONDITIONS_PENDINGThe arrival may proceed, but a ground-side condition at the destination is still open.

Data minimization

  • Partners receive a decision, generalized requirement flags, and aggregate subject counts — never names, photos, documents, or templates.
  • No persistent ClearPass identifier is disclosed. Where an action is required, the subject is referenced by a subject_token derived with SHA-256 over a random per-response value plus that trip and decision, so it is stable within one response, one-way, and cannot be correlated across arrivals.
  • Assurance tiers, biometric provider, match, liveness, confidence and timestamps, consent history, and the raw policy checklist are never included in the partner payload.
  • Cleared subjects are reported only as a count, never individually.
  • Every response is scoped to the partner that owns the trip.
  • Subjects can revoke a partner's access at any time; the next check reflects it as DATA_SHARING_NOT_AUTHORIZED.
Request sandbox access