openapi: 3.2.0
info:
title: Portal Backend Apps API
description: API for the gateway developer portal backend server
version: 1.0.0
servers:
- url: /v1
description: API v1 base path
tags:
- name: apps
description: Application management endpoints
paths:
/teams/{teamID}/apps:
get:
summary: List team apps
description: Returns all applications belonging to a team
operationId: ListTeamApps
tags:
- 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:
- 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
/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
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
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
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
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
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
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
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
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
components:
schemas:
CreateSubscriptionRequest:
type: object
description: Request body for creating a subscription
required:
- apiProductId
properties:
apiProductId:
type: string
description: ID of the API product to subscribe to
OAuthCredentialWithSecret:
type: object
description: OAuth credential with the client secret (only returned at creation time)
required:
- id
- idpClientId
- idpClientSecret
- idpClientName
properties:
id:
type: string
description: Unique OAuth credential identifier
idpClientId:
type: string
description: OAuth client ID
idpClientSecret:
type: string
description: OAuth client secret (only returned at creation time)
idpClientName:
type: string
description: OAuth client display name
ApiKey:
description: API key information (without the actual key value)
allOf:
- $ref: '#/components/schemas/BaseEntity'
- type: object
required:
- appId
- name
properties:
appId:
type: string
description: ID of the application this key belongs to
name:
type: string
description: Display name for the API key
expiresAt:
type: string
format: date-time
description: Timestamp when the key expires
metadata:
type: object
description: Custom metadata for the API key
additionalProperties:
type: string
CreateApiKeyRequest:
type: object
description: Request body for creating an API key
required:
- apiKeyName
properties:
apiKeyName:
type: string
description: Display name for the API key
metadata:
type: object
description: Custom metadata for the API key
additionalProperties:
type: string
ResourceMetadata:
type: object
description: Metadata attached to a resource (app or subscription) including rate limits and custom key-value pairs
required:
- id
properties:
id:
type: string
description: Metadata record ID (resource ID + "-metadata" suffix)
customMetadata:
type: object
description: Custom metadata key-value pairs
additionalProperties:
type: string
rateLimit:
$ref: '#/components/schemas/RateLimit'
createdAt:
type: string
format: date-time
description: Timestamp when the parent resource was created
updatedAt:
type: string
format: date-time
description: Timestamp when the parent resource was last updated
OAuthCredential:
type: object
description: OAuth credential information (without the client secret)
required:
- id
- idpClientId
- idpClientName
properties:
id:
type: string
description: Unique OAuth credential identifier
idpClientId:
type: string
description: OAuth client ID
idpClientName:
type: string
description: OAuth client display name
Subscription:
description: Subscription to an API product
allOf:
- $ref: '#/components/schemas/BaseEntity'
- type: object
required:
- applicationId
- apiProductId
- approved
- rejected
properties:
applicationId:
type: string
description: ID of the subscribing application
apiProductId:
type: string
description: ID of the subscribed API product
approved:
type: boolean
description: Whether the subscription is approved
rejected:
type: boolean
description: Whether the subscription is rejected
requestedAt:
type: string
format: date-time
description: Timestamp when the subscription was requested
metadata:
$ref: '#/components/schemas/ResourceMetadata'
SetMetadataRequest:
type: object
description: Request body for setting metadata (rate limit and/or custom metadata) on a resource
properties:
rateLimit:
$ref: '#/components/schemas/RateLimit'
customMetadata:
type: object
description: Custom metadata key-value pairs
additionalProperties:
type: string
ApiKeyWithSecret:
description: API key with the actual key value (only returned at creation time)
allOf:
- $ref: '#/components/schemas/BaseEntity'
- type: object
required:
- appId
- name
- apiKey
properties:
appId:
type: string
description: ID of the application this key belongs to
name:
type: string
description: Display name for the API key
apiKey:
type: string
description: The raw API key value (only returned at creation time)
metadata:
type: object
description: Custom metadata for the API key
additionalProperties:
type: string
App:
description: Application information
allOf:
- $ref: '#/components/schemas/BaseEntity'
- type: object
required:
- teamId
- name
properties:
teamId:
type: string
description: ID of the team that owns this app
name:
type: string
description: Application name
description:
type: string
description: Application description
metadata:
$ref: '#/components/schemas/ResourceMetadata'
CreateAppRequest:
description: Request body for creating an application
type: object
required:
- name
properties:
name:
type: string
description: Application name
description:
type: string
description: Application description
RateLimit:
type: object
description: Rate limit configuration
required:
- requestsPerUnit
- unit
properties:
requestsPerUnit:
type: string
description: Number of requests allowed per unit
unit:
type: string
description: Time unit for rate limiting
enum:
- SECOND
- MINUTE
- HOUR
- DAY
- MONTH
- YEAR
BaseEntity:
type: object
description: Base entity with common fields
required:
- id
- createdAt
properties:
id:
type: string
description: Unique identifier
createdAt:
type: string
format: date-time
description: Timestamp when the entity was created
updatedAt:
type: string
format: date-time
description: Timestamp when the entity was last updated
UpdateAppRequest:
type: object
description: Request body for updating an application
properties:
name:
type: string
description: Application name
description:
type: string
description: Application description
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Bearer token passed in the Authorization header
identityToken:
type: apiKey
in: cookie
name: id_token
description: id_token cookie set by the identity provider after OIDC login
accessToken:
type: apiKey
in: cookie
name: access_token
description: access_token cookie set by the identity provider after OIDC login