Organizzazioni — riferimento dell'API di PassportCraft

Elencare le organizzazioni per cui questa chiave può agire.

get/organizations

Ambito: Nessun ambito richiesto
Idempotency-Key: Non accettata
Restituisce: 200

Errori

Tutti i rifiuti che questo endpoint può restituire, con lo stato con cui arrivano.

Richiesta

curl "https://passportcraft.com/api/v1/organizations" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

Risposta · 200

{
  "object": "list",
  "data": [
    {
      "object": "connection",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "display_name": "Atelier Nord",
      "link_status": null,
      "scopes": [
        "passports:read",
        "passports:write",
        "keys:admin"
      ],
      "granted_at": "2026-07-14T11:02:19.004Z"
    },
    {
      "object": "connection",
      "organization_id": "3c59dc04-8f7b-4d0e-9c1a-5f2b6e7d8a90",
      "name": "organizations/3c59dc04-8f7b-4d0e-9c1a-5f2b6e7d8a90",
      "display_name": "Acme Apparel",
      "link_status": "accepted",
      "scopes": [
        "passports:read",
        "passports:write"
      ],
      "granted_at": "2026-09-22T08:15:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET /organizations

Dare a una chiave l'accesso a un'organizzazione cliente.

post/organizations/{organization}/grants

Ambito: keys:admin
Idempotency-Key: Non accettata
Restituisce: 201

Parametri di percorso

organizationstringaObbligatorio

L'organizzazione cliente. La chiave usata per la chiamata deve disporre di keys:admin nella propria organizzazione, e tale organizzazione deve gestire questo cliente; qui la chiave non ha bisogno di alcuna concessione.

Corpo della richiesta

key_idstringaObbligatorio

L'identificativo pubblico di una chiave di proprietà della Sua organizzazione, nella stessa modalità della chiave usata per la chiamata, così come GET /whoami lo riporta in key_id.

scopesarray di stringheObbligatorio

Ciò che la chiave può fare in questa organizzazione. Ogni ambito deve essere consentito dagli ambiti di cui la chiave dispone nella propria organizzazione (un ambito di scrittura consente anche il corrispondente ambito di lettura); keys:admin non viene mai concesso per un cliente.

Errori

Tutti i rifiuti che questo endpoint può restituire, con lo stato con cui arrivano.

Richiesta

curl "https://passportcraft.com/api/v1/organizations/3c59dc04-8f7b-4d0e-9c1a-5f2b6e7d8a90/grants" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "key_id": "K3n9Qw2P",
  "scopes": [
    "passports:read",
    "passports:write"
  ]
}'

Risposta · 201

{
  "object": "grant",
  "organization_id": "3c59dc04-8f7b-4d0e-9c1a-5f2b6e7d8a90",
  "key_id": "K3n9Qw2P",
  "scopes": [
    "passports:read",
    "passports:write"
  ],
  "granted_at": "2026-09-22T08:15:00.000Z"
}

POST /organizations/3c59dc04-8f7b-4d0e-9c1a-5f2b6e7d8a90/grants

Porre fine all'accesso di una chiave a una singola organizzazione cliente.

delete/organizations/{organization}/grants/{keyId}

Ambito: keys:admin
Idempotency-Key: Non accettata
Restituisce: 200

Parametri di percorso

organizationstringaObbligatorio

L'organizzazione cliente. La chiave usata per la chiamata deve disporre di keys:admin nella propria organizzazione, e tale organizzazione deve gestire questo cliente; qui la chiave non ha bisogno di alcuna concessione.

keyIdstringaObbligatorio

L'identificativo della risorsa. Lo tratti come una stringa opaca.

Errori

Tutti i rifiuti che questo endpoint può restituire, con lo stato con cui arrivano.

Richiesta

curl "https://passportcraft.com/api/v1/organizations/3c59dc04-8f7b-4d0e-9c1a-5f2b6e7d8a90/grants/K3n9Qw2P" \
  -X DELETE \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

Risposta · 200

{
  "object": "grant",
  "organization_id": "3c59dc04-8f7b-4d0e-9c1a-5f2b6e7d8a90",
  "key_id": "K3n9Qw2P",
  "status": "revoked"
}

DELETE /organizations/3c59dc04-8f7b-4d0e-9c1a-5f2b6e7d8a90/grants/K3n9Qw2P

Descrivere che cosa questa chiave può fare per questa organizzazione.

get/organizations/{organization}/capabilities

Ambito: passports:read
Idempotency-Key: Non accettata
Restituisce: 200

Parametri di percorso

organizationstringaObbligatorio

L'organizzazione per cui questa richiesta agisce. La chiave deve avere una concessione su di essa.

Errori

Tutti i rifiuti che questo endpoint può restituire, con lo stato con cui arrivano.

Richiesta

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/capabilities" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

Risposta · 200

{
  "object": "list",
  "data": [
    {
      "object": "capability",
      "id": "passport_publishing",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/capabilities/passport_publishing",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "livemode": true,
      "requested": true,
      "allowed": true,
      "verification_status": "valid",
      "problems": [],
      "detail": {
        "plan_id": "pro",
        "subscription_status": "trialing",
        "publish_limit": 500,
        "published_count": 37,
        "per_passport_check": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/{id}/validate"
      }
    },
    {
      "object": "capability",
      "id": "france_affichage_filing",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/capabilities/france_affichage_filing",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "livemode": true,
      "requested": true,
      "allowed": false,
      "verification_status": "pending",
      "problems": [
        {
          "code": "delegation_required",
          "message": "The delegation is awaiting verification against the French portal.",
          "type": "pending",
          "remediating_actions": [
            {
              "code": "await_portal_verification",
              "message": "No action is required. Poll this capability until verification completes."
            }
          ]
        }
      ],
      "detail": {
        "delegation_status": "pending",
        "portal_brand_id": null,
        "delegated_at": "2026-07-30T16:20:00.000Z",
        "entitlement": "free_offer",
        "free_filing_reason": "available",
        "per_passport_requirements": [
          "gtin_required",
          "attestation_required"
        ],
        "attestation_wording_version": "2026-09-19.1",
        "per_passport_check": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/{id}/affichage",
        "api_filing_supported": true,
        "api_filing_scope": "filings:write"
      }
    },
    {
      "object": "capability",
      "id": "document_upload",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/capabilities/document_upload",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "livemode": true,
      "requested": true,
      "allowed": true,
      "verification_status": "valid",
      "problems": [],
      "detail": {
        "document_limit": 50,
        "documents_used": 12
      }
    },
    {
      "object": "capability",
      "id": "live_api_writes",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/capabilities/live_api_writes",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "livemode": true,
      "requested": true,
      "allowed": false,
      "verification_status": "invalid",
      "problems": [
        {
          "code": "no_subscription",
          "message": "Live API writes start when the trial becomes a paid subscription.",
          "type": "invalid",
          "remediating_actions": [
            {
              "code": "add_subscription",
              "message": "Convert the trial to a paid subscription."
            }
          ]
        }
      ],
      "detail": {
        "subscription_status": "trialing",
        "plan_id": "pro"
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/capabilities