# Admin Portal リンクを作成

`POST /v1/admin-portal-links` · 権限 `admin-portal-links:write`

顧客組織の IT 管理者が、サポートチームを介さずに、ホステッド Admin Portal で SSO、ディレクトリ同期、ドメイン確認などを設定できるリンクを作成します。管理者がお使いのアプリケーションで「SSO を設定」をクリックするたびに新しいリンクを作成し、直ちに `url` へリダイレクトしてください。リンクの有効期間は 5 分で、ポータルセッションを 1 回だけ開けます。`url` はこのレスポンスでのみ 1 回返され、それ以降はどのエンドポイントでも返されません。レスポンスには `Cache-Control: no-store` が付き、同じ `Idempotency-Key` で再生されたレスポンスには `url` が含まれず、`secret_redacted: true` が付きます。ポータルセッションはアイドル 60 分、最長 8 時間です。`DELETE /v1/admin-portal-links/{link_id}` で取り消せます。作成は `admin_portal_link.created` として監査されます（URL が監査ログに記録されることはありません）。

`audit_logs` には Business プランが、`log_streams` には Enterprise プランが必要です。そのほかのインテントはすべてのプランで利用できます。`delivery: email` の場合は代わりに招待を送信します。招待は 7 日間有効で、`recipient_email` にメールで届きます。レスポンスには `url` もアドレスも含まれません。受信者が招待を開くと、同じアドレスに 6 桁のコード（有効期間 10 分）が送られ、検証済みのコードだけがポータルセッションを開きます。招待メールを送信できない場合、呼び出しは `503 service_unavailable` と `Retry-After` で応答し、何も作成されません。招待は `DELETE /v1/admin-portal-links/{link_id}` で取り消せます。受信者のアドレスは、レスポンス、一覧、監査ログ、いかなるログにも現れません。

## リクエスト

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `organization_id` | string | はい | 組織 ID（`org_…`）。この環境に存在している必要があります。 |
| `intents` | string[] | はい | `sso`、`dsync`、`domain_verification`、`certificate_renewal`、`audit_logs`（Business）、`log_streams`（Enterprise）のうち 1〜6 個。同じ値の重複は不可。 |
| `return_url` | string | はい | 2048 バイト以内の絶対 `https` URL。ユーザー情報とフラグメントを含まないこと。そのオリジンは、この環境に登録された有効なアプリケーションの `redirect_uri` のオリジンと一致する必要があります。 |
| `delivery` | string | いいえ | `link`（既定値。レスポンスに 5 分間有効なワンタイム `url` を含む）または `email`（`recipient_email` にメールで送られる 7 日間有効の招待。`url` は含まない）。 |
| `recipient_email` | string | いいえ | `delivery: email` の場合のみ指定でき、その場合は必須です。320 文字以内。未指定の場合: `422` の `/recipient_email` `required`。`delivery: link` の場合: `not_allowed`。アドレスが不正な場合: `invalid_value`。 |

## レスポンス

リンクと、そのワンタイム `url` を含む `201 Created`。

```json
{
  "id": "apl_01j9xv2c4d6e8f0g2h4j6k8m0n",
  "organization_id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "intents": [
    "dsync",
    "sso"
  ],
  "delivery": "link",
  "return_url": "https://app.example.com/settings/sso",
  "expires_at": "2026-10-12T09:36:00.123456Z",
  "consumed_at": null,
  "revoked_at": null,
  "created_at": "2026-10-12T09:31:00.123456Z",
  "url": "https://acme.eu.keenauth.app/portal/l/<token>"
}
```

## エラー

| HTTP | code | 発生条件 |
|---|---|---|
| 403 | `plan_feature_unavailable` | インテントにより上位プランが必要です。`feature` と `required_plan` がそれを示します。 |
| 404 | `not_found` | 組織がこの環境に存在しません。 |
| 409 | `organization_disabled` | 組織がアクティブではありません（無効化されています）。リンクは作成されません。 |
| 409 | `organization_pending_deletion` | 組織は削除予定です。リンクは作成されません。 |
| 422 | `validation_failed` | フィールドが欠けているか不正です。`/return_url` の `origin_not_registered` は、オリジンが登録済みアプリケーションのものでない場合です。`/recipient_email` の `required`、`not_allowed`、`invalid_value`。 |
| 401 | `unauthenticated` | 資格情報が欠けているか、不正か、取り消されています。 |
| 403 | `insufficient_permissions` | 資格情報に必要な権限がありません。 |
| 429 | `rate_limited` | レート制限を超えました。`Retry-After` の時間が経過してから再試行してください。 |
| 503 | `service_unavailable` | 依存先が一時的に利用できないか、（`delivery: email` の場合）招待メールを送信できません。何も作成されません。`Retry-After` の時間が経過してから再試行してください。 |

## 例

```bash
curl -i -X POST "https://api.eu.keenauth.com/v1/admin-portal-links" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"organization_id":"org_01j9xk3m7q8r2s4t6v8w0y2z4a","intents":["sso","dsync"],"return_url":"https://app.example.com/settings/sso"}'
```

### メールで招待を送信する

```bash
curl -i -X POST "https://api.eu.keenauth.com/v1/admin-portal-links" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"organization_id":"org_01j9xk3m7q8r2s4t6v8w0y2z4a","intents":["sso"],"return_url":"https://app.example.com/settings/sso","delivery":"email","recipient_email":"it@customer.example"}'
```

`201 Created`。レスポンスには `url` もアドレスも含まれません。

```json
{
  "id": "apl_01j9xv2c4d6e8f0g2h4j6k8m0n",
  "organization_id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "intents": [
    "sso"
  ],
  "delivery": "email",
  "return_url": "https://app.example.com/settings/sso",
  "expires_at": "2026-10-19T09:31:00.123456Z",
  "consumed_at": null,
  "revoked_at": null,
  "created_at": "2026-10-12T09:31:00.123456Z"
}
```

CLI の場合: `keenauth admin-portal-links create --organization-id org_01j9xk3m7q8r2s4t6v8w0y2z4a --intents sso --return-url https://app.example.com/settings/sso --delivery email --recipient-email it@customer.example`。