docs: API key shown-once behavior + permission scoping (155917/155921/156737)

[mhmojtahedi]

Documents the API-key security work from core_backend tickets #155917, #155921, #156737 (core PRs ottuco/core_backend#208, ottuco/core_backend#350).

What changed

Developers

• getting-started/authentication.md — the private key is now shown once at creation and cannot be re-read; keys are full access (all pre-existing keys, unchanged) or scoped to an explicit permission set. Removed the "all permissions are granted by default" claim.
• New reference/api-key-permissions.md — the operation→permission catalog for scoped keys (same vocabulary as dashboard users), with the guarantees stated up front: existing keys unaffected, SDK/public-key guest flows never blocked, scoped-without-perm → 403. Added to the Reference sidebar.

Business

• settings/api-keys.mdx — the step-by-step no longer instructs merchants to click the key later to view it (impossible now). Step 4 is "copy the private key — shown only once"; the entry keeps only the public key. Form table gains Full access and Permissions fields.

API reference (generated)

• _shared/permissions.yaml blocks updated, then npm run gen-api — every endpoint page's Permissions table now describes both key modes and links to the catalog instead of claiming "All permissions (admin access)".

Review notes

• ⚠️ Screenshots api-keys-03/04/05 show the old admin form (no Full access/Permissions fields, old key-viewing flow) and need retakes once a server with the new admin is available.
• npm run build passes; the broken-anchor warnings in the log are pre-existing on main (glossary term anchors etc.), none from these pages.
• Suggest holding merge until the backend stack (core PRs #208/#350) is deployed to production, so docs don't describe behavior merchants don't have yet.

[mhmojtahedi]

Documents the API-key security work from core_backend tickets #155917, #155921, #156737 (core PRs ottuco/core_backend#208, ottuco/core_backend#350).

What changed

Developers

• getting-started/authentication.md — the private key is now shown once at creation and cannot be re-read; keys are full access (all pre-existing keys, unchanged) or scoped to an explicit permission set. Removed the "all permissions are granted by default" claim.
• New reference/api-key-permissions.md — the operation→permission catalog for scoped keys (same vocabulary as dashboard users), with the guarantees stated up front: existing keys unaffected, SDK/public-key guest flows never blocked, scoped-without-perm → 403. Added to the Reference sidebar.

Business

• settings/api-keys.mdx — the step-by-step no longer instructs merchants to click the key later to view it (impossible now). Step 4 is "copy the private key — shown only once"; the entry keeps only the public key. Form table gains Full access and Permissions fields.

API reference (generated)

• _shared/permissions.yaml blocks updated, then npm run gen-api — every endpoint page's Permissions table now describes both key modes and links to the catalog instead of claiming "All permissions (admin access)".

Review notes

• ⚠️ Screenshots api-keys-03/04/05 show the old admin form (no Full access/Permissions fields, old key-viewing flow) and need retakes once a server with the new admin is available.
• npm run build passes; the broken-anchor warnings in the log are pre-existing on main (glossary term anchors etc.), none from these pages.
• Suggest holding merge until the backend stack (core PRs #208/#350) is deployed to production, so docs don't describe behavior merchants don't have yet.

[mhmojtahedi]

Documents the API-key security work from core_backend tickets #155917, #155921, #156737 (core PRs ottuco/core_backend#208, ottuco/core_backend#350).

What changed

Developers

• getting-started/authentication.md — the private key is now shown once at creation and cannot be re-read; keys are full access (all pre-existing keys, unchanged) or scoped to an explicit permission set. Removed the "all permissions are granted by default" claim.
• New reference/api-key-permissions.md — the operation→permission catalog for scoped keys (same vocabulary as dashboard users), with the guarantees stated up front: existing keys unaffected, SDK/public-key guest flows never blocked, scoped-without-perm → 403. Added to the Reference sidebar.

Business

• settings/api-keys.mdx — the step-by-step no longer instructs merchants to click the key later to view it (impossible now). Step 4 is "copy the private key — shown only once"; the entry keeps only the public key. Form table gains Full access and Permissions fields.

API reference (generated)

• _shared/permissions.yaml blocks updated, then npm run gen-api — every endpoint page's Permissions table now describes both key modes and links to the catalog instead of claiming "All permissions (admin access)".

Review notes

• ⚠️ Screenshots api-keys-03/04/05 show the old admin form (no Full access/Permissions fields, old key-viewing flow) and need retakes once a server with the new admin is available.
• npm run build passes; the broken-anchor warnings in the log are pre-existing on main (glossary term anchors etc.), none from these pages.
• Suggest holding merge until the backend stack (core PRs #208/#350) is deployed to production, so docs don't describe behavior merchants don't have yet.

[mhmojtahedi]

Documents the API-key security work from core_backend tickets #155917, #155921, #156737 (core PRs ottuco/core_backend#208, ottuco/core_backend#350).

What changed

Developers

• getting-started/authentication.md — the private key is now shown once at creation and cannot be re-read; keys are full access (all pre-existing keys, unchanged) or scoped to an explicit permission set. Removed the "all permissions are granted by default" claim.
• New reference/api-key-permissions.md — the operation→permission catalog for scoped keys (same vocabulary as dashboard users), with the guarantees stated up front: existing keys unaffected, SDK/public-key guest flows never blocked, scoped-without-perm → 403. Added to the Reference sidebar.

Business

• settings/api-keys.mdx — the step-by-step no longer instructs merchants to click the key later to view it (impossible now). Step 4 is "copy the private key — shown only once"; the entry keeps only the public key. Form table gains Full access and Permissions fields.

API reference (generated)

• _shared/permissions.yaml blocks updated, then npm run gen-api — every endpoint page's Permissions table now describes both key modes and links to the catalog instead of claiming "All permissions (admin access)".

Review notes

• ⚠️ Screenshots api-keys-03/04/05 show the old admin form (no Full access/Permissions fields, old key-viewing flow) and need retakes once a server with the new admin is available.
• npm run build passes; the broken-anchor warnings in the log are pre-existing on main (glossary term anchors etc.), none from these pages.
• Suggest holding merge until the backend stack (core PRs #208/#350) is deployed to production, so docs don't describe behavior merchants don't have yet.

[mhmojtahedi]

Documents the API-key security work from core_backend tickets #155917, #155921, #156737 (core PRs ottuco/core_backend#208, ottuco/core_backend#350).

What changed

Developers

• getting-started/authentication.md — the private key is now shown once at creation and cannot be re-read; keys are full access (all pre-existing keys, unchanged) or scoped to an explicit permission set. Removed the "all permissions are granted by default" claim.
• New reference/api-key-permissions.md — the operation→permission catalog for scoped keys (same vocabulary as dashboard users), with the guarantees stated up front: existing keys unaffected, SDK/public-key guest flows never blocked, scoped-without-perm → 403. Added to the Reference sidebar.

Business

• settings/api-keys.mdx — the step-by-step no longer instructs merchants to click the key later to view it (impossible now). Step 4 is "copy the private key — shown only once"; the entry keeps only the public key. Form table gains Full access and Permissions fields.

API reference (generated)

• _shared/permissions.yaml blocks updated, then npm run gen-api — every endpoint page's Permissions table now describes both key modes and links to the catalog instead of claiming "All permissions (admin access)".

Review notes

• ⚠️ Screenshots api-keys-03/04/05 show the old admin form (no Full access/Permissions fields, old key-viewing flow) and need retakes once a server with the new admin is available.
• npm run build passes; the broken-anchor warnings in the log are pre-existing on main (glossary term anchors etc.), none from these pages.
• Suggest holding merge until the backend stack (core PRs #208/#350) is deployed to production, so docs don't describe behavior merchants don't have yet.

[mhmojtahedi]

Documents the API-key security work from core_backend tickets #155917, #155921, #156737 (core PRs ottuco/core_backend#208, ottuco/core_backend#350).

What changed

Developers

• getting-started/authentication.md — the private key is now shown once at creation and cannot be re-read; keys are full access (all pre-existing keys, unchanged) or scoped to an explicit permission set. Removed the "all permissions are granted by default" claim.
• New reference/api-key-permissions.md — the operation→permission catalog for scoped keys (same vocabulary as dashboard users), with the guarantees stated up front: existing keys unaffected, SDK/public-key guest flows never blocked, scoped-without-perm → 403. Added to the Reference sidebar.

Business

• settings/api-keys.mdx — the step-by-step no longer instructs merchants to click the key later to view it (impossible now). Step 4 is "copy the private key — shown only once"; the entry keeps only the public key. Form table gains Full access and Permissions fields.

API reference (generated)

• _shared/permissions.yaml blocks updated, then npm run gen-api — every endpoint page's Permissions table now describes both key modes and links to the catalog instead of claiming "All permissions (admin access)".

Review notes

• ⚠️ Screenshots api-keys-03/04/05 show the old admin form (no Full access/Permissions fields, old key-viewing flow) and need retakes once a server with the new admin is available.
• npm run build passes; the broken-anchor warnings in the log are pre-existing on main (glossary term anchors etc.), none from these pages.
• Suggest holding merge until the backend stack (core PRs #208/#350) is deployed to production, so docs don't describe behavior merchants don't have yet.

[mhmojtahedi]

Documents the API-key security work from core_backend tickets #155917, #155921, #156737 (core PRs ottuco/core_backend#208, ottuco/core_backend#350).

What changed

Developers

• getting-started/authentication.md — the private key is now shown once at creation and cannot be re-read; keys are full access (all pre-existing keys, unchanged) or scoped to an explicit permission set. Removed the "all permissions are granted by default" claim.
• New reference/api-key-permissions.md — the operation→permission catalog for scoped keys (same vocabulary as dashboard users), with the guarantees stated up front: existing keys unaffected, SDK/public-key guest flows never blocked, scoped-without-perm → 403. Added to the Reference sidebar.

Business

• settings/api-keys.mdx — the step-by-step no longer instructs merchants to click the key later to view it (impossible now). Step 4 is "copy the private key — shown only once"; the entry keeps only the public key. Form table gains Full access and Permissions fields.

API reference (generated)

• _shared/permissions.yaml blocks updated, then npm run gen-api — every endpoint page's Permissions table now describes both key modes and links to the catalog instead of claiming "All permissions (admin access)".

Review notes

• ⚠️ Screenshots api-keys-03/04/05 show the old admin form (no Full access/Permissions fields, old key-viewing flow) and need retakes once a server with the new admin is available.
• npm run build passes; the broken-anchor warnings in the log are pre-existing on main (glossary term anchors etc.), none from these pages.
• Suggest holding merge until the backend stack (core PRs #208/#350) is deployed to production, so docs don't describe behavior merchants don't have yet.

[mhmojtahedi]

Documents the API-key security work from core_backend tickets #155917, #155921, #156737 (core PRs ottuco/core_backend#208, ottuco/core_backend#350).

What changed

Developers

• getting-started/authentication.md — the private key is now shown once at creation and cannot be re-read; keys are full access (all pre-existing keys, unchanged) or scoped to an explicit permission set. Removed the "all permissions are granted by default" claim.
• New reference/api-key-permissions.md — the operation→permission catalog for scoped keys (same vocabulary as dashboard users), with the guarantees stated up front: existing keys unaffected, SDK/public-key guest flows never blocked, scoped-without-perm → 403. Added to the Reference sidebar.

Business

• settings/api-keys.mdx — the step-by-step no longer instructs merchants to click the key later to view it (impossible now). Step 4 is "copy the private key — shown only once"; the entry keeps only the public key. Form table gains Full access and Permissions fields.

API reference (generated)

• _shared/permissions.yaml blocks updated, then npm run gen-api — every endpoint page's Permissions table now describes both key modes and links to the catalog instead of claiming "All permissions (admin access)".

Review notes

• ⚠️ Screenshots api-keys-03/04/05 show the old admin form (no Full access/Permissions fields, old key-viewing flow) and need retakes once a server with the new admin is available.
• npm run build passes; the broken-anchor warnings in the log are pre-existing on main (glossary term anchors etc.), none from these pages.
• Suggest holding merge until the backend stack (core PRs #208/#350) is deployed to production, so docs don't describe behavior merchants don't have yet.