Ir al contenido

Recursos

Organizaciones

Todos los endpoints de Organizaciones, con el ámbito que imponen, el cuerpo que admiten, una respuesta legible y los rechazos que pueden devolver.

Listar las organizaciones por las que esta clave puede actuar.

get/organizations
Ámbito
No requiere ámbito
Idempotency-Key
No se acepta
Devuelve
200

Errores

Todos los rechazos que este endpoint puede devolver, con el estado con el que llegan.

Solicitud
curl "https://passportcraft.com/api/v1/organizations" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"
Respuesta · 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

Dar a una clave acceso a una organización cliente.

post/organizations/{organization}/grants
Ámbito
keys:admin
Idempotency-Key
No se acepta
Devuelve
201

Parámetros de ruta

organizationcadenaObligatorio

La organización cliente. La clave que hace la llamada necesita keys:admin en la organización a la que pertenece, y esa organización debe gestionar este cliente; aquí la clave no necesita ninguna concesión.

Cuerpo de la solicitud

key_idcadenaObligatorio

El identificador público de una clave que pertenece a su organización y está en el mismo modo que la clave que hace la llamada, tal como lo indica GET /whoami en key_id.

scopesmatriz de cadenasObligatorio

Lo que la clave puede hacer en esta organización. Cada ámbito debe estar permitido por los ámbitos que la clave tiene en su propia organización (un ámbito de escritura también permite el ámbito de lectura correspondiente); keys:admin nunca se concede para un cliente.

Errores

Todos los rechazos que este endpoint puede devolver, con el estado con el que llegan.

Solicitud
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"
  ]
}'
Respuesta · 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

Poner fin al acceso de una clave a una sola organización cliente.

delete/organizations/{organization}/grants/{keyId}
Ámbito
keys:admin
Idempotency-Key
No se acepta
Devuelve
200

Parámetros de ruta

organizationcadenaObligatorio

La organización cliente. La clave que hace la llamada necesita keys:admin en la organización a la que pertenece, y esa organización debe gestionar este cliente; aquí la clave no necesita ninguna concesión.

keyIdcadenaObligatorio

El identificador del recurso. Trátelo como una cadena opaca.

Errores

Todos los rechazos que este endpoint puede devolver, con el estado con el que llegan.

Solicitud
curl "https://passportcraft.com/api/v1/organizations/3c59dc04-8f7b-4d0e-9c1a-5f2b6e7d8a90/grants/K3n9Qw2P" \
  -X DELETE \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"
Respuesta · 200
{
  "object": "grant",
  "organization_id": "3c59dc04-8f7b-4d0e-9c1a-5f2b6e7d8a90",
  "key_id": "K3n9Qw2P",
  "status": "revoked"
}

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

Describir qué puede hacer esta clave por esta organización.

get/organizations/{organization}/capabilities
Ámbito
passports:read
Idempotency-Key
No se acepta
Devuelve
200

Parámetros de ruta

organizationcadenaObligatorio

La organización en cuyo nombre actúa esta solicitud. La clave debe tener concesión sobre ella.

Errores

Todos los rechazos que este endpoint puede devolver, con el estado con el que llegan.

Solicitud
curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/capabilities" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"
Respuesta · 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