Improve system user token guides #2558
Conversation
|
Note
|
| Cohort / File(s) | Summary |
|---|---|
System-user token documentation (multilingual) content/authorization/guides/system-vendor/system-user/usetoken/_index.en.md, content/authorization/guides/system-vendor/system-user/usetoken/_index.nb.md |
Full rewrite from a narrow "request system access token" page to a complete step-by-step guide: new Introduction and audience, table distinguishing own vs agent system-user types, prerequisites, JWT (RAR) construction, signing and using client_assertion, form-encoded token request and cURL examples, decoded JWT claim examples, Maskinporten response interpretation including authorization_details fields, PDP usage instructions toward Altinn, revised notices/warnings (single-customer per call, request vs response separation, key material and scope checks), and expanded "Common pitfalls and tips". Norwegian version also updates phrasing/capitalization and localizes examples. |
Estimated code review effort
🎯 3 (Moderate) | ⏱️ ~25 minutes
- Verify terminology and translation parity across English and Norwegian Bokmål files.
- Validate JWT/RAR claim examples,
client_assertionsigning guidance, and form-encoded request fields against Maskinporten specs. - Check the interpretation table for
authorization_details(fields such assystemuser_id,systemuser_org.ID,system_id,consumer.ID) for accuracy. - Confirm PDP usage instructions and example references correctly map which token claims to send to the PDP.
- Ensure warnings about single-customer requests and not reusing responses are clear and technically correct.
- Also check whether a corresponding Norwegian Nynorsk (nn-NO) version is needed or should be synchronized.
Poem
Tokens hum in form-encoded light,
JWTs signed and claims take flight,
System users, agent and own unite,
Maskinporten hands the key tonight,
Altinn waits — the PDP shines bright. 🔐
Pre-merge checks and finishing touches
❌ Failed checks (1 warning, 1 inconclusive)
| Check name | Status | Explanation | Resolution |
|---|---|---|---|
| Linked Issues check | The PR changes focus on system user token guides, but linked issue #1641 requires diagram integration with Diaogporten, BPMN v8 updates, ProcessDataWrite updates, and knowledge check modifications—none of which are present in this PR. | Verify that the correct issue was linked. If #1641 is the intended issue, implement the required diagram, BPMN/ProcessDataWrite updates, and knowledge check changes. Otherwise, link the PR to the correct issue. | |
| Out of Scope Changes check | ❓ Inconclusive | The PR contains comprehensive rewrites of system user token guides (English and Norwegian) with new structures, examples, and troubleshooting guidance, which aligns with implied documentation improvements but conflicts with the linked issue #1641 scope. | Clarify whether the system user token guide improvements are the actual scope or if this PR was incorrectly linked to #1641. Confirm the primary objective of this PR. |
✅ Passed checks (3 passed)
| Check name | Status | Explanation |
|---|---|---|
| Description Check | ✅ Passed | Check skipped - CodeRabbit’s high-level summary is enabled. |
| Title check | ✅ Passed | The title 'Improve system user token guides' accurately reflects the main changes: comprehensive rewrites of both English and Norwegian system user token guides with enhanced structure and examples. |
| Docstring Coverage | ✅ Passed | No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. |
✨ Finishing touches
🧪 Generate unit tests (beta)
- Create PR with unit tests
- Post copyable unit tests in a comment
- Commit unit tests in branch
docs/improve-system-user-token-guide
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
Comment @coderabbitai help to get the list of available commands and usage tips.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
content/authorization/guides/system-vendor/system-user/usetoken/_index.en.md (1)
113-115: Enhance clarity of critical notices.The two notices back-to-back (info and warning) could be combined or better separated for emphasis. The warning at 117-119 is critical (don't reuse response as request), so it might benefit from clearer formatting or earlier placement.
Consider reorganizing these notices or adding emphasis, but current placement is acceptable.
Also applies to: 117-119
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
content/authorization/guides/system-vendor/system-user/usetoken/_index.en.md(2 hunks)content/authorization/guides/system-vendor/system-user/usetoken/_index.nb.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (2)
content/**/*
⚙️ CodeRabbit configuration file
Check for links, markdown formatting, headings, grammar, and spelling in multiple languages (en-US, nb-NO, nn-NO).
Files:
content/authorization/guides/system-vendor/system-user/usetoken/_index.en.mdcontent/authorization/guides/system-vendor/system-user/usetoken/_index.nb.md
**/*.nb.md
⚙️ CodeRabbit configuration file
Check for Norwegian Bokmål (nb-NO) grammar and spelling with extra care. Pay special attention to specialized terminology and Norwegian-specific words.
Files:
content/authorization/guides/system-vendor/system-user/usetoken/_index.nb.md
🧠 Learnings (3)
📓 Common learnings
Learnt from: lvbachmann
Repo: Altinn/altinn-studio-docs PR: 2477
File: content/authorization/migration/servicemigrationplan/_index.nb.md:4-4
Timestamp: 2025-10-27T07:48:11.643Z
Learning: In content/authorization/migration/servicemigrationplan/_index.nb.md (Norwegian Bokmål), the use of "Altinn II" in the description and "Altinn 2" in the document body is intentional and reflects actual naming conventions. This terminology difference should not be flagged as an inconsistency.
📚 Learning: 2025-10-27T07:48:11.643Z
Learnt from: lvbachmann
Repo: Altinn/altinn-studio-docs PR: 2477
File: content/authorization/migration/servicemigrationplan/_index.nb.md:4-4
Timestamp: 2025-10-27T07:48:11.643Z
Learning: In content/authorization/migration/servicemigrationplan/_index.nb.md (Norwegian Bokmål), the use of "Altinn II" in the description and "Altinn 2" in the document body is intentional and reflects actual naming conventions. This terminology difference should not be flagged as an inconsistency.
Applied to files:
content/authorization/guides/system-vendor/system-user/usetoken/_index.en.mdcontent/authorization/guides/system-vendor/system-user/usetoken/_index.nb.md
📚 Learning: 2025-07-11T09:46:22.736Z
Learnt from: SandGrainOne
Repo: Altinn/altinn-studio-docs PR: 2262
File: static/swagger/altinn-platform-profile-v1.json:202-296
Timestamp: 2025-07-11T09:46:22.736Z
Learning: The file static/swagger/altinn-platform-profile-v1.json is mostly autogenerated and manually added to documentation. Any issues with this OpenAPI specification file need to be fixed in the source code that generates it, not directly in the file itself.
Applied to files:
content/authorization/guides/system-vendor/system-user/usetoken/_index.nb.md
🪛 GitHub Actions: Hugo Verifications
content/authorization/guides/system-vendor/system-user/usetoken/_index.en.md
[error] 165-165: Hyperlink: bad anchor '/en/authorization/guides/resource-owner/system-user#authorisation-of-system-user' referenced at line 165.
🪛 GitHub Check: Build and Check links
content/authorization/guides/system-vendor/system-user/usetoken/_index.en.md
[failure] 165-165:
bad anchors:
en/authorization/guides/resource-owner/system-user#authorisation-of-system-user
🪛 Gitleaks (8.29.1)
content/authorization/guides/system-vendor/system-user/usetoken/_index.en.md
[high] 127-127: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
content/authorization/guides/system-vendor/system-user/usetoken/_index.nb.md
[high] 127-127: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
🪛 LanguageTool
content/authorization/guides/system-vendor/system-user/usetoken/_index.en.md
[style] ~32-~32: Since ownership is already implied, this phrasing may be redundant.
Context: ...cating party) | Service owner consuming its own API | | agent | The system vendor o...
(PRP_OWN)
[style] ~43-~43: Redundant conjunctions can lead to confusion; consider removing a conjunction here.
Context: ...the line-of-business system (production and/or test) with valid key material. - A syst...
(AND_OR)
[style] ~58-~58: Since ownership is already implied, this phrasing may be redundant.
Context: ...r’s organisation (agent scenario) or to your own organisation (own scenario). The aud ...
(PRP_OWN)
[uncategorized] ~154-~154: Do not mix variants of the same word (‘authorisation’ and ‘authorization’) within a single text.
Context: ...e customer. Supply this value to Altinn Authorisation (PDP). | | `authorization_details[].sys...
(EN_WORD_COHERENCY)
[uncategorized] ~161-~161: Do not mix variants of the same word (‘authorisation’ and ‘authorization’) within a single text.
Context: ... token when calling Altinn APIs. Altinn Authorisation (PDP) decides whether the system user m...
(EN_WORD_COHERENCY)
🪛 markdownlint-cli2 (0.18.1)
content/authorization/guides/system-vendor/system-user/usetoken/_index.en.md
91-91: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Analyze (javascript-typescript)
🔇 Additional comments (8)
content/authorization/guides/system-vendor/system-user/usetoken/_index.en.md (2)
1-172: Overall documentation quality is strong.The guide is well-structured with clear sections, realistic examples, and practical guidance. The distinction between agent and own system-user types is explained effectively. The main issues to address are the broken anchor link and code block language specification.
154-154: No issue found—the spelling difference is intentional and correct.The document appropriately distinguishes between:
- API field names (
authorization_details): American spelling, which reflects the actual Maskinporten API contract- Product/service name (
Altinn Authorisation (PDP)): British spelling, which is the official Altinn component nameThis is not mixing variants carelessly; it's correctly using different spellings for different purposes (technical identifiers vs. official product names). The rarity of "Altinn Authorisation" in the repository (only 2 instances, both in this file) confirms it is Altinn's intentional naming convention. No change needed.
content/authorization/guides/system-vendor/system-user/usetoken/_index.nb.md (6)
165-165: Verify the Norwegian anchor link exists.Ensure the target page
/nb/authorization/guides/resource-owner/system-user/has the section heading "Autorisasjon av systembruker" with the matching anchor#autorisasjon-av-systembruker. Since the English version has a reported issue, confirm this Norwegian link is working.
43-46: Prerequisites section is clear and complete.The Norwegian prerequisites are well-articulated and match the English version appropriately.
62-111: Examples section is well-structured and clear.The JWT payload, form-data, and curl examples are practical and clearly explained. Norwegian terminology and explanations appropriately frame the technical examples.
152-157: Response interpretation table is clear and informative.The Norwegian terminology and descriptions appropriately convey the technical information. The table structure and content match the English version well.
159-172: PDP usage and common pitfalls sections are well-written.The Norwegian terminology is consistent, imperative instructions are appropriately formal, and the guidance is clear and actionable. Content matches the English version effectively.
1-172: Overall: High-quality Norwegian documentation.The Norwegian version mirrors the English guide effectively, with appropriate translation of explanations while preserving technical terminology. Grammar, spelling, and phrasing are correct throughout. The structure, examples, and guidance are well-adapted for Norwegian-speaking developers.
| ```http | ||
| #### Example: HTTP request | ||
|
|
||
| ``` |
There was a problem hiding this comment.
Add language specification to code block.
The HTTP request code block is missing the language identifier. This should be http or left blank if not supported, but Hugo code highlighting requires explicit declaration.
Apply this diff:
#### Example: HTTP request
-```
+```http
POST https://test.maskinporten.no/token
Content-Type: application/x-www-form-urlencoded🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
91-91: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In content/authorization/guides/system-vendor/system-user/usetoken/_index.en.md
around line 91, the HTTP request code block lacks a language specifier; update
the opening fence from ``` to ```http and ensure the POST request and
Content-Type lines remain inside that fenced block so Hugo applies HTTP
highlighting.
content/authorization/guides/system-vendor/system-user/usetoken/_index.en.md
Outdated
Show resolved
Hide resolved
| ```http | ||
| #### Eksempel: HTTP request | ||
|
|
||
| ``` |
There was a problem hiding this comment.
Add language specification to code block.
Like the English version, the HTTP request code block needs a language identifier for proper Hugo rendering.
Apply this diff:
#### Eksempel: HTTP request
-```
+```http
POST https://test.maskinporten.no/token
Content-Type: application/x-www-form-urlencoded🤖 Prompt for AI Agents
In content/authorization/guides/system-vendor/system-user/usetoken/_index.nb.md
around line 91, the HTTP request code block lacks a language identifier causing
Hugo to render it without syntax highlighting; update the block to include the
language specifier by replacing the opening fence with ```http so the block
becomes a fenced code block labelled as http, and ensure spacing/indentation
matches surrounding content.
There was a problem hiding this comment.
Actionable comments posted: 2
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
content/authorization/guides/system-vendor/system-user/usetoken/_index.en.md(2 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
content/**/*
⚙️ CodeRabbit configuration file
Check for links, markdown formatting, headings, grammar, and spelling in multiple languages (en-US, nb-NO, nn-NO).
Files:
content/authorization/guides/system-vendor/system-user/usetoken/_index.en.md
🧠 Learnings (3)
📓 Common learnings
Learnt from: lvbachmann
Repo: Altinn/altinn-studio-docs PR: 2477
File: content/authorization/migration/servicemigrationplan/_index.nb.md:4-4
Timestamp: 2025-10-27T07:48:11.643Z
Learning: In content/authorization/migration/servicemigrationplan/_index.nb.md (Norwegian Bokmål), the use of "Altinn II" in the description and "Altinn 2" in the document body is intentional and reflects actual naming conventions. This terminology difference should not be flagged as an inconsistency.
Learnt from: SandGrainOne
Repo: Altinn/altinn-studio-docs PR: 2262
File: static/swagger/altinn-platform-profile-v1.json:202-296
Timestamp: 2025-07-11T09:46:22.736Z
Learning: The file static/swagger/altinn-platform-profile-v1.json is mostly autogenerated and manually added to documentation. Any issues with this OpenAPI specification file need to be fixed in the source code that generates it, not directly in the file itself.
📚 Learning: 2025-10-27T07:48:11.643Z
Learnt from: lvbachmann
Repo: Altinn/altinn-studio-docs PR: 2477
File: content/authorization/migration/servicemigrationplan/_index.nb.md:4-4
Timestamp: 2025-10-27T07:48:11.643Z
Learning: In content/authorization/migration/servicemigrationplan/_index.nb.md (Norwegian Bokmål), the use of "Altinn II" in the description and "Altinn 2" in the document body is intentional and reflects actual naming conventions. This terminology difference should not be flagged as an inconsistency.
Applied to files:
content/authorization/guides/system-vendor/system-user/usetoken/_index.en.md
📚 Learning: 2025-07-11T09:46:22.736Z
Learnt from: SandGrainOne
Repo: Altinn/altinn-studio-docs PR: 2262
File: static/swagger/altinn-platform-profile-v1.json:202-296
Timestamp: 2025-07-11T09:46:22.736Z
Learning: The file static/swagger/altinn-platform-profile-v1.json is mostly autogenerated and manually added to documentation. Any issues with this OpenAPI specification file need to be fixed in the source code that generates it, not directly in the file itself.
Applied to files:
content/authorization/guides/system-vendor/system-user/usetoken/_index.en.md
🪛 Gitleaks (8.29.1)
content/authorization/guides/system-vendor/system-user/usetoken/_index.en.md
[high] 127-127: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
🪛 LanguageTool
content/authorization/guides/system-vendor/system-user/usetoken/_index.en.md
[style] ~32-~32: Since ownership is already implied, this phrasing may be redundant.
Context: ...cating party) | Service owner consuming its own API | | agent | The system vendor o...
(PRP_OWN)
[style] ~43-~43: Redundant conjunctions can lead to confusion; consider removing a conjunction here.
Context: ...the line-of-business system (production and/or test) with valid key material. - A syst...
(AND_OR)
[style] ~58-~58: Since ownership is already implied, this phrasing may be redundant.
Context: ...r’s organisation (agent scenario) or to your own organisation (own scenario). The aud ...
(PRP_OWN)
[uncategorized] ~154-~154: Do not mix variants of the same word (‘authorisation’ and ‘authorization’) within a single text.
Context: ...e customer. Supply this value to Altinn Authorisation (PDP). | | `authorization_details[].sys...
(EN_WORD_COHERENCY)
[uncategorized] ~161-~161: Do not mix variants of the same word (‘authorisation’ and ‘authorization’) within a single text.
Context: ... token when calling Altinn APIs. Altinn Authorisation (PDP) decides whether the system user m...
(EN_WORD_COHERENCY)
🪛 markdownlint-cli2 (0.18.1)
content/authorization/guides/system-vendor/system-user/usetoken/_index.en.md
91-91: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Analyze (javascript-typescript)
🔇 Additional comments (1)
content/authorization/guides/system-vendor/system-user/usetoken/_index.en.md (1)
1-172: Overall structure and content approval.The documentation successfully achieves the PR objectives: it distinguishes agent vs. own system-user types, provides detailed Maskinporten request examples with both HTTP and curl variants, includes comprehensive response interpretation, and adds clear pitfalls guidance. The step-by-step flow and tabular comparisons enhance clarity for the target audience (developers and integrators). The mermaid diagram and notice blocks appropriately highlight key concepts.
Note: The prior link issue flagged at line 165 has been correctly resolved with the American English anchor spelling.
| ``` | ||
| POST https://test.maskinporten.no/token | ||
| Content-Type: application/json | ||
| Content-Type: application/x-www-form-urlencoded | ||
| { | ||
| "aud" : "https://maskinporten.no", | ||
| "sub" : "fc9a8287-e7cb-45e5-b90e-123048d32d85", | ||
| "authorization_details" : [ { | ||
| "systemuser_org" : { | ||
| "authority" : "iso6523-actorid-upis", | ||
| "ID" : "0192:123456789" | ||
| }, | ||
| "type" : "urn:altinn:systemuser" | ||
| } ], | ||
| "scope" : "krr:global/kontaktinformasjon.read", | ||
| "iss" : "fc9a8287-e7cb-45e5-b90e-123048d32d85", | ||
| "exp" : 1718124835, | ||
| "iat" : 1718124715, | ||
| "jti" : "89365ecd-772b-4462-a4de-ac36af8ef3e2" | ||
| } | ||
| grant_type=client_credentials& | ||
| scope=krr%3Aglobal%2Fkontaktinformasjon.read& | ||
| client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer& | ||
| client_assertion=<signed-JWT> | ||
| ``` |
There was a problem hiding this comment.
Add language specification to HTTP code block.
The code block at line 91 is missing a language identifier. This violates the markdown linter (MD040) and prevents proper syntax highlighting. Add http as the language specifier.
#### Example: HTTP request
-```
+```http
POST https://test.maskinporten.no/token
Content-Type: application/x-www-form-urlencoded🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
91-91: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In content/authorization/guides/system-vendor/system-user/usetoken/_index.en.md
around lines 91 to 99, the fenced code block is missing a language identifier
which trips MD040; add "http" immediately after the opening backticks so the
block starts with ```http to enable proper linting and syntax highlighting.
| | Field | Description | | ||
| |-------|-------------| | ||
| | `authorization_details[].systemuser_id` | List of system users you can use for the customer. Supply this value to Altinn Authorisation (PDP). | | ||
| | `authorization_details[].systemuser_org.ID` | Organisation that owns the system user. For agent scenarios this is the customer; for own scenarios it matches `consumer.ID`. | | ||
| | `authorization_details[].system_id` | Reference to your system in Altinn. Useful for troubleshooting and verification. | | ||
| | `consumer.ID` | Organisation number of the Maskinporten client (system vendor). Confirm that it matches the expected vendor. | | ||
|
|
There was a problem hiding this comment.
Standardize spelling to American English "Authorization".
Lines 154 and 161 use "Authorisation" (British spelling), which conflicts with the American English "authorization" used elsewhere in the document. For consistency in en-US documentation, change both occurrences to "Authorization".
-| `authorization_details[].systemuser_id` | List of system users you can use for the customer. Supply this value to Altinn Authorisation (PDP). |
+| `authorization_details[].systemuser_id` | List of system users you can use for the customer. Supply this value to Altinn Authorization (PDP). |And at line 161:
-Use the Maskinporten system user token as a Bearer token when calling Altinn APIs. Altinn Authorisation (PDP) decides whether the system user may perform the requested action based on `systemuser_id`, resource and action.
+Use the Maskinporten system user token as a Bearer token when calling Altinn APIs. Altinn Authorization (PDP) decides whether the system user may perform the requested action based on `systemuser_id`, resource and action.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| | Field | Description | | |
| |-------|-------------| | |
| | `authorization_details[].systemuser_id` | List of system users you can use for the customer. Supply this value to Altinn Authorisation (PDP). | | |
| | `authorization_details[].systemuser_org.ID` | Organisation that owns the system user. For agent scenarios this is the customer; for own scenarios it matches `consumer.ID`. | | |
| | `authorization_details[].system_id` | Reference to your system in Altinn. Useful for troubleshooting and verification. | | |
| | `consumer.ID` | Organisation number of the Maskinporten client (system vendor). Confirm that it matches the expected vendor. | | |
| | Field | Description | | |
| |-------|-------------| | |
| | `authorization_details[].systemuser_id` | List of system users you can use for the customer. Supply this value to Altinn Authorization (PDP). | | |
| | `authorization_details[].systemuser_org.ID` | Organisation that owns the system user. For agent scenarios this is the customer; for own scenarios it matches `consumer.ID`. | | |
| | `authorization_details[].system_id` | Reference to your system in Altinn. Useful for troubleshooting and verification. | | |
| | `consumer.ID` | Organisation number of the Maskinporten client (system vendor). Confirm that it matches the expected vendor. | |
🧰 Tools
🪛 LanguageTool
[uncategorized] ~154-~154: Do not mix variants of the same word (‘authorisation’ and ‘authorization’) within a single text.
Context: ...e customer. Supply this value to Altinn Authorisation (PDP). | | `authorization_details[].sys...
(EN_WORD_COHERENCY)
🤖 Prompt for AI Agents
In content/authorization/guides/system-vendor/system-user/usetoken/_index.en.md
around lines 152-161, two occurrences of the British spelling "Authorisation"
should be changed to the American spelling "Authorization" (specifically at
lines 154 and 161); update those words to "Authorization" and scan the
surrounding lines for any other stray "Authorisation" instances to ensure
consistent American English spelling across the section.
1 participant
Summary
Testing
Notes
Closes #1641
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.