组织 — PassportCraft API 参考

列出该凭据可代为操作的组织。

get/organizations

作用域: 无需作用域
Idempotency-Key: 不接受
返回: 200

错误

该端点可能返回的全部拒绝，以及它们所带的 HTTP 状态码。

请求

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

响应 · 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

授予某个密钥访问客户组织的权限。

post/organizations/{organization}/grants

作用域: keys:admin
Idempotency-Key: 不接受
返回: 201

路径参数

organization字符串必填

客户组织。发起调用的密钥须在其所属组织中持有 keys:admin，且该所属组织必须管理此客户；该密钥在此处无需任何授权。

请求体

key_id字符串必填

您的组织所拥有、且与发起调用的密钥处于同一模式的某个密钥的公开 id，即 GET /whoami 在 key_id 中返回的值。

scopes字符串数组必填

该密钥在此组织中可以执行的操作。每个作用域都必须为该密钥在其所属组织中自身的作用域所允许（写入作用域同时允许对应的读取作用域）；为客户授权时，永远不会授予 keys:admin。

错误

该端点可能返回的全部拒绝，以及它们所带的 HTTP 状态码。

请求

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

响应 · 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

终止某个密钥对单个客户组织的访问权限。

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

作用域: keys:admin
Idempotency-Key: 不接受
返回: 200

路径参数

organization字符串必填

客户组织。发起调用的密钥须在其所属组织中持有 keys:admin，且该所属组织必须管理此客户；该密钥在此处无需任何授权。

keyId字符串必填

资源的标识符。请把它当作不可解析的字符串处理。

错误

该端点可能返回的全部拒绝，以及它们所带的 HTTP 状态码。

请求

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

响应 · 200

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

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

说明该凭据可为此组织执行哪些操作。

get/organizations/{organization}/capabilities

作用域: passports:read
Idempotency-Key: 不接受
返回: 200

路径参数

organization字符串必填

本次请求代为操作的组织。密钥必须已获得该组织的授权。

错误

该端点可能返回的全部拒绝，以及它们所带的 HTTP 状态码。

请求

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

响应 · 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