The portal backend server API for the kgateway 2.x generation of Gloo Portal. It exposes health and readiness probes, the API product catalog and product versions, user and team management, team applications, application subscriptions, API keys, OAuth credentials, application metadata, and the OIDC login/logout redirect endpoints used by the frontend portal.
openapi: 3.0.3
info:
title: Portal Backend API
description: API for the gateway developer portal backend server
version: 1.0.0
servers:
- url: /v1
description: API v1 base path
tags:
- name: health
description: Health check endpoints
- name: api-products
description: API product catalog endpoints
- name: users
description: User management endpoints
- name: teams
description: Team management endpoints
- name: apps
description: Application management endpoints
- name: subscriptions
description: Subscription management endpoints
- name: api-keys
description: API key management endpoints
- name: oauth-credentials
description: OAuth credential management endpoints
- name: metadata
description: Internal credential metadata endpoints
- name: auth
description: Authentication redirect endpoints
paths:
/healthz:
servers:
- url: /
description: Root path (health endpoints are not under /v1)
get:
summary: Health check
description: Returns OK if the server is healthy
operationId: HealthCheck
tags:
- health
responses:
"200":
description: Server is healthy
/readyz:
servers:
- url: /
description: Root path (health endpoints are not under /v1)
get:
summary: Readiness check
description: Returns OK if the server is ready to accept requests
operationId: ReadinessCheck
tags:
- health
responses:
"200":
description: Server is ready
/api-products:
get:
summary: List API products
description: Retrieve a list of all API products accessible by the user
operationId: ListApiProducts
tags:
- api-products
responses:
"200":
description: List of API products
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/ApiProductSummary"
"503":
description: API products not loaded
/api-products/{productID}:
get:
summary: Get API product details
description: Returns detailed information about a specific API product
operationId: GetApiProduct
tags:
- api-products
parameters:
- name: productID
in: path
description: API Product ID
required: true
schema:
type: string
responses:
"200":
description: API product details
content:
application/json:
schema:
$ref: "#/components/schemas/ApiProductDetails"
"404":
description: Product not found
"503":
description: API products not loaded
/api-products/{productID}/versions:
get:
summary: List API product versions
description: Returns all versions of a specific API product including OpenAPI specs
operationId: ListApiProductVersions
tags:
- api-products
parameters:
- name: productID
in: path
description: API Product ID
required: true
schema:
type: string
responses:
"200":
description: List of API product versions
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/ApiProductVersion"
"503":
description: API products not loaded
/me:
get:
summary: Get current user
description: Returns the authenticated user's information. Creates a new user record if this is the first access.
operationId: GetCurrentUser
tags:
- users
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
responses:
"200":
description: Current user information
content:
application/json:
schema:
$ref: "#/components/schemas/User"
"401":
description: Authentication required
"500":
description: Internal server error
put:
summary: Update current user
description: Updates the authenticated user's information
operationId: UpdateCurrentUser
tags:
- users
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
responses:
"200":
description: Updated user information
content:
application/json:
schema:
$ref: "#/components/schemas/User"
"401":
description: Authentication required
"500":
description: Internal server error
/users:
get:
summary: List users
description: Returns a list of all registered users
operationId: ListUsers
tags:
- users
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
responses:
"200":
description: List of users
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/User"
"401":
description: Authentication required
"500":
description: Internal server error
/teams:
get:
summary: List teams
description: Returns a list of all teams
operationId: ListTeams
tags:
- teams
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
responses:
"200":
description: List of teams
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/TeamSummary"
"401":
description: Authentication required
"500":
description: Internal server error
post:
summary: Create team
description: Creates a new team. The creator is automatically added as a member.
operationId: CreateTeam
tags:
- teams
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateTeamRequest"
responses:
"201":
description: Team created
content:
application/json:
schema:
$ref: "#/components/schemas/TeamSummary"
"400":
description: Invalid request
"401":
description: Authentication required
"409":
description: Team already exists
"500":
description: Internal server error
/teams/{teamID}:
get:
summary: Get team details
description: Returns detailed information about a team including its members
operationId: GetTeam
tags:
- teams
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
parameters:
- name: teamID
in: path
description: Team ID
required: true
schema:
type: string
responses:
"200":
description: Team details with members
content:
application/json:
schema:
$ref: "#/components/schemas/TeamDetails"
"401":
description: Authentication required
"404":
description: Team not found
"500":
description: Internal server error
put:
summary: Update team
description: Updates a team's name and description
operationId: UpdateTeam
tags:
- teams
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
parameters:
- name: teamID
in: path
description: Team ID
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UpdateTeamRequest"
responses:
"200":
description: Team updated
content:
application/json:
schema:
$ref: "#/components/schemas/TeamSummary"
"400":
description: Invalid request
"401":
description: Authentication required
"500":
description: Internal server error
delete:
summary: Delete team
description: Deletes a team and removes all member associations
operationId: DeleteTeam
tags:
- teams
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
parameters:
- name: teamID
in: path
description: Team ID
required: true
schema:
type: string
responses:
"204":
description: Team deleted
"401":
description: Authentication required
"409":
description: Team has apps or members that must be removed first
"500":
description: Internal server error
/teams/{teamID}/apps:
get:
summary: List team apps
description: Returns all applications belonging to a team
operationId: ListTeamApps
tags:
- teams
- apps
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
parameters:
- name: teamID
in: path
description: Team ID
required: true
schema:
type: string
responses:
"200":
description: List of team applications
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/App"
"401":
description: Authentication required
"500":
description: Internal server error
post:
summary: Create team app
description: Creates a new application for a team
operationId: CreateTeamApp
tags:
- teams
- apps
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
parameters:
- name: teamID
in: path
description: Team ID
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateAppRequest"
responses:
"201":
description: Application created
content:
application/json:
schema:
$ref: "#/components/schemas/App"
"400":
description: Invalid request
"401":
description: Authentication required
"409":
description: App already exists
"500":
description: Internal server error
/teams/{teamID}/members:
get:
summary: List team members
description: Returns all members of a team with their user details
operationId: ListTeamMembers
tags:
- teams
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
parameters:
- name: teamID
in: path
description: Team ID
required: true
schema:
type: string
responses:
"200":
description: List of team members
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/TeamMember"
"401":
description: Authentication required
"500":
description: Internal server error
post:
summary: Add team member
description: Adds a user to a team by userId or email
operationId: AddTeamMember
tags:
- teams
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
parameters:
- name: teamID
in: path
description: Team ID
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/AddTeamMemberRequest"
responses:
"201":
description: Member added
content:
application/json:
schema:
$ref: "#/components/schemas/TeamMember"
"400":
description: Invalid request - userId or email required
"401":
description: Authentication required
"404":
description: Team or user not found
"409":
description: User already a member
"500":
description: Internal server error
/teams/{teamID}/members/{memberID}:
delete:
summary: Remove team member
description: Removes a user from a team
operationId: RemoveTeamMember
tags:
- teams
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
parameters:
- name: teamID
in: path
description: Team ID
required: true
schema:
type: string
- name: memberID
in: path
description: Team Member (User) ID
required: true
schema:
type: string
responses:
"204":
description: Member removed
"401":
description: Authentication required
"500":
description: Internal server error
/apps/{appID}:
get:
summary: Get app details
description: Returns detailed information about an application
operationId: GetApp
tags:
- apps
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
parameters:
- name: appID
in: path
description: Application ID
required: true
schema:
type: string
responses:
"200":
description: Application details
content:
application/json:
schema:
$ref: "#/components/schemas/App"
"401":
description: Authentication required
"404":
description: App not found
"500":
description: Internal server error
put:
summary: Update app
description: Updates an application's name and description
operationId: UpdateApp
tags:
- apps
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
parameters:
- name: appID
in: path
description: Application ID
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UpdateAppRequest"
responses:
"200":
description: Application updated
content:
application/json:
schema:
$ref: "#/components/schemas/App"
"400":
description: Invalid request
"401":
description: Authentication required
"404":
description: App not found
"500":
description: Internal server error
delete:
summary: Delete app
description: Deletes an application and all associated resources (subscriptions, API keys, OAuth credentials)
operationId: DeleteApp
tags:
- apps
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
parameters:
- name: appID
in: path
description: Application ID
required: true
schema:
type: string
responses:
"204":
description: Application deleted
"401":
description: Authentication required
"409":
description: App has API keys or OAuth credentials that must be removed first
"500":
description: Internal server error
/apps/{appID}/metadata:
post:
summary: Set app metadata (Admin)
description: Sets rate limit and custom metadata on an application. Requires admin privileges.
operationId: SetAppMetadata
tags:
- apps
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
parameters:
- name: appID
in: path
description: Application ID
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/SetMetadataRequest"
responses:
"200":
description: App metadata updated
content:
application/json:
schema:
$ref: "#/components/schemas/App"
"400":
description: Invalid request or rate limit unit
"401":
description: Authentication required
"403":
description: Admin access required
"404":
description: App not found
"500":
description: Internal server error
/apps/{appID}/subscriptions:
get:
summary: List app subscriptions
description: Returns all subscriptions for an application
operationId: ListAppSubscriptions
tags:
- apps
- subscriptions
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
parameters:
- name: appID
in: path
description: Application ID
required: true
schema:
type: string
responses:
"200":
description: List of subscriptions
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Subscription"
"401":
description: Authentication required
"404":
description: App not found
"500":
description: Internal server error
post:
summary: Create app subscription
description: Creates a new subscription for an application to an API product. The subscription starts in pending status.
operationId: CreateAppSubscription
tags:
- apps
- subscriptions
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
parameters:
- name: appID
in: path
description: Application ID
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateSubscriptionRequest"
responses:
"201":
description: Subscription created
content:
application/json:
schema:
$ref: "#/components/schemas/Subscription"
"400":
description: Invalid request - apiProductId required
"401":
description: Authentication required
"404":
description: App not found
"409":
description: Subscription already exists
"500":
description: Internal server error
/apps/{appID}/subscriptions/{subscriptionID}:
delete:
summary: Delete app subscription
description: Deletes a subscription from an application
operationId: DeleteAppSubscription
tags:
- apps
- subscriptions
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
parameters:
- name: appID
in: path
description: Application ID
required: true
schema:
type: string
- name: subscriptionID
in: path
description: Subscription ID
required: true
schema:
type: string
responses:
"204":
description: Subscription deleted
"401":
description: Authentication required
"500":
description: Internal server error
/apps/{appID}/api-keys:
get:
summary: List app API keys
description: Returns all API keys for an application (without the actual key values)
operationId: ListAppApiKeys
tags:
- apps
- api-keys
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
parameters:
- name: appID
in: path
description: Application ID
required: true
schema:
type: string
responses:
"200":
description: List of API keys
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/ApiKey"
"401":
description: Authentication required
"404":
description: App not found
"500":
description: Internal server error
post:
summary: Create app API key
description: Creates a new API key for an application. The raw API key value is only returned once at creation time.
operationId: CreateAppApiKey
tags:
- apps
- api-keys
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
parameters:
- name: appID
in: path
description: Application ID
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateApiKeyRequest"
responses:
"201":
description: API key created
content:
application/json:
schema:
$ref: "#/components/schemas/ApiKeyWithSecret"
"400":
description: Invalid request - apiKeyName required
"401":
description: Authentication required
"404":
description: App not found
"409":
description: API key already exists
"500":
description: Internal server error
/apps/{appID}/api-keys/{keyID}:
delete:
summary: Delete app API key
description: Deletes an API key from an application
operationId: DeleteAppApiKey
tags:
- apps
- api-keys
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
parameters:
- name: appID
in: path
description: Application ID
required: true
schema:
type: string
- name: keyID
in: path
description: API Key ID
required: true
schema:
type: string
responses:
"204":
description: API key deleted
"401":
description: Authentication required
"500":
description: Internal server error
/apps/{appID}/oauth-credentials:
get:
summary: Get app OAuth credential
description: Returns the OAuth credential for an application (without the client secret)
operationId: GetAppOAuthCredential
tags:
- apps
- oauth-credentials
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
parameters:
- name: appID
in: path
description: Application ID
required: true
schema:
type: string
responses:
"200":
description: OAuth credential (without secret)
content:
application/json:
schema:
$ref: "#/components/schemas/OAuthCredential"
"401":
description: Authentication required
"404":
description: App or credential not found
"500":
description: Internal server error
post:
summary: Create app OAuth credential
description: Creates a new OAuth credential for an application. The client secret is only returned once at creation time.
operationId: CreateAppOAuthCredential
tags:
- apps
- oauth-credentials
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
parameters:
- name: appID
in: path
description: Application ID
required: true
schema:
type: string
responses:
"201":
description: OAuth credential created
content:
application/json:
schema:
$ref: "#/components/schemas/OAuthCredentialWithSecret"
"401":
description: Authentication required
"404":
description: App not found
"409":
description: Credential already exists (one per app)
"500":
description: Internal server error
/oauth-credentials/{credentialID}:
delete:
summary: Delete OAuth credential
description: Deletes an OAuth credential by ID
operationId: DeleteOAuthCredential
tags:
- oauth-credentials
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
parameters:
- name: credentialID
in: path
description: OAuth Credential ID
required: true
schema:
type: string
responses:
"204":
description: OAuth credential deleted
"401":
description: Authentication required
"500":
description: Internal server error
/subscriptions:
get:
summary: List all subscriptions
description: Returns all subscriptions across all apps. Optionally filtered by status.
operationId: ListSubscriptions
tags:
- subscriptions
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
parameters:
- name: status
in: query
description: Filter subscriptions by status
schema:
$ref: "#/components/schemas/SubscriptionStatus"
responses:
"200":
description: List of subscriptions
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Subscription"
"401":
description: Authentication required
"500":
description: Internal server error
/subscriptions/{subscriptionID}:
delete:
summary: Delete subscription
description: Deletes a subscription by ID
operationId: DeleteSubscription
tags:
- subscriptions
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
parameters:
- name: subscriptionID
in: path
description: Subscription ID
required: true
schema:
type: string
responses:
"204":
description: Subscription deleted
"401":
description: Authentication required
"500":
description: Internal server error
/subscriptions/{subscriptionID}/metadata:
post:
summary: Set subscription metadata (Admin)
description: Sets rate limit and custom metadata on a subscription. Requires admin privileges.
operationId: SetSubscriptionMetadata
tags:
- subscriptions
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
parameters:
- name: subscriptionID
in: path
description: Subscription ID
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/SetMetadataRequest"
responses:
"200":
description: Subscription metadata updated
content:
application/json:
schema:
$ref: "#/components/schemas/Subscription"
"400":
description: Invalid request or rate limit unit
"401":
description: Authentication required
"403":
description: Admin access required
"404":
description: Subscription not found
"500":
description: Internal server error
/subscriptions/{subscriptionID}/{action}:
post:
summary: Approve or reject subscription (Admin)
description: Approves or rejects a pending subscription. Requires admin privileges.
operationId: SubscriptionAction
tags:
- subscriptions
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
parameters:
- name: subscriptionID
in: path
description: Subscription ID
required: true
schema:
type: string
- name: action
in: path
description: Action to perform on the subscription
required: true
schema:
type: string
enum:
- approve
- reject
responses:
"200":
description: Subscription updated
content:
application/json:
schema:
$ref: "#/components/schemas/Subscription"
"400":
description: Invalid action
"401":
description: Authentication required
"403":
description: Admin access required
"404":
description: Subscription not found
"500":
description: Internal server error
/api-keys/{keyID}:
delete:
summary: Delete API key
description: Deletes an API key by ID
operationId: DeleteApiKey
tags:
- api-keys
security:
- bearerAuth: []
- identityToken: []
- accessToken: []
parameters:
- name: keyID
in: path
description: API Key ID
required: true
schema:
type: string
responses:
"204":
description: API key deleted
"401":
description: Authentication required
"500":
description: Internal server error
/metadata:
get:
summary: Get credential metadata (Internal)
description: >
Internal endpoint used by ExtAuth to validate API keys and access tokens.
Returns whether the credential is allowed and any associated metadata.
operationId: GetCredentialMetadata
tags:
- metadata
parameters:
- name: apiKey
in: query
description: Raw API key value to validate. Exactly one of apiKey or accessToken must be provided.
schema:
type: string
- name: accessToken
in: query
description: OAuth access token to validate. Exactly one of apiKey or accessToken must be provided.
schema:
type: string
- name: apiProductId
in: query
description: API product ID to check subscription for
required: true
schema:
type: string
responses:
"200":
description: Credential validation result
content:
application/json:
schema:
$ref: "#/components/schemas/CredentialMetadataResponse"
"400":
description: Missing required query parameters
/login:
get:
summary: Login redirect
description: Redirects to the app root after successful OIDC authentication. The actual OIDC flow is handled by extauth.
operationId: LoginRedirect
tags:
- auth
responses:
"302":
description: Redirect to app root
/logout:
get:
summary: Logout redirect
description: Redirects to the app root after logout. The actual logout flo
# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/solo-io/refs/heads/main/openapi/solo-io-portal-backend-openapi.yml