Skip to content

Describe the client credentials flow in the Management API specification - #6141

Open
flyrain wants to merge 1 commit into
apache:mainfrom
flyrain:yf/docs-190-management-oauth
Open

flyrain wants to merge 1 commit into
apache:mainfrom
flyrain:yf/docs-190-management-oauth

Conversation

@flyrain

@flyrain flyrain commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

The Management API specification describes client credentials but declares an implicit OAuth flow and an authorization URL that the built-in service does not serve. The specification now declares clientCredentials with tokenUrl: /api/catalog/v1/oauth/tokens. The unreleased Management API reference renders this file directly, and client generators can consume the corrected flow.

Parsed the specification, checked the flow and token endpoint against the authentication example, and verified that the unreleased reference renders this schema.

Verification build

Checklist

  • The change concerns public documentation.
  • The reason for the correction is described above.
  • The verification is described above.
  • No complex implementation logic needs comments.
  • This correction to documented behavior needs no changelog entry.
  • The change updates the unreleased documentation or its source.

AI assistance was used to prepare and check this change.

@flyrain
flyrain changed the base branch from versioned-docs to main November 19, 2026 03:23
@flyrain
flyrain force-pushed the yf/docs-190-management-oauth branch from 54b866a to a65b4b0 Compare November 19, 2026 03:24
@flyrain flyrain changed the title Document the OAuth flow for 1.9.0 Management API clients Describe the client credentials flow in the Management API specification Nov 19, 2026
implicit:
authorizationUrl: "{scheme}://{host}/api/v1/oauth/tokens"
clientCredentials:
tokenUrl: /api/catalog/v1/oauth/tokens

@flyrain flyrain Nov 19, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the correct token url, check the regtest example here,

if ! output=$(curl -X POST -H "Polaris-Realm: POLARIS" "http://${POLARIS_HOST:-localhost}:8181/api/catalog/v1/oauth/tokens" \

@flyrain
flyrain marked this pull request as ready for review November 19, 2026 04:48
Copilot AI balanced review requested due to automatic review settings November 19, 2026 04:48

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The OAuth specification omits supported role scopes and does not clarify that externally authenticated realms must use their identity provider’s token URL.

2 open issues
What changed in this PR

This PR updates the Management API’s OpenAPI authentication declaration to describe the built-in client-credentials flow. The specification supplies the unreleased API reference and can be consumed by client generators.

Changes:

  • Replaces the implicit OAuth flow with clientCredentials.
  • Replaces authorizationUrl with tokenUrl: /api/catalog/v1/oauth/tokens.
File Description
spec/​polaris-management-service.yml Updates the OAuth flow type and token endpoint declaration.

Review effort: Balanced

@@ -814,8 +814,8 @@ components:
type: oauth2
description: Uses OAuth 2 with client credentials flow
authorizationUrl: "{scheme}://{host}/api/v1/oauth/tokens"
clientCredentials:
tokenUrl: /api/catalog/v1/oauth/tokens
scopes: {}

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants