Restructure solution layout by module
This commit is contained in:
master
16
src/Api/StellaOps.Api.OpenApi/AGENTS.md
Normal file
16
src/Api/StellaOps.Api.OpenApi/AGENTS.md
Normal file
@@ -0,0 +1,16 @@
|
||||
# StellaOps API Contracts Guild Charter
|
||||
|
||||
## Mission
|
||||
Maintain OpenAPI 3.1 specifications for every StellaOps service, compose the aggregate spec, and ensure API contract consistency across releases.
|
||||
|
||||
## Scope
|
||||
- Author and review per-service OAS documents in `src/Api/StellaOps.Api.OpenApi/<service>/openapi.yaml`.
|
||||
- Operate the aggregate composer producing `src/Api/StellaOps.Api.OpenApi/stella.yaml`.
|
||||
- Provide shared components, schema libraries, and example catalogs.
|
||||
- Coordinate with service guilds on contract changes, examples, and versioning.
|
||||
- Own CI validation, linting, and compatibility diff tooling for OAS artifacts.
|
||||
|
||||
## Definition of Done
|
||||
- All public endpoints represented in OAS with validated request/response examples.
|
||||
- Aggregate spec builds deterministically and passes lint + compatibility checks.
|
||||
- Change logs generated with every release and linked to developer portal updates.
|
||||
19
src/Api/StellaOps.Api.OpenApi/TASKS.md
Normal file
19
src/Api/StellaOps.Api.OpenApi/TASKS.md
Normal file
@@ -0,0 +1,19 @@
|
||||
# API OpenAPI Task Board — Epic 17: SDKs & OpenAPI Docs
|
||||
|
||||
## Sprint 61 – Spec Foundations
|
||||
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|
||||
|----|--------|----------|------------|-------------|---------------|
|
||||
| OAS-61-001 | TODO | API Contracts Guild | — | Scaffold per-service OpenAPI 3.1 files with shared components, info blocks, and initial path stubs. | All services have baseline `openapi.yaml`; shared components library established; lint passes. |
|
||||
| OAS-61-002 | TODO | API Contracts Guild, DevOps Guild | OAS-61-001 | Implement aggregate composer (`stella.yaml`) resolving `$ref`s and merging shared components; wire into CI. | Aggregate spec builds deterministically; CI artifact published; documentation updated. |
|
||||
|
||||
## Sprint 62 – Examples & Error Envelope
|
||||
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|
||||
|----|--------|----------|------------|-------------|---------------|
|
||||
| OAS-62-001 | TODO | API Contracts Guild, Service Guilds | OAS-61-001 | Populate request/response examples for top 50 endpoints, including standard error envelope. | Examples validated via CI; error envelope consistent across services. |
|
||||
| OAS-62-002 | TODO | API Contracts Guild | OAS-61-002 | Add custom lint rules enforcing pagination, idempotency headers, naming conventions, and example coverage. | Lint job fails on violations; documentation for rules published. |
|
||||
|
||||
## Sprint 63 – Compatibility & Discovery
|
||||
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|
||||
|----|--------|----------|------------|-------------|---------------|
|
||||
| OAS-63-001 | TODO | API Contracts Guild | OAS-61-002 | Implement compatibility diff tooling comparing previous release specs; classify breaking vs additive changes. | Diff tool integrated in CI; PRs flagged on breaking changes. |
|
||||
| OAS-63-002 | TODO | API Contracts Guild, Gateway Guild | OAS-62-002 | Add `/.well-known/openapi` discovery endpoint schema metadata (extensions, version info). | Discovery endpoints defined in spec; linked to implementation tasks. |
|
||||
689
src/Api/StellaOps.Api.OpenApi/authority/openapi.yaml
Normal file
689
src/Api/StellaOps.Api.OpenApi/authority/openapi.yaml
Normal file
@@ -0,0 +1,689 @@
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: StellaOps Authority Authentication API
|
||||
summary: Token issuance, introspection, revocation, and key discovery endpoints exposed by the Authority service.
|
||||
description: |
|
||||
The Authority service issues OAuth 2.1 access tokens for StellaOps components, enforcing tenant and scope
|
||||
restrictions configured per client. This specification describes the authentication surface only; domain APIs
|
||||
are documented by their owning services.
|
||||
version: 0.1.0
|
||||
jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema
|
||||
servers:
|
||||
- url: https://authority.stellaops.local
|
||||
description: Example Authority deployment
|
||||
tags:
|
||||
- name: Authentication
|
||||
description: OAuth 2.1 token exchange, introspection, and revocation flows.
|
||||
- name: Keys
|
||||
description: JSON Web Key Set discovery.
|
||||
components:
|
||||
securitySchemes:
|
||||
ClientSecretBasic:
|
||||
type: http
|
||||
scheme: basic
|
||||
description: HTTP Basic authentication with `client_id` and `client_secret`.
|
||||
OAuthPassword:
|
||||
type: oauth2
|
||||
description: Resource owner password exchange for Authority-managed identities.
|
||||
flows:
|
||||
password:
|
||||
tokenUrl: /token
|
||||
refreshUrl: /token
|
||||
scopes:
|
||||
advisory:ingest: Submit advisory ingestion payloads.
|
||||
advisory:read: Read advisory ingestion data.
|
||||
aoc:verify: Execute Aggregation-Only Contract verification workflows.
|
||||
authority.audit.read: Read Authority audit logs.
|
||||
authority.clients.manage: Manage Authority client registrations.
|
||||
authority.users.manage: Manage Authority users.
|
||||
authority:tenants.read: Read the Authority tenant catalog.
|
||||
concelier.jobs.trigger: Trigger Concelier aggregation jobs.
|
||||
concelier.merge: Manage Concelier merge operations.
|
||||
effective:write: Write effective findings (Policy Engine service identity only).
|
||||
email: Access email claim data.
|
||||
exceptions:approve: Approve exception workflows.
|
||||
findings:read: Read effective findings emitted by Policy Engine.
|
||||
graph:export: Export graph artefacts.
|
||||
graph:read: Read graph explorer data.
|
||||
graph:simulate: Run graph what-if simulations.
|
||||
graph:write: Enqueue or mutate graph build jobs.
|
||||
offline_access: Request refresh tokens for offline access.
|
||||
openid: Request OpenID Connect identity tokens.
|
||||
orch:operate: Execute privileged Orchestrator control actions.
|
||||
orch:read: Read Orchestrator job state.
|
||||
policy:author: Author Policy Studio drafts and workspaces.
|
||||
policy:activate: Activate policy revisions.
|
||||
policy:approve: Approve or reject policy drafts.
|
||||
policy:audit: Inspect Policy Studio audit history.
|
||||
policy:edit: Edit policy definitions.
|
||||
policy:operate: Operate Policy Studio promotions and runs.
|
||||
policy:read: Read policy definitions and metadata.
|
||||
policy:run: Trigger policy executions.
|
||||
policy:submit: Submit policy drafts for review.
|
||||
policy:review: Review Policy Studio drafts and leave feedback.
|
||||
policy:simulate: Execute Policy Studio simulations.
|
||||
policy:write: Create or update policy drafts.
|
||||
profile: Access profile claim data.
|
||||
signals:admin: Administer Signals ingestion and routing settings.
|
||||
signals:read: Read Signals events and state.
|
||||
signals:write: Publish Signals events or mutate state.
|
||||
stellaops.bypass: Bypass trust boundary protections (restricted identities only).
|
||||
ui.read: Read Console UX resources.
|
||||
vex:ingest: Submit VEX ingestion payloads.
|
||||
vex:read: Read VEX ingestion data.
|
||||
vuln:read: Read vulnerability permalinks and overlays.
|
||||
authorizationCode:
|
||||
authorizationUrl: /authorize
|
||||
tokenUrl: /token
|
||||
refreshUrl: /token
|
||||
scopes:
|
||||
advisory:ingest: Submit advisory ingestion payloads.
|
||||
advisory:read: Read advisory ingestion data.
|
||||
aoc:verify: Execute Aggregation-Only Contract verification workflows.
|
||||
authority.audit.read: Read Authority audit logs.
|
||||
authority.clients.manage: Manage Authority client registrations.
|
||||
authority.users.manage: Manage Authority users.
|
||||
authority:tenants.read: Read the Authority tenant catalog.
|
||||
concelier.jobs.trigger: Trigger Concelier aggregation jobs.
|
||||
concelier.merge: Manage Concelier merge operations.
|
||||
effective:write: Write effective findings (Policy Engine service identity only).
|
||||
email: Access email claim data.
|
||||
exceptions:approve: Approve exception workflows.
|
||||
findings:read: Read effective findings emitted by Policy Engine.
|
||||
graph:export: Export graph artefacts.
|
||||
graph:read: Read graph explorer data.
|
||||
graph:simulate: Run graph what-if simulations.
|
||||
graph:write: Enqueue or mutate graph build jobs.
|
||||
offline_access: Request refresh tokens for offline access.
|
||||
openid: Request OpenID Connect identity tokens.
|
||||
orch:operate: Execute privileged Orchestrator control actions.
|
||||
orch:read: Read Orchestrator job state.
|
||||
policy:author: Author Policy Studio drafts and workspaces.
|
||||
policy:activate: Activate policy revisions.
|
||||
policy:approve: Approve or reject policy drafts.
|
||||
policy:audit: Inspect Policy Studio audit history.
|
||||
policy:edit: Edit policy definitions.
|
||||
policy:operate: Operate Policy Studio promotions and runs.
|
||||
policy:read: Read policy definitions and metadata.
|
||||
policy:run: Trigger policy executions.
|
||||
policy:submit: Submit policy drafts for review.
|
||||
policy:review: Review Policy Studio drafts and leave feedback.
|
||||
policy:simulate: Execute Policy Studio simulations.
|
||||
policy:write: Create or update policy drafts.
|
||||
profile: Access profile claim data.
|
||||
signals:admin: Administer Signals ingestion and routing settings.
|
||||
signals:read: Read Signals events and state.
|
||||
signals:write: Publish Signals events or mutate state.
|
||||
stellaops.bypass: Bypass trust boundary protections (restricted identities only).
|
||||
ui.read: Read Console UX resources.
|
||||
vex:ingest: Submit VEX ingestion payloads.
|
||||
vex:read: Read VEX ingestion data.
|
||||
vuln:read: Read vulnerability permalinks and overlays.
|
||||
OAuthClientCredentials:
|
||||
type: oauth2
|
||||
description: Client credential exchange for machine-to-machine identities.
|
||||
flows:
|
||||
clientCredentials:
|
||||
tokenUrl: /token
|
||||
scopes:
|
||||
advisory:ingest: Submit advisory ingestion payloads.
|
||||
advisory:read: Read advisory ingestion data.
|
||||
aoc:verify: Execute Aggregation-Only Contract verification workflows.
|
||||
authority.audit.read: Read Authority audit logs.
|
||||
authority.clients.manage: Manage Authority client registrations.
|
||||
authority.users.manage: Manage Authority users.
|
||||
authority:tenants.read: Read the Authority tenant catalog.
|
||||
concelier.jobs.trigger: Trigger Concelier aggregation jobs.
|
||||
concelier.merge: Manage Concelier merge operations.
|
||||
effective:write: Write effective findings (Policy Engine service identity only).
|
||||
email: Access email claim data.
|
||||
exceptions:approve: Approve exception workflows.
|
||||
findings:read: Read effective findings emitted by Policy Engine.
|
||||
graph:export: Export graph artefacts.
|
||||
graph:read: Read graph explorer data.
|
||||
graph:simulate: Run graph what-if simulations.
|
||||
graph:write: Enqueue or mutate graph build jobs.
|
||||
offline_access: Request refresh tokens for offline access.
|
||||
openid: Request OpenID Connect identity tokens.
|
||||
orch:operate: Execute privileged Orchestrator control actions.
|
||||
orch:read: Read Orchestrator job state.
|
||||
policy:author: Author Policy Studio drafts and workspaces.
|
||||
policy:activate: Activate policy revisions.
|
||||
policy:approve: Approve or reject policy drafts.
|
||||
policy:audit: Inspect Policy Studio audit history.
|
||||
policy:edit: Edit policy definitions.
|
||||
policy:operate: Operate Policy Studio promotions and runs.
|
||||
policy:read: Read policy definitions and metadata.
|
||||
policy:run: Trigger policy executions.
|
||||
policy:submit: Submit policy drafts for review.
|
||||
policy:review: Review Policy Studio drafts and leave feedback.
|
||||
policy:simulate: Execute Policy Studio simulations.
|
||||
policy:write: Create or update policy drafts.
|
||||
profile: Access profile claim data.
|
||||
signals:admin: Administer Signals ingestion and routing settings.
|
||||
signals:read: Read Signals events and state.
|
||||
signals:write: Publish Signals events or mutate state.
|
||||
stellaops.bypass: Bypass trust boundary protections (restricted identities only).
|
||||
ui.read: Read Console UX resources.
|
||||
vex:ingest: Submit VEX ingestion payloads.
|
||||
vex:read: Read VEX ingestion data.
|
||||
vuln:read: Read vulnerability permalinks and overlays.
|
||||
schemas:
|
||||
TokenResponse:
|
||||
type: object
|
||||
description: OAuth 2.1 bearer token response.
|
||||
properties:
|
||||
access_token:
|
||||
type: string
|
||||
description: Access token encoded as JWT.
|
||||
token_type:
|
||||
type: string
|
||||
description: Token type indicator. Always `Bearer`.
|
||||
expires_in:
|
||||
type: integer
|
||||
description: Lifetime of the access token, in seconds.
|
||||
minimum: 1
|
||||
refresh_token:
|
||||
type: string
|
||||
description: Refresh token issued when the grant allows offline access.
|
||||
scope:
|
||||
type: string
|
||||
description: Space-delimited scopes granted in the response.
|
||||
id_token:
|
||||
type: string
|
||||
description: ID token issued for authorization-code flows.
|
||||
required:
|
||||
- access_token
|
||||
- token_type
|
||||
- expires_in
|
||||
OAuthErrorResponse:
|
||||
type: object
|
||||
description: RFC 6749 compliant error envelope.
|
||||
properties:
|
||||
error:
|
||||
type: string
|
||||
description: Machine-readable error code.
|
||||
error_description:
|
||||
type: string
|
||||
description: Human-readable error description.
|
||||
error_uri:
|
||||
type: string
|
||||
format: uri
|
||||
description: Link to documentation about the error.
|
||||
required:
|
||||
- error
|
||||
PasswordGrantRequest:
|
||||
type: object
|
||||
required:
|
||||
- grant_type
|
||||
- client_id
|
||||
- username
|
||||
- password
|
||||
properties:
|
||||
grant_type:
|
||||
type: string
|
||||
const: password
|
||||
client_id:
|
||||
type: string
|
||||
description: Registered client identifier. May also be supplied via HTTP Basic auth.
|
||||
client_secret:
|
||||
type: string
|
||||
description: Client secret. Required for confidential clients when not using HTTP Basic auth.
|
||||
scope:
|
||||
type: string
|
||||
description: Space-delimited scopes being requested.
|
||||
username:
|
||||
type: string
|
||||
description: Resource owner username.
|
||||
password:
|
||||
type: string
|
||||
description: Resource owner password.
|
||||
authority_provider:
|
||||
type: string
|
||||
description: Optional identity provider hint. Required when multiple password-capable providers are registered.
|
||||
description: Form-encoded payload for password grant exchange.
|
||||
ClientCredentialsGrantRequest:
|
||||
type: object
|
||||
required:
|
||||
- grant_type
|
||||
- client_id
|
||||
properties:
|
||||
grant_type:
|
||||
type: string
|
||||
const: client_credentials
|
||||
client_id:
|
||||
type: string
|
||||
description: Registered client identifier. May also be supplied via HTTP Basic auth.
|
||||
client_secret:
|
||||
type: string
|
||||
description: Client secret. Required for confidential clients when not using HTTP Basic auth.
|
||||
scope:
|
||||
type: string
|
||||
description: Space-delimited scopes being requested.
|
||||
authority_provider:
|
||||
type: string
|
||||
description: Optional identity provider hint for plugin-backed clients.
|
||||
operator_reason:
|
||||
type: string
|
||||
description: Required when requesting `orch:operate`; explains the operator action.
|
||||
maxLength: 256
|
||||
operator_ticket:
|
||||
type: string
|
||||
description: Required when requesting `orch:operate`; tracks the external change ticket or incident.
|
||||
maxLength: 128
|
||||
description: Form-encoded payload for client credentials exchange.
|
||||
RefreshTokenGrantRequest:
|
||||
type: object
|
||||
required:
|
||||
- grant_type
|
||||
- refresh_token
|
||||
properties:
|
||||
grant_type:
|
||||
type: string
|
||||
const: refresh_token
|
||||
client_id:
|
||||
type: string
|
||||
description: Registered client identifier. May also be supplied via HTTP Basic auth.
|
||||
client_secret:
|
||||
type: string
|
||||
description: Client secret. Required for confidential clients when not using HTTP Basic auth.
|
||||
refresh_token:
|
||||
type: string
|
||||
description: Previously issued refresh token.
|
||||
scope:
|
||||
type: string
|
||||
description: Optional scope list to narrow the requested access.
|
||||
description: Form-encoded payload for refresh token exchange.
|
||||
RevocationRequest:
|
||||
type: object
|
||||
required:
|
||||
- token
|
||||
properties:
|
||||
token:
|
||||
type: string
|
||||
description: Token value or token identifier to revoke.
|
||||
token_type_hint:
|
||||
type: string
|
||||
description: Optional token type hint (`access_token` or `refresh_token`).
|
||||
description: Form-encoded payload for token revocation.
|
||||
IntrospectionRequest:
|
||||
type: object
|
||||
required:
|
||||
- token
|
||||
properties:
|
||||
token:
|
||||
type: string
|
||||
description: Token value whose state should be introspected.
|
||||
token_type_hint:
|
||||
type: string
|
||||
description: Optional token type hint (`access_token` or `refresh_token`).
|
||||
description: Form-encoded payload for token introspection.
|
||||
IntrospectionResponse:
|
||||
type: object
|
||||
description: Active token descriptor compliant with RFC 7662.
|
||||
properties:
|
||||
active:
|
||||
type: boolean
|
||||
description: Indicates whether the token is currently active.
|
||||
scope:
|
||||
type: string
|
||||
description: Space-delimited list of scopes granted to the token.
|
||||
client_id:
|
||||
type: string
|
||||
description: Client identifier associated with the token.
|
||||
sub:
|
||||
type: string
|
||||
description: Subject identifier when the token represents an end-user.
|
||||
username:
|
||||
type: string
|
||||
description: Preferred username associated with the subject.
|
||||
token_type:
|
||||
type: string
|
||||
description: Type of the token (e.g., `Bearer`).
|
||||
exp:
|
||||
type: integer
|
||||
description: Expiration timestamp (seconds since UNIX epoch).
|
||||
iat:
|
||||
type: integer
|
||||
description: Issued-at timestamp (seconds since UNIX epoch).
|
||||
nbf:
|
||||
type: integer
|
||||
description: Not-before timestamp (seconds since UNIX epoch).
|
||||
aud:
|
||||
type: array
|
||||
description: Audience values associated with the token.
|
||||
items:
|
||||
type: string
|
||||
iss:
|
||||
type: string
|
||||
description: Issuer identifier.
|
||||
jti:
|
||||
type: string
|
||||
description: JWT identifier corresponding to the token.
|
||||
tenant:
|
||||
type: string
|
||||
description: Tenant associated with the token, when assigned.
|
||||
confirmation:
|
||||
type: object
|
||||
description: Sender-constrained confirmation data (e.g., mTLS thumbprint, DPoP JWK thumbprint).
|
||||
required:
|
||||
- active
|
||||
JwksDocument:
|
||||
type: object
|
||||
description: JSON Web Key Set published by the Authority.
|
||||
properties:
|
||||
keys:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/Jwk'
|
||||
required:
|
||||
- keys
|
||||
Jwk:
|
||||
type: object
|
||||
description: Public key material for token signature validation.
|
||||
properties:
|
||||
kid:
|
||||
type: string
|
||||
description: Key identifier.
|
||||
kty:
|
||||
type: string
|
||||
description: Key type (e.g., `EC`, `RSA`).
|
||||
use:
|
||||
type: string
|
||||
description: Intended key use (`sig`).
|
||||
alg:
|
||||
type: string
|
||||
description: Signing algorithm (e.g., `ES384`).
|
||||
crv:
|
||||
type: string
|
||||
description: Elliptic curve identifier when applicable.
|
||||
x:
|
||||
type: string
|
||||
description: X coordinate for EC keys.
|
||||
y:
|
||||
type: string
|
||||
description: Y coordinate for EC keys.
|
||||
status:
|
||||
type: string
|
||||
description: Operational status metadata for the key (e.g., `active`, `retiring`).
|
||||
paths:
|
||||
/token:
|
||||
post:
|
||||
tags:
|
||||
- Authentication
|
||||
summary: Exchange credentials for tokens
|
||||
description: |
|
||||
Issues OAuth 2.1 bearer tokens for StellaOps clients. Supports password, client credentials,
|
||||
authorization-code, device, and refresh token grants. Confidential clients must authenticate using
|
||||
HTTP Basic auth or `client_secret` form fields.
|
||||
security:
|
||||
- ClientSecretBasic: []
|
||||
- {}
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/x-www-form-urlencoded:
|
||||
schema:
|
||||
oneOf:
|
||||
- $ref: '#/components/schemas/PasswordGrantRequest'
|
||||
- $ref: '#/components/schemas/ClientCredentialsGrantRequest'
|
||||
- $ref: '#/components/schemas/RefreshTokenGrantRequest'
|
||||
encoding:
|
||||
authority_provider:
|
||||
style: form
|
||||
explode: false
|
||||
examples:
|
||||
passwordGrant:
|
||||
summary: Password grant for tenant-scoped ingestion bot
|
||||
value:
|
||||
grant_type: password
|
||||
client_id: ingest-cli
|
||||
client_secret: s3cr3t
|
||||
username: ingest-bot
|
||||
password: pa55w0rd!
|
||||
scope: advisory:ingest vex:ingest
|
||||
authority_provider: primary-directory
|
||||
authorizationCode:
|
||||
summary: Authorization code exchange for Console UI session
|
||||
value:
|
||||
grant_type: authorization_code
|
||||
client_id: console-ui
|
||||
code: 2Lba1WtwPLfZ2b0Z9uPrsQ
|
||||
redirect_uri: https://console.stellaops.local/auth/callback
|
||||
code_verifier: g3ZnL91QJ6i4zO_86oI4CDnZ7gS0bSeK
|
||||
clientCredentials:
|
||||
summary: Client credentials exchange for Policy Engine
|
||||
value:
|
||||
grant_type: client_credentials
|
||||
client_id: policy-engine
|
||||
client_secret: 9c39f602-2f2b-4f29
|
||||
scope: effective:write findings:read
|
||||
operator_reason: Deploying policy change 1234
|
||||
operator_ticket: CHG-004211
|
||||
refreshToken:
|
||||
summary: Refresh token rotation for console session
|
||||
value:
|
||||
grant_type: refresh_token
|
||||
client_id: console-ui
|
||||
refresh_token: 0.rg9pVlsGzXE8Q
|
||||
responses:
|
||||
'200':
|
||||
description: Token exchange succeeded.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/TokenResponse'
|
||||
examples:
|
||||
passwordGrant:
|
||||
summary: Password grant success response
|
||||
value:
|
||||
access_token: eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCJ9...
|
||||
token_type: Bearer
|
||||
expires_in: 3600
|
||||
refresh_token: OxGdVtZJ-mk49cFd38uRUw
|
||||
scope: advisory:ingest vex:ingest
|
||||
clientCredentials:
|
||||
summary: Client credentials success response
|
||||
value:
|
||||
access_token: eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCJ9...
|
||||
token_type: Bearer
|
||||
expires_in: 900
|
||||
scope: effective:write findings:read
|
||||
authorizationCode:
|
||||
summary: Authorization code success response
|
||||
value:
|
||||
access_token: eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCJ9...
|
||||
token_type: Bearer
|
||||
expires_in: 900
|
||||
refresh_token: VxKpc9Vj9QjYV6gLrhQHTw
|
||||
scope: ui.read authority:tenants.read
|
||||
id_token: eyJhbGciOiJFUzM4NCIsImtpZCI6ImNvbnNvbGUifQ...
|
||||
'400':
|
||||
description: Malformed request, unsupported grant type, or invalid credentials.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/OAuthErrorResponse'
|
||||
examples:
|
||||
invalidProvider:
|
||||
summary: Unknown identity provider hint
|
||||
value:
|
||||
error: invalid_request
|
||||
error_description: "Unknown identity provider 'legacy-directory'."
|
||||
invalidScope:
|
||||
summary: Scope not permitted for client
|
||||
value:
|
||||
error: invalid_scope
|
||||
error_description: Scope 'effective:write' is not permitted for this client.
|
||||
'401':
|
||||
description: Client authentication failed.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/OAuthErrorResponse'
|
||||
examples:
|
||||
badClientSecret:
|
||||
summary: Invalid client secret
|
||||
value:
|
||||
error: invalid_client
|
||||
error_description: Client authentication failed.
|
||||
/revoke:
|
||||
post:
|
||||
tags:
|
||||
- Authentication
|
||||
summary: Revoke an access or refresh token
|
||||
security:
|
||||
- ClientSecretBasic: []
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/x-www-form-urlencoded:
|
||||
schema:
|
||||
$ref: '#/components/schemas/RevocationRequest'
|
||||
examples:
|
||||
revokeRefreshToken:
|
||||
summary: Revoke refresh token after logout
|
||||
value:
|
||||
token: 0.rg9pVlsGzXE8Q
|
||||
token_type_hint: refresh_token
|
||||
responses:
|
||||
'200':
|
||||
description: Token revoked or already invalid. The response body is intentionally blank.
|
||||
'400':
|
||||
description: Malformed request.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/OAuthErrorResponse'
|
||||
examples:
|
||||
missingToken:
|
||||
summary: Token parameter omitted
|
||||
value:
|
||||
error: invalid_request
|
||||
error_description: The revocation request is missing the token parameter.
|
||||
'401':
|
||||
description: Client authentication failed.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/OAuthErrorResponse'
|
||||
examples:
|
||||
badClientSecret:
|
||||
summary: Invalid client credentials
|
||||
value:
|
||||
error: invalid_client
|
||||
error_description: Client authentication failed.
|
||||
/introspect:
|
||||
post:
|
||||
tags:
|
||||
- Authentication
|
||||
summary: Introspect token state
|
||||
description: Returns the active status and claims for a given token. Requires a privileged client.
|
||||
security:
|
||||
- ClientSecretBasic: []
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/x-www-form-urlencoded:
|
||||
schema:
|
||||
$ref: '#/components/schemas/IntrospectionRequest'
|
||||
examples:
|
||||
introspectToken:
|
||||
summary: Validate an access token issued to Orchestrator
|
||||
value:
|
||||
token: eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCJ9...
|
||||
token_type_hint: access_token
|
||||
responses:
|
||||
'200':
|
||||
description: Token state evaluated.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/IntrospectionResponse'
|
||||
examples:
|
||||
activeToken:
|
||||
summary: Active token response
|
||||
value:
|
||||
active: true
|
||||
scope: orch:operate orch:read
|
||||
client_id: orch-control
|
||||
sub: operator-7f12
|
||||
username: ops.engineer@tenant.example
|
||||
token_type: Bearer
|
||||
exp: 1761628800
|
||||
iat: 1761625200
|
||||
nbf: 1761625200
|
||||
iss: https://authority.stellaops.local
|
||||
aud:
|
||||
- https://orch.stellaops.local
|
||||
jti: 01J8KYRAMG7FWBPRRV5XG20T7S
|
||||
tenant: tenant-alpha
|
||||
confirmation:
|
||||
mtls_thumbprint: 079871b8c9a0f2e6
|
||||
inactiveToken:
|
||||
summary: Revoked token response
|
||||
value:
|
||||
active: false
|
||||
'400':
|
||||
description: Malformed request.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/OAuthErrorResponse'
|
||||
examples:
|
||||
missingToken:
|
||||
summary: Token missing
|
||||
value:
|
||||
error: invalid_request
|
||||
error_description: token parameter is required.
|
||||
'401':
|
||||
description: Client authentication failed or client lacks introspection permission.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/OAuthErrorResponse'
|
||||
examples:
|
||||
unauthorizedClient:
|
||||
summary: Client not allowed to introspect tokens
|
||||
value:
|
||||
error: invalid_client
|
||||
error_description: Client authentication failed.
|
||||
/jwks:
|
||||
get:
|
||||
tags:
|
||||
- Keys
|
||||
summary: Retrieve signing keys
|
||||
description: Returns the JSON Web Key Set used to validate Authority-issued tokens.
|
||||
responses:
|
||||
'200':
|
||||
description: JWKS document.
|
||||
headers:
|
||||
Cache-Control:
|
||||
schema:
|
||||
type: string
|
||||
description: Standard caching headers apply; keys rotate infrequently.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/JwksDocument'
|
||||
examples:
|
||||
ecKeySet:
|
||||
summary: EC signing keys
|
||||
value:
|
||||
keys:
|
||||
- kid: auth-tokens-es384-202510
|
||||
kty: EC
|
||||
use: sig
|
||||
alg: ES384
|
||||
crv: P-384
|
||||
x: 7UchU5R77LtChrJx6uWg9mYjFvV6RIpSgZPDIj7d1q0
|
||||
y: v98nHe8a7mGZ9Fn1t4Jp9PTJv1ma35QPmhUrE4pH7H0
|
||||
status: active
|
||||
- kid: auth-tokens-es384-202409
|
||||
kty: EC
|
||||
use: sig
|
||||
alg: ES384
|
||||
crv: P-384
|
||||
x: hjdKc0r8jvVHJ7S9mP0y0mU9bqN7v5PxS21SwclTzfc
|
||||
y: yk6J3pz4TUpymN4mG-6th3dYvJ5N1lQvDK0PLuFv3Pg
|
||||
status: retiring
|
||||
Reference in New Issue
Block a user