897 lines
37 KiB
YAML
897 lines
37 KiB
YAML
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.
|
|
packs.read: Discover Task Packs and download manifests.
|
|
packs.write: Publish or update Task Packs in the registry.
|
|
packs.run: Execute Task Packs via CLI or Task Runner.
|
|
packs.approve: Approve Task Pack gates and resume runs.
|
|
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:view: Read vulnerability overlays and issue permalinks.
|
|
vuln:investigate: Perform vulnerability triage actions (assign, comment, annotate).
|
|
vuln:operate: Execute vulnerability workflow transitions and remediation tasks.
|
|
vuln:audit: Access vulnerability audit ledgers and exports.
|
|
vuln:read: Read vulnerability permalinks and overlays. (legacy compatibility; prefer vuln:view)
|
|
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.
|
|
packs.read: Discover Task Packs and download manifests.
|
|
packs.write: Publish or update Task Packs in the registry.
|
|
packs.run: Execute Task Packs via CLI or Task Runner.
|
|
packs.approve: Approve Task Pack gates and resume runs.
|
|
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:view: Read vulnerability overlays and issue permalinks.
|
|
vuln:investigate: Perform vulnerability triage actions (assign, comment, annotate).
|
|
vuln:operate: Execute vulnerability workflow transitions and remediation tasks.
|
|
vuln:audit: Access vulnerability audit ledgers and exports.
|
|
vuln:read: Read vulnerability permalinks and overlays. (legacy compatibility; prefer vuln:view)
|
|
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.
|
|
packs.read: Discover Task Packs and download manifests.
|
|
packs.write: Publish or update Task Packs in the registry.
|
|
packs.run: Execute Task Packs via CLI or Task Runner.
|
|
packs.approve: Approve Task Pack gates and resume runs.
|
|
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:view: Read vulnerability overlays and issue permalinks.
|
|
vuln:investigate: Perform vulnerability triage actions (assign, comment, annotate).
|
|
vuln:operate: Execute vulnerability workflow transitions and remediation tasks.
|
|
vuln:audit: Access vulnerability audit ledgers and exports.
|
|
vuln:read: Read vulnerability permalinks and overlays. (legacy compatibility; prefer vuln:view)
|
|
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.
|
|
|
|
/oauth/token:
|
|
post:
|
|
tags:
|
|
- Authentication
|
|
summary: "[Deprecated] Exchange credentials for tokens"
|
|
description: |
|
|
Legacy alias for `/token`. Responses include `Deprecation`, `Sunset`, `Warning`, and `Link`
|
|
headers to advertise the removal timeline. Migrate clients to `/token` before the
|
|
announced sunset date (2026-05-01).
|
|
deprecated: true
|
|
security:
|
|
- ClientSecretBasic: []
|
|
- {}
|
|
requestBody:
|
|
$ref: #/paths/~1token/post/requestBody
|
|
responses:
|
|
200:
|
|
description: Token exchange succeeded (legacy alias of `/token`).
|
|
headers:
|
|
Deprecation:
|
|
description: RFC 7231 HTTP-date signaling when the endpoint was deprecated.
|
|
schema:
|
|
type: string
|
|
Sunset:
|
|
description: RFC 7231 HTTP-date signaling the planned removal of this endpoint.
|
|
schema:
|
|
type: string
|
|
Link:
|
|
description: Sunset documentation link (`rel="sunset"`).
|
|
schema:
|
|
type: string
|
|
Warning:
|
|
description: RFC 7234 Warning header describing the deprecation notice.
|
|
schema:
|
|
type: string
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: #/components/schemas/TokenResponse
|
|
400:
|
|
description: Malformed request, unsupported grant type, or invalid credentials.
|
|
headers:
|
|
Deprecation:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Deprecation
|
|
Sunset:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Sunset
|
|
Link:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Link
|
|
Warning:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Warning
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: #/components/schemas/OAuthErrorResponse
|
|
401:
|
|
description: Client authentication failed.
|
|
headers:
|
|
Deprecation:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Deprecation
|
|
Sunset:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Sunset
|
|
Link:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Link
|
|
Warning:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Warning
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: #/components/schemas/OAuthErrorResponse
|
|
/oauth/revoke:
|
|
post:
|
|
tags:
|
|
- Authentication
|
|
summary: "[Deprecated] Revoke an access or refresh token"
|
|
description: |
|
|
Legacy alias for `/revoke`. Deprecated; clients should call `/revoke` directly. Deprecation headers
|
|
mirror those emitted by the runtime middleware.
|
|
deprecated: true
|
|
security:
|
|
- ClientSecretBasic: []
|
|
requestBody:
|
|
$ref: #/paths/~1revoke/post/requestBody
|
|
responses:
|
|
200:
|
|
description: Token revoked or already invalid (legacy alias of `/revoke`).
|
|
headers:
|
|
Deprecation:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Deprecation
|
|
Sunset:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Sunset
|
|
Link:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Link
|
|
Warning:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Warning
|
|
400:
|
|
description: Malformed request.
|
|
headers:
|
|
Deprecation:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Deprecation
|
|
Sunset:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Sunset
|
|
Link:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Link
|
|
Warning:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Warning
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: #/components/schemas/OAuthErrorResponse
|
|
401:
|
|
description: Client authentication failed.
|
|
headers:
|
|
Deprecation:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Deprecation
|
|
Sunset:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Sunset
|
|
Link:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Link
|
|
Warning:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Warning
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: #/components/schemas/OAuthErrorResponse
|
|
/oauth/introspect:
|
|
post:
|
|
tags:
|
|
- Authentication
|
|
summary: "[Deprecated] Introspect token state"
|
|
description: |
|
|
Legacy alias for `/introspect`. Deprecated; clients must migrate to `/introspect`. Deprecation headers
|
|
highlight the removal schedule.
|
|
deprecated: true
|
|
security:
|
|
- ClientSecretBasic: []
|
|
requestBody:
|
|
$ref: #/paths/~1introspect/post/requestBody
|
|
responses:
|
|
200:
|
|
description: Token state evaluated (legacy alias of `/introspect`).
|
|
headers:
|
|
Deprecation:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Deprecation
|
|
Sunset:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Sunset
|
|
Link:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Link
|
|
Warning:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Warning
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: #/components/schemas/IntrospectionResponse
|
|
400:
|
|
description: Malformed request.
|
|
headers:
|
|
Deprecation:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Deprecation
|
|
Sunset:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Sunset
|
|
Link:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Link
|
|
Warning:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Warning
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: #/components/schemas/OAuthErrorResponse
|
|
401:
|
|
description: Client authentication failed or client lacks introspection permission.
|
|
headers:
|
|
Deprecation:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Deprecation
|
|
Sunset:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Sunset
|
|
Link:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Link
|
|
Warning:
|
|
$ref: #/paths/~1oauth~1token/post/responses/200/headers/Warning
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: #/components/schemas/OAuthErrorResponse /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
|