Gloo Portal Server API

info:
  title: 'Gloo Portal Server API'
  version: 1.0.0
  description: 'Review the following reference documentation for the Gloo portal server APIs, which has the endpoint specifications for managing user access to both the developer portal and resources exposed by the portal. You can use these APIs to build your own frontend application. Be sure to update the server URL to the host that you exposed the backend portal server on, such as portal.example.com. For a sample app, refer to the Gloo Portal product documentation and GitHub repo https://github.com/solo-io/dev-portal-starter.'
openapi: 3.0.0
servers:
  - url: http://portal.example.com/v1
components:
  schemas:
    APIKey:
      allOf:
      - $ref: '#/components/schemas/BaseEntity'
      - properties:
          apiKey:
            description: Is returned only once when the API key is created
            example: 4f357f4f-cd56-41d2-aca8-301c999bb8a4
            type: string
          id:
            example: ae8261d2-4e16-4a06-b1f3-1af71464a8dd
            type: string
          metadata:
            example:
              key: value
            type: object
          name:
            example: api-key-name-1
            type: string
        type: object
    APIProduct:
      allOf:
      - $ref: '#/components/schemas/BaseEntity'
      - properties:
          apiProductMetadata:
            description: Metadata for the API product.
            type: object
          contactEmail:
            type: string
          description:
            type: string
          name:
            type: string
        type: object
    APIProductSummary:
      allOf:
      - $ref: '#/components/schemas/BaseEntity'
      - properties:
          apiKeyEnabled:
            description: Indicates whether `ApiKey` is enabled as an authentication
              mechanism for the API product.
            type: boolean
          apiProductMetadata:
            description: Metadata for the API product.
            type: object
          description:
            type: string
          name:
            type: string
          oauthEnabled:
            description: Indicates whether `OAuth` is enabled as an authentication
              mechanism for the API product.
            type: boolean
          versionsCount:
            description: The version count of the API product.
            example: 2
            type: integer
        type: object
    Application:
      allOf:
      - $ref: '#/components/schemas/BaseEntity'
      - properties:
          description:
            example: app description
            type: string
          metadata:
            $ref: '#/components/schemas/ApplicationMetadata'
          name:
            example: app
            type: string
          teamId:
            example: 2frepq0mjp841i3jfd030dhtmn
            readOnly: true
            type: string
        type: object
    ApplicationCreate:
      description: Create
      properties:
        description:
          example: app description
          type: string
        name:
          example: app
          type: string
      required:
      - name
    ApplicationMetadata:
      allOf:
      - $ref: '#/components/schemas/BaseEntity'
      - properties:
          customMetadata:
            example:
              key: value
            type: object
          rateLimit:
            $ref: '#/components/schemas/RateLimit'
        type: object
    ApplicationUpdate:
      properties:
        description:
          example: the app description
          type: string
        name:
          example: app
          type: string
    BaseEntity:
      properties:
        createdAt:
          example: '2021-08-25T20:00:00Z'
          format: date-time
          readOnly: true
          type: string
        deletedAt:
          example: '2021-08-25T20:00:00Z'
          format: date-time
          readOnly: true
          type: string
        id:
          example: uuid
          readOnly: true
          type: string
        updatedAt:
          example: '2021-08-25T20:00:00Z'
          format: date-time
          readOnly: true
          type: string
    OAuthCredential:
      properties:
        id:
          example: uuid
          readOnly: true
          type: string
        idpClientId:
          example: generated-client-id
          readOnly: true
          type: string
        idpClientName:
          example: client-name
          readOnly: true
          type: string
        idpClientSecret:
          example: generated-client-secret
          readOnly: true
          type: string
      type: object
    ProductVersion:
      allOf:
      - $ref: '#/components/schemas/BaseEntity'
      - properties:
          apiProductId:
            type: string
          apiSpec:
            type: object
          documentation:
            type: string
          license:
            type: string
          name:
            type: string
          productVersionMetadata:
            description: Metadata for the API product version.
            type: object
          termsOfService:
            type: string
          title:
            type: string
        type: object
    RateLimit:
      properties:
        requestsPerUnit:
          example: 5
          type: string
        unit:
          enum:
          - SECOND
          - MINUTE
          - HOUR
          - DAY
          - MONTH
          - YEAR
          example: SECOND
          type: string
    Subscription:
      allOf:
      - $ref: '#/components/schemas/BaseEntity'
      - properties:
          apiProductId:
            description: The ID of the API product associated with the subscription.
            type: string
          applicationId:
            description: The ID of the application to which the subscription is associated.
            readOnly: true
            type: string
          approved:
            description: Indicates whether the subscription has been approved.
            readOnly: true
            type: boolean
          approvedAt:
            description: The timestamp when the subscription was approved.
            format: date-time
            readOnly: true
            type: string
          metadata:
            $ref: '#/components/schemas/SubscriptionMetadata'
          rejected:
            description: Indicates whether the subscription has been rejected.
            readOnly: true
            type: boolean
          rejectedAt:
            description: The timestamp when the subscription was rejected.
            format: date-time
            readOnly: true
            type: string
          requestedAt:
            description: The timestamp when the subscription was requested.
            format: date-time
            readOnly: true
            type: string
        type: object
    SubscriptionCreate:
      properties:
        apiProductId:
          description: The API Product ID that we are subscribing to
          type: string
      required:
      - apiProductId
      type: object
    SubscriptionMetadata:
      allOf:
      - $ref: '#/components/schemas/BaseEntity'
      - properties:
          customMetadata:
            example:
              key: value
            type: object
          rateLimit:
            $ref: '#/components/schemas/RateLimit'
        type: object
    Team:
      allOf:
      - $ref: '#/components/schemas/BaseEntity'
      - $ref: '#/components/schemas/TeamCreate'
    TeamCreate:
      description: Create a new team
      properties:
        description:
          example: team description
          type: string
        name:
          example: ACME Team
          type: string
      required:
      - name
    TeamUpdate:
      allOf:
      - $ref: '#/components/schemas/TeamCreate'
    User:
      allOf:
      - $ref: '#/components/schemas/BaseEntity'
      - properties:
          email:
            example: johndoe@email.com
            type: string
          isAdmin:
            example: false
            type: boolean
          name:
            example: John Doe
            type: string
          synced:
            example: true
            type: boolean
          username:
            example: johndoe
            type: string
        required:
        - email
        type: object
  securitySchemes:
    identityToken:
      description: id token cookie from the identity provider used to authenticate
        the user
      in: cookie
      name: id_token
      type: apiKey
paths:
  /api-keys/{keyId}:
    delete:
      description: Deletes an API Key by API Key ID (UUID).
      operationId: DeleteAPIKey
      parameters:
      - description: The API Key ID (UUID) of key to be deleted.
        in: path
        name: keyId
        required: true
        schema:
          example: bfbf98eb-732d-428f-b948-770629802231
          type: string
      responses:
        '204':
          description: Successfully deleted API keys.
        '400':
          description: Bad request. Please supply an API Key Name
        '401':
          description: Unauthorized. The user's identity token is invalid.
        '403':
          description: Forbidden. The user's identity token is valid, but the user
            has missing claims required by this method.
        '404':
          description: User not found.
        '500':
          description: Unexpected error deleting API keys. Try again in a few moments.
      security:
      - identityToken: []
      summary: Deletes the current user's API key(s) for a specified API ID.
      tags:
      - Applications
  /api-products:
    get:
      description: 'Retrieve a list of all API product summaries accessible to user.


        This will return the list of summaries for all API products.

        '
      operationId: ListApiProducts
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/APIProductSummary'
                type: array
          description: A list of API products summaries accessible to user.
        '401':
          description: Unauthorized. The user's identity token is invalid
        '404':
          description: No API Products found
        '500':
          description: Unexpected error fetching api products
      security:
      - identityToken: []
      tags:
      - API Products
  /api-products/{productId}:
    get:
      description: Retrieve a specific API product by its ID.
      operationId: GetApiProductById
      parameters:
      - description: The unique identifier of the API product.
        in: path
        name: productId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIProduct'
          description: An API product object.
        '400':
          description: Invalid request parameters.
        '401':
          description: Unauthorized. The user's identity token is invalid.
        '403':
          description: Forbidden. The user's identity token is valid, but the user
            does not have permission to view the API product.
        '404':
          description: API Product not found.
        '500':
          description: Unexpected error fetching api product.
      tags:
      - API Products
  /api-products/{productId}/versions:
    get:
      description: Retrieve all versions for a specific API product.
      operationId: ListProductVersions
      parameters:
      - description: The unique identifier of the API product.
        in: path
        name: productId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ProductVersion'
                type: array
          description: A list of product versions for the specified API product.
        '400':
          description: Invalid request parameters.
        '401':
          description: Unauthorized. The user's identity token is invalid.
        '403':
          description: Forbidden. The user's identity token is valid, but the user
            does not have permission to view the API product.
        '404':
          description: API Product not found.
        '500':
          description: Unexpected error fetching api product.
      tags:
      - API Products
  /apps/{appId}:
    delete:
      description: Delete Application
      operationId: DeleteApplication
      parameters:
      - description: Unique identifier of the application
        in: path
        name: appId
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Successfully deleted client.
        '401':
          description: Unauthorized. The user's identity token is invalid.
        '403':
          description: Forbidden. The user's identity token is valid, but the user
            does not have permission to delete the application.
        '404':
          description: Not found.
        '500':
          description: Unexpected error deleting client.
      security:
      - identityToken: []
      summary: Deletes an application
      tags:
      - Applications
    get:
      description: Get App information by its ID
      operationId: GetApplicationById
      parameters:
      - description: Unique identifier of the team app
        in: path
        name: appId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
          description: Successfully retrieved app information
        '401':
          description: Unauthorized. The user's identity token is invalid.
        '403':
          description: Forbidden. The user's identity token is valid, but the user
            does not have permission to view the app.
        '404':
          description: App not found
        '500':
          description: Unexpected error querying for app information
      security:
      - identityToken: []
      summary: Gets an application
      tags:
      - Applications
    put:
      description: Update Application
      operationId: UpdateApplication
      parameters:
      - description: Unique identifier of the team app
        in: path
        name: appId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationUpdate'
        description: Updates an application
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
          description: Successfully updated application information.
        '400':
          description: Bad request. The request body is invalid.
        '401':
          description: Unauthorized. The user's identity token is invalid.
        '403':
          description: Forbidden. The user's identity token is valid, but the user
            does not have permission to update the application.
        '404':
          description: App not found
        '500':
          description: Unexpected error updating application information.
      security:
      - identityToken: []
      summary: Updates an application
      tags:
      - Applications
  /apps/{appId}/api-keys:
    get:
      description: Lists the API keys for the current user, filterable by usage plans
        or API IDs. A usage plan can have multiple API keys, which can each be tied
        to multiple API IDs. An API key belongs to only one usage plan. To check the
        current user, use the GET /me endpoint. To create an API key, use the POST
        /api-keys endpoint.
      operationId: ListApplicationAPIKeys
      parameters:
      - description: The unique identifier of the application.
        in: path
        name: appId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/APIKey'
                type: array
          description: Successfully listed API keys.
        '400':
          description: Bad request. Please supply appId.
        '404':
          description: Application not found for provided appId.
        '500':
          description: Unexpected error fetching API keys. Try again in a few moments.
      security:
      - identityToken: []
      summary: Lists API keys for the current user, filterable by usage plans or API
        IDs.
      tags:
      - Applications
    post:
      description: Creates an API key for the current user for a application. To check
        the current user, use the GET /me endpoint.
      operationId: CreateApplicationAPIKey
      parameters:
      - description: The unique identifier of the application.
        in: path
        name: appId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                apiKeyName:
                  example: api-key-name-1
                  type: string
              type: object
        description: Send the name for this API key in the request body.
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIKey'
          description: Successfully created API key.
        '400':
          description: Bad request. Please supply an API Key Name
        '401':
          description: Unauthorized. The user's identity token is invalid.
        '404':
          description: Application not found for provided appId.
        '409':
          description: An API key with the same name already exists in the application.
        '500':
          description: Unexpected error creating API key. Try again in a few moments.
      security:
      - identityToken: []
      summary: Creates an API key for the current user for a specific API ID and usage
        plan.
      tags:
      - Applications
  /apps/{appId}/oauth-credentials:
    get:
      description: Gets the OAuth client credentials for the application
      operationId: GetApplicationOAuthCredential
      parameters:
      - description: The unique identifier of the application.
        in: path
        name: appId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthCredential'
          description: Successfully listed OAuth Client Credentials.
        '400':
          description: Bad request. Please supply appId.
        '404':
          description: Application not found for provided appId.
        '500':
          description: Unexpected error fetching API keys. Try again in a few moments.
      security:
      - identityToken: []
      tags:
      - Applications
    post:
      description: Generates new credentials for the specified application and pushes
        them to the Identity Provider. If credentials already exist a for the application,
        then a `409 Conflict` error will be returned.
      operationId: GenerateApplicationOAuthCredential
      parameters:
      - description: The unique identifier of the application.
        in: path
        name: appId
        required: true
        schema:
          type: string
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthCredential'
          description: Successfully generated and pushed application credentials.
        '400':
          description: Invalid request parameters.
        '401':
          description: Unauthorized. The user's identity token is invalid.
        '403':
          description: Forbidden. The user's identity token is valid, but the user
            does not have permission to generate credentials for the application.
        '404':
          description: Application not found.
        '409':
          description: Application credentials already exist.
        '500':
          description: Unexpected error generating or pushing credentials.
      security:
      - identityToken: []
      summary: Generate and push application credentials to the Identity Provider
      tags:
      - Applications
  /apps/{appId}/subscriptions:
    get:
      description: Retrieve all subscriptions for an application
      operationId: ListApplicationProductSubscriptions
      parameters:
      - description: Unique identifier of the team app
        in: path
        name: appId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Subscription'
                type: array
          description: Successfully listed all app subscriptions
        '400':
          description: Invalid request parameters.
        '401':
          description: Unauthorized. The user's identity token is invalid.
        '403':
          description: Forbidden. The user's identity token is valid, but the user
            does not have permission to view the app subscriptions.
        '404':
          description: App not found
        '500':
          description: Unexpected error fetching app subscriptions
      security:
      - identityToken: []
      summary: Lists all app subscriptions
      tags:
      - Applications
    post:
      description: Subscribe to an API product. It is subject to admin approval.
      operationId: SubscribeToApiProduct
      parameters:
      - description: Unique identifier of the team app
        in: path
        name: appId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionCreate'
        description: Subscription object that needs to be created
        required: true
      responses:
        '201':
          description: Successfully created the subscription
        '400':
          description: Bad request. The request body is invalid.
        '401':
          description: Unauthorized. The user's identity token is invalid.
        '403':
          description: Forbidden. The user's identity token is valid, but the user
            does not have permission to create the subscription.
        '404':
          description: App not found.
        '409':
          description: Subscription already exists.
        '500':
          description: Unexpected error creating the subscription.
      security:
      - identityToken: []
      summary: Subscribes to an API product
      tags:
      - Applications
  /me:
    get:
      description: Looks up the user for the current session. Returns your user information
        if the user session exists and is not expired. You might use this endpoint
        to confirm your identity before performing other actions for the developer
        portal, like issuing an API key.
      operationId: GetCurrentUser
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          description: Successfully got user information.
        '401':
          description: Unauthorized. The user's identity token is invalid.
        '403':
          description: Forbidden. The user's identity token is valid, but the user
            has missing claims required by this method.
        '404':
          description: User not found.
        '500':
          description: Internal server error. Try again in a few moments.
      security:
      - identityToken: []
      - {}
      summary: Gets the user for the current session.
      tags:
      - Me
    put:
      description: 'Upsert current user with the information encoded in the id token.

        It is recommended to call this endpoint after the user logs in to the portal
        to ensure that the data is up to date.

        '
      operationId: UpsertCurrentUser
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          description: Successfully updated the user details
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          description: Successfully created the user details
        '401':
          description: Unauthorized. The user's identity token is invalid.
        '500':
          description: Unexpected error creating the user
      security:
      - identityToken: []
      summary: Upserts the current user
      tags:
      - Me
  /oauth-credentials/{credentialId}:
    delete:
      description: Deletes an OAuth client credential by its client ID
      operationId: DeleteOAuthCredential
      parameters:
      - description: The OAuth client credential ID (UUID) of the credential to be
          deleted.
        in: path
        name: credentialId
        required: true
        schema:
          example: bfbf98eb-732d-428f-b948-770629802231
          type: string
      responses:
        '204':
          description: Successfully deleted OAuth client credential.
        '400':
          description: Bad request. Please supply an OAuth client credential ID.
        '401':
          description: Unauthorized. The user's identity token is invalid.
        '403':
          description: Forbidden. The user's identity token is valid, but the user
            has missing claims required by this method.
        '404':
          description: User not found.
        '500':
          description: Unexpected error deleting OAuth client credential. Try again
            in a few moments.
      security:
      - identityToken: []
      summary: Deletes an OAuth client credential
      tags:
      - Applications
  /subscriptions:
    get:
      description: 'Retrieves a list of subscriptions, filtered by their approval
        status. Use the `status` query parameter to specify whether to return ''pending'',
        ''approved'', or ''rejected'' subscriptions. If the user is an administrator,
        all subscriptions for the specified status will be returned. Otherwise, only
        the subscriptions belonging to the teams for the given user with the specified
        status will be returned.

        '
      operationId: ListSubscriptionsByStatus
      parameters:
      - description: Filter subscriptions by status ('pending' for subscriptions awaiting
          approval, 'approved' for subscriptions that have been approved, 'rejected'
          for subscriptions that have been denied).
        in: query
        name: status
        required: true
        schema:
          enum:
          - pending
          - approved
          - rejected
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Subscription'
                type: array
          description: Successfully retrieved list of subscriptions.
        '400':
          description: Invalid status parameter.
        '401':
          description: Unauthorized. The user's identity token is invalid.
        '403':
          description: Unauthorized to view the list.
        '500':
          description: Internal server error.
      summary: List subscriptions filtered by status
      tags:
      - Subscriptions
  /subscriptions/{subscriptionId}:
    delete:
      description: Deletes a subscription, revoking the associated application's access
        to the specified API product.
      operationId: DeleteApplicationProductSubscription
      parameters:
      - description: The unique identifier of the subscription to delete.
        in: path
        name: subscriptionId
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Subscription successfully deleted.
        '400':
          description: Invalid request parameters.
        '403':
          description: Unauthorized to delete subscription.
        '404':
          description: Subscription not found.
        '500':
          description: Internal server error.
      summary: Delete subscription
      tags:
      - Subscriptions
  /teams:
    get:
      description: Retrieve the teams of the current user
      operationId: ListTeams
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Team'
                type: array
          description: Successfully listed all teams
        '401':
          description: Unauthorized. The user's identity token is invalid
        '404':
          description: Teams not found
        '500':
          description: Unexpected error fetching teams
      security:
      - identityToken: []
      summary: Lists all teams
      tags:
      - Teams
    post:
      description: Create a new team associated with the user provided in the identity
        token
      operationId: CreateTeam
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamCreate'
        description: Team object that needs to be created
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
          description: Successfully created the team
        '400':
          description: Bad request. The request body is invalid.
        '401':
          description: Unauthorized. The user's identity token is invalid.
        '404':
          description: User not found
        '409':
          description: User belongs to a team with the same name
        '500':
          description: Unexpected error creating the team
      security:
      - identityToken: []
      summary: Creates a team
      tags:
      - Teams
  /teams/{teamId}:
    delete:
      description: 'Delete a team.


        Prerequisite: All users and all apps associated with the team must be deleted
        before the team can be deleted.'
      operationId: DeleteTeam
      parameters:
      - description: Unique identifier of the team
        in: path
        name: teamId
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Successfully deleted the team
        '400':
          description: Bad request. The team has users or apps associated with it.
        '401':
          description: Unauthorized. The user's identity token is invalid.
        '403':
          description: Forbidden. The user's identity token is valid, but the user
            does not have permission to delete the team
        '404':
          description: Team not found
        '500':
          description: Unexpected error deleting the team
      security:
      - identityToken: []
      summary: Deletes a team
      tags:
      - Teams
    get:
      description: Retrieve detailed information about a team by its ID
      operationId: GetTeamById
      parameters:
      - description: Unique identifier of the team
        in: path
        name: teamId
        required: true
        schema:
          example: team-id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
          description: Successfully retrieved team information
        '401':
          description: Unauthorized. The user's identity token is invalid.
        '403':
          description: Forbidden. The user's identity token is valid, but the user
            does not have permission to view the team.
        '404':
          description: Team not found
        '500':
          description: Unexpected error querying for team information
      security:
      - identityToken: []
      summary: Gets a team
      tags:
      - Teams
    put:
  

# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/solo-io/refs/heads/main/openapi/solo-io-portal-server-openapi.yml