openapi: 3.1.0
info:
  title: Express Gateway Admin API
  description: |
    Administrative REST API for Express Gateway - the API gateway built on
    Express.js. The Admin API manages users, applications, credentials,
    scopes, schemas, policies, service endpoints, API endpoints, and
    pipelines. By default it listens on http://localhost:9876 and should
    NOT be exposed publicly without protection - the recommended pattern
    is to expose it through Express Gateway itself behind a key-auth
    policy (Authorization: apikey {keyId}:{keySecret}).
  version: "1.0.0"
  contact:
    name: Express Gateway
    url: https://www.express-gateway.io/docs/
servers:
  - url: http://localhost:9876
    description: Default admin API host
paths:
  /users:
    get:
      summary: List users
      operationId: listUsers
      responses:
        "200":
          description: User collection
    post:
      summary: Create a user
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: User created
  /users/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
        description: Username or user id
    get:
      summary: Get a user
      operationId: getUser
      responses:
        "200": { description: User }
    put:
      summary: Update a user
      operationId: updateUser
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object }
      responses:
        "204": { description: Updated }
    delete:
      summary: Delete a user
      operationId: deleteUser
      responses:
        "204": { description: Deleted }
  /users/{id}/status:
    put:
      summary: Activate or deactivate a user
      operationId: setUserStatus
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum: [active, inactive]
      responses:
        "204": { description: Status updated }
  /apps:
    get:
      summary: List applications
      operationId: listApps
      responses:
        "200": { description: Apps collection }
    post:
      summary: Create an application
      operationId: createApp
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object }
      responses:
        "201": { description: App created }
  /apps/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
    get:
      summary: Get an application
      operationId: getApp
      responses:
        "200": { description: App }
    put:
      summary: Update an application
      operationId: updateApp
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object }
      responses:
        "204": { description: Updated }
    delete:
      summary: Delete an application
      operationId: deleteApp
      responses:
        "204": { description: Deleted }
  /apps/{id}/status:
    put:
      summary: Activate or deactivate an application
      operationId: setAppStatus
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum: [active, inactive]
      responses:
        "204": { description: Status updated }
  /credentials:
    get:
      summary: List credentials
      operationId: listCredentials
      responses:
        "200": { description: Credential collection }
    post:
      summary: Create a credential
      operationId: createCredential
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object }
      responses:
        "201": { description: Credential created }
  /credentials/{consumerId}:
    get:
      summary: List credentials for a consumer (user or app)
      operationId: listConsumerCredentials
      parameters:
        - name: consumerId
          in: path
          required: true
          schema: { type: string }
      responses:
        "200": { description: Credential list }
  /credentials/{type}/{id}:
    parameters:
      - name: type
        in: path
        required: true
        schema:
          type: string
          enum: [key-auth, basic-auth, oauth2, jwt]
      - name: id
        in: path
        required: true
        schema: { type: string }
    get:
      summary: Get a credential by type and id
      operationId: getCredential
      responses:
        "200": { description: Credential }
  /credentials/{type}/{id}/status:
    put:
      summary: Activate or deactivate a credential
      operationId: setCredentialStatus
      parameters:
        - name: type
          in: path
          required: true
          schema: { type: string }
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum: [active, inactive]
      responses:
        "204": { description: Status updated }
  /credentials/{type}/{id}/scopes:
    put:
      summary: Set all scopes on a credential
      operationId: setCredentialScopes
      parameters:
        - name: type
          in: path
          required: true
          schema: { type: string }
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                scopes:
                  type: array
                  items: { type: string }
      responses:
        "204": { description: Scopes updated }
  /credentials/{type}/{id}/scopes/{scope}:
    parameters:
      - name: type
        in: path
        required: true
        schema: { type: string }
      - name: id
        in: path
        required: true
        schema: { type: string }
      - name: scope
        in: path
        required: true
        schema: { type: string }
    put:
      summary: Add a scope to a credential
      operationId: addCredentialScope
      responses:
        "204": { description: Scope added }
    delete:
      summary: Remove a scope from a credential
      operationId: removeCredentialScope
      responses:
        "204": { description: Scope removed }
  /scopes:
    get:
      summary: List scopes
      operationId: listScopes
      responses:
        "200": { description: Scope collection }
    post:
      summary: Create scopes
      operationId: createScopes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                scopes:
                  type: array
                  items: { type: string }
      responses:
        "201": { description: Created }
  /scopes/{scope}:
    parameters:
      - name: scope
        in: path
        required: true
        schema: { type: string }
    get:
      summary: Check whether a scope exists
      operationId: getScope
      responses:
        "200": { description: Scope exists }
        "404": { description: Not found }
    put:
      summary: Create a single scope
      operationId: createScope
      responses:
        "201": { description: Scope created }
    delete:
      summary: Delete a scope
      operationId: deleteScope
      responses:
        "204": { description: Scope deleted }
components:
  securitySchemes:
    KeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: |
        When the Admin API is fronted by Express Gateway with key-auth,
        send "Authorization: apikey {keyId}:{keySecret}".
security:
  - {}
  - KeyAuth: []