the-usher-openapi-spec.yaml

openapi: 3.0.3
info:
  title: The Usher
  description: |
    The Usher server allows a business to authorize an identified user for access to resources or services offered by the business.
  contact:
    name: The Usher Support Page
    url: https://github.com/DMGT-TECH/the-usher-server/issues
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: 2.5.0
externalDocs:
  description: GitHub Repository
  url: https://github.com/DMGT-TECH/the-usher-server
servers:
    - url: https://localhost:3001
    - url: https://o07e9wdidk.execute-api.us-east-1.amazonaws.com/prod
tags:
- name: Server Configuration
  description: This API endpoint allows setting up initial top-level admin personas, who must subsequently access the other endpoints with a valid ID token.
- name: Self APIs
  description: The Self APIs are the main APIs accessed by a client application that a persona has logged in to.
- name: Admin APIs
  description: APIs that provide access to top-level Usher Related data
- name: Client Admin APIs
  description: APIs that provide access to client specific data and operations

#Default security scheme:
security:
  - bearerSelfAuth: []
  - bearerAdminAuth: []
  - bearerClientAdminAuth: []

paths:
  /:
    get:
      operationId: getConfiguration
      'x-swagger-router-controller': 'endpoint_root'
      summary: Returns basic information about this server.
      description: This endpoint returns a JSON object with URIs for an authenticated persona to obtain an access token, and for an API or client application to get this server's JSON Web Key Set (JWKS).
      security:
        #any authenticated user
        - bearerSelfAuth: []
        - bearerAdminAuth: []
      tags:
        - Server Configuration
      responses:
        '200':
          description: On success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerConfig'
        default:
          $ref: '#/components/responses/Default'

  /.well-known/jwks.json:
    get:
      'x-swagger-router-controller': 'endpoint_jwksjson'
      operationId: getJwks
      summary: Returns this server's public key in JSON Web Key Set (JWKS) format.
      tags:
        - Server Configuration
      description: "Returns public key information that can be used to verify the signature on tokens (JWTs) issued by this server."
      security: [] # public endpoint
      responses:
        '200':
          description: On success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Jwks'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          $ref: '#/components/responses/Default'

  /self/clients:
    get:
      operationId: getSelfClients
      'x-swagger-router-controller': 'endpoint_self_clients'
      tags:
        - Self APIs
      security:
        - bearerSelfAuth: []
      summary: List all of the client applications for which currently logged-in persona has at least one role or permission.
      parameters:
        - $ref: '#/components/parameters/userContextParam'
      responses:
        '200':
          description: On success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrayOfSelfClients'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          $ref: '#/components/responses/Default'

  /self/roles:
    get:
      operationId: getSelfRoles
      'x-swagger-router-controller': 'endpoint_self_roles'
      tags:
      - Self APIs
      security:
        - bearerSelfAuth: []
      summary: List entitled roles for the currently logged-in persona for the client application(s).
      description: |-
        Returns the list of roles assigned to this persona and for the group(s) of which they are a member.
      parameters:
        - $ref: '#/components/parameters/clientIdParam'
        - $ref: '#/components/parameters/userContextParam'
        - $ref: '#/components/parameters/payloadFormatParam'
      responses:
        '200':
          description: On success return a list of granted roles.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionOfRoles'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          $ref: '#/components/responses/Default'

  /self/permissions:
    get:
      operationId: getSelfPermissions
      'x-swagger-router-controller': 'endpoint_self_permissions'
      tags:
      - Self APIs
      security:
        - bearerSelfAuth: []
      summary: List entitled permissions for the currently logged-in persona for the client application(s).
      description: |-
        Returns the list of permissions assigned to this persona and for the group(s) of which they are a member. <P>
      parameters:
        - $ref: '#/components/parameters/clientIdParam'
        - $ref: '#/components/parameters/userContextParam'
        - $ref: '#/components/parameters/payloadFormatParam'
      responses:
        '200':
          description: On success return a list of granted permissions.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/CollectionOfPermissions'
                  - $ref: '#/components/schemas/DictionaryOfPermissions'
                  - $ref: '#/components/schemas/ArrayOfPermissions'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          $ref: '#/components/responses/Default'

  /self/scope:
    get:
      'x-swagger-router-controller': 'endpoint_self_scopes'
      tags:
      - Self APIs
      security:
        - bearerSelfAuth: []
      summary: List the granted roles and permissions of the currently logged-in persona for the client application.
      description: |-
        Returns a list of permissions and roles assigned to this persona and for the group(s) of which they are a member.  A smaller scope than what was requested may be returned.
      operationId: listSelfScopes
      parameters:
        - $ref: '#/components/parameters/clientIdParam'
        - $ref: '#/components/parameters/userContextParam'
        - $ref: '#/components/parameters/scopeParam'
        - $ref: '#/components/parameters/payloadFormatParam'
      responses:
        '200':
          description: On success, returns a keyed list of granted entitlements.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/CollectionOfScope'
                  - $ref: '#/components/schemas/DictionaryOfScope'
                  - $ref: '#/components/schemas/ArrayOfScope'
                  - $ref: '#/components/schemas/HierarchyOfScope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          $ref: '#/components/responses/Default'

  /self/token:
    post:
      'x-swagger-router-controller': 'endpoint_self_token'
      operationId: issueSelfToken  #  https://tools.ietf.org/html/rfc7523#section-2.1
      summary: Issue an access token (JWT) containing permissions for the logged-in persona to cover the requested scope.
      description: |
        Returns, in the response body (not in the header), a signed JWT access token with the requested scope, if granted.  May return a smaller scope if fewer entitlements were granted to the persona. Requires a signed access token from the Persona Authorization (identity) server (e.g., Auth0, Cognito, or Azure AD) containing the **sub** claim and possibly a **groups** claim if individual personas are not being managed on this server for the given client application.

        Use this endpoint if the scope need to be passed to a publicly accessible resource server.
      tags:
        - Self APIs
      security:
        - bearerSelfAuth: []
      parameters:
        - $ref: '#/components/parameters/clientIdParam'
        - $ref: '#/components/parameters/userContextParam'
        - $ref: '#/components/parameters/scopeParam'
        - $ref: '#/components/parameters/lifetimeParam'
      responses:
        '200':
          description: Returns a signed JWT containing the following JSON payload.
          headers:
            X-OAuth-Scopes:
              schema:
                type: string
              description: The scopes the token has authorized.
            X-Accepted-OAuth-Scopes:
              schema:
                type: string
              description: The scopes that the action checks for.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          $ref: '#/components/responses/Default'

  /self/refresh_token:
    post:
      'x-swagger-router-controller': 'endpoint_self_refresh_token'
      operationId: issueSelfRefreshToken
      summary: Issue a refreshed access token (JWT) containing permissions for the logged-in persona to cover the requested scope.
      description: "Returns, in the response body (not in the header), a signed JWT access token with the requested scope, if granted.  May return a smaller scope if fewer entitlements were granted to the persona. Requires a non-expired refresh token issued by The Usher's <b>/self/token</b> endpoint."
      tags:
        - Self APIs
      security: [] # public endpoint
      parameters:
        - name: client_id
          description: Unique identifier for the client.
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/EntityNameDef'
        - $ref: '#/components/parameters/userContextParam'
        - name: grant_type
          schema:
            type: string
            maxLength: 13
            minLength: 13
            pattern: '\brefresh_token\b'
          in: query
          required: true
          description: "Value MUST be set to \"refresh_token\""
        - name: refresh_token
          schema:
            type: string
            maxLength: 36
            minLength: 36
            pattern: '^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-4{1}[a-fA-F0-9]{3}-[89abAB]{1}[a-fA-F0-9]{3}-[a-fA-F0-9]{12}$'
          in: query
          required: true
          description: "The refresh_token issued to the client returned in the response from <b>/self/token</b>"
      responses:
        '200':
          description: Returns a signed JWT containing the following JSON payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          $ref: '#/components/responses/Default'

  /roles:
    get:
      'x-swagger-router-controller': 'endpoint_roles'
      operationId: getRoles
      summary: Get a List of Roles for a given Client
      tags:
        - Admin APIs
      security:
        - bearerAdminAuth: []
      parameters:
        - $ref: '#/components/parameters/clientIdQueryParam'
        - $ref: '#/components/parameters/includePermissionsQueryParam'
      responses:
        200:
          description: The List of Roles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionOfRolesWithPermissions'
        400:
          $ref: '#/components/responses/BadRequest'
    post:
      'x-swagger-router-controller': 'endpoint_roles'
      operationId: createRole
      summary: Create a new Role for a given Client
      tags:
        - Admin APIs
      security:
        - bearerAdminAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                client_id:
                  type: string
                name:
                  type: string
                description:
                  type: string
              required:
                - client_id
                - name
      responses:
        201:
          description: The newly created Role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        400:
          $ref: '#/components/responses/BadRequest'

  /roles/{role_key}:
    parameters:
      - $ref: '#/components/parameters/roleKeyPathParam'
    get:
      'x-swagger-router-controller': 'roles/role_key'
      summary: Get a single Role
      operationId: getRole
      tags:
        - Admin APIs
      security:
        - bearerAdminAuth: []
      parameters:
        - $ref: '#/components/parameters/includePermissionsQueryParam'
      responses:
        200:
          description: Return a Role for the given key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleWithPermissions'
        404:
          $ref: '#/components/responses/NotFound'
    patch:
      'x-swagger-router-controller': 'roles/role_key'
      summary: Update a single Role
      operationId: patchRole
      tags:
        - Admin APIs
      security:
        - bearerAdminAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
      responses:
        204:
          description: OK if the Role is updated
        404:
          $ref: '#/components/responses/NotFound'
    delete:
      'x-swagger-router-controller': 'roles/role_key'
      summary: Delete a single Role
      operationId: deleteRole
      tags:
        - Admin APIs
      security:
        - bearerAdminAuth: []
      responses:
        204:
          description: OK if the Role is deleted
        404:
          $ref: '#/components/responses/NotFound'

  /roles/{role_key}/permissions:
    parameters:
      - $ref: '#/components/parameters/roleKeyPathParam'
    get:
      'x-swagger-router-controller': 'roles/permissions'
      operationId: getRolesPermissions
      summary: "Roles: Get list of Permissions"
      tags:
        - Admin APIs
      security:
        - bearerAdminAuth: []
      responses:
        200:
          description: Returns a list of permissions for the subject roles
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArrayOfPermissionObject"
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalError'
        503:
          $ref: '#/components/responses/ServiceUnavailableError'
    put:
      'x-swagger-router-controller': 'roles/permissions'
      operationId: createRolePermissions
      summary: Assigns permissions to the subject role
      tags:
        - Admin APIs
      security:
        - bearerAdminAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              items:
                type: integer
                minimum: 1
      responses:
        204:
          description: Successfully created permissions for the subject role
          headers:
            Location:
              description: The URL to get all the role permissions
              schema:
                type: string
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalError'
        503:
          $ref: '#/components/responses/ServiceUnavailableError'

  /permissions:
    get:
      'x-swagger-router-controller': 'endpoint_permissions'
      operationId: getPermissions
      summary: Get a List of permissions, optionally filtered by name, client_id and client_key
      tags:
        - Admin APIs
      security:
        - bearerAdminAuth: []
      parameters:
        - $ref: '#/components/parameters/nameQueryParam'
        - $ref: '#/components/parameters/clientIdQueryParam'
        - $ref: '#/components/parameters/clientKeyQueryParam'
      responses:
        200:
          description: The List of Permissions
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                    - $ref: '#/components/schemas/PermissionObject'
                    - type: object
                      properties:
                        client_id: 
                          type: string
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        500:
          $ref: '#/components/responses/InternalError'
        503:
          $ref: '#/components/responses/ServiceUnavailableError'

  /personas:
    get:
      'x-swagger-router-controller': 'personas/persona'
      operationId: getPersonas
      summary: Retrieve a list of personas
      parameters:
        - name: key
          in: query
          description: Filter by key (exact match)
          schema:
            type: number
            example: 10
        - name: tenantkey
          in: query
          description: Filter by tenantkey (exact match)
          schema:
            type: number
            example: 10
        - name: tenantname
          in: query
          description: Filter by tenantname (exact match)
          schema:
            type: string
            example: DMGT
        - name: sub_claim
          in: query
          description: Filter by sub_claim (exact match)
          schema:
            type: string
            example: auth0|test-persona
        - name: user_context
          in: query
          description: Filter by user_context (exact match)
          schema:
            type: string
        - name: sort
          in: query
          description: Sort the results by a field
          schema:
            type: string
            example: sub_claim
            enum:
              [
                key,
                tenantkey,
                tenantname,
                sub_claim,
                user_context,
                created_at,
                updated_at,
              ]
        - name: order
          in: query
          description: Specify the sort order (asc or desc)
          schema:
            type: string
            enum: [asc, desc]
      tags:
        - Admin APIs
      security:
        - bearerAdminAuth: []
      responses:
        200:
          description: Returns a list of personas
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Persona"
                  properties:
                    tenantname:
                      type: string
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        500:
          $ref: '#/components/responses/InternalError'
        503:
          $ref: '#/components/responses/ServiceUnavailableError'
    post:
      'x-swagger-router-controller': 'personas/persona'
      summary: Create a single persona
      operationId: createPersona
      tags:
        - Admin APIs
      security:
        - bearerAdminAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tenant_key:
                  type: number
                  minimum: 1
                  format: int32
                sub_claim:
                  type: string
                user_context:
                  type: string
              required:
                - tenant_key
                - sub_claim
      responses:
        201:
          description: Returns the created persona
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Persona"
        400:
          $ref: '#/components/responses/BadRequest'
        409:
          $ref: '#/components/responses/Conflict'
        500:
          $ref: '#/components/responses/InternalError'
        503:
          $ref: '#/components/responses/ServiceUnavailableError'

  /personas/{persona_key}:
    get:
      'x-swagger-router-controller': 'personas/persona'
      operationId: getPersona
      summary: Get a Persona by persona_key
      parameters:
      - $ref: '#/components/parameters/personaKeyPathParam'
      tags:
        - Admin APIs
      security:
        - bearerAdminAuth: []
      responses:
        200:
          description: Returns a persona
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Persona"
                properties:
                  tenantname:
                    type: string
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalError'
        503:
          $ref: '#/components/responses/ServiceUnavailableError'
    delete:
      'x-swagger-router-controller': 'personas/persona'
      operationId: deletePersona
      summary: Deletes the subject persona
      parameters:
      - $ref: '#/components/parameters/personaKeyPathParam'
      tags:
        - Admin APIs
      security:
        - bearerAdminAuth: []
      responses:
        204:
          description: Empty response on success
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalError'
        503:
          $ref: '#/components/responses/ServiceUnavailableError'

  /personas/{persona_key}/permissions:
    get:
      'x-swagger-router-controller': 'personas/permissions'
      operationId: getPersonaPermissions
      summary: Get a list of permissions assigned to the given Persona
      parameters:
      - $ref: '#/components/parameters/personaKeyPathParam'
      tags:
        - Admin APIs
      security:
        - bearerAdminAuth: []
      responses:
        200:
          description: Returns a list of permissions for the subject persona
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArrayOfPermissionObject"
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalError'
        503:
          $ref: '#/components/responses/ServiceUnavailableError'
    put:
      'x-swagger-router-controller': 'personas/permissions'
      operationId: createPersonaPermissions
      summary: Assigns permissions to the subject persona
      parameters:
        - $ref: '#/components/parameters/personaKeyPathParam'
      tags:
        - Admin APIs
      security:
        - bearerAdminAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              items:
                type: integer
                minimum: 1
      responses:
        204:
          description: Successfully created permissions for the subject persona
          headers:
            Location:
              description: The URL to get all the persona permissions
              schema:
                type: string
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalError'
        503:
          $ref: '#/components/responses/ServiceUnavailableError'

  /personas/{persona_key}/permissions/{permission_key}:
    delete:
      'x-swagger-router-controller': 'personas/permissions'
      operationId: deletePersonaPermission
      summary: Removes a permission for subject persona
      parameters:
      - $ref: '#/components/parameters/personaKeyPathParam'
      - $ref: '#/components/parameters/permissionKeyPathParam'
      tags:
        - Admin APIs
      security:
        - bearerAdminAuth: []
      responses:
        204:
          description: Empty response on success
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalError'
        503:
          $ref: '#/components/responses/ServiceUnavailableError'

  /personas/{persona_key}/roles:
    get:
      'x-swagger-router-controller': 'personas/roles'
      operationId: getPersonaRoles
      summary: Get a list of roles assigned to the given Persona
      parameters:
        - $ref: '#/components/parameters/personaKeyPathParam'
        - $ref: '#/components/parameters/includePermissionsQueryParam'
      tags:
        - Admin APIs
      security:
        - bearerAdminAuth: []
      responses:
        200:
          description: Returns a list of roles for the subject persona
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/RoleWithPermissions"
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalError'
        503:
          $ref: '#/components/responses/ServiceUnavailableError'
    put:
      'x-swagger-router-controller': 'personas/roles'
      operationId: createPersonaRoles
      summary: Assigns roles to the subject persona
      parameters:
        - $ref: '#/components/parameters/personaKeyPathParam'
      tags:
        - Admin APIs
      security:
        - bearerAdminAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              items:
                type: integer
                minimum: 1
      responses:
        204:
          description: Successfully created roles for the subject persona
          headers:
            Location:
              description: The URL to get all the persona roles
              schema:
                type: string
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalError'
        503:
          $ref: '#/components/responses/ServiceUnavailableError'

  /personas/{persona_key}/roles/{role_key}:
    delete:
      'x-swagger-router-controller': 'personas/roles'
      operationId: deletePersonaRole
      summary: Removes a role for subject persona
      parameters:
      - $ref: '#/components/parameters/personaKeyPathParam'
      - $ref: '#/components/parameters/roleKeyPathParam'
      tags:
        - Admin APIs
      security:
        - bearerAdminAuth: []
      responses:
        204:
          description: Empty response on success
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalError'
        503:
          $ref: '#/components/responses/ServiceUnavailableError'

  /clients:
    get:
      'x-swagger-router-controller': 'clients/index'
      operationId: getClients
      summary: Get a list of Clients
      tags:
        - Client Admin APIs
      security:
        - bearerAdminAuth: []
      responses:
        200:
          description: Returns a list of clients
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Client"
        401:
          $ref: '#/components/responses/Unauthorized'
        500:
          $ref: '#/components/responses/InternalError'
        503:
          $ref: '#/components/responses/ServiceUnavailableError'

    post:
      'x-swagger-router-controller': 'clients/index'
      operationId: createClient
      summary: Create a new Client
      tags:
        - Client Admin APIs
      security:
        - bearerAdminAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tenant_name:
                  type: string
                client_id:
                  type: string
                  maxLength: 50
                  pattern: ^[a-z0-9-_]*$
                name:
                  type: string
                  maxLength: 50
                description:
                  type: string
                secret:
                  type: string
              required:
                - tenant_name
                - client_id
                - name
      responses:
        201:
          description: The newly created Client object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Client'
        400:
          $ref: '#/components/responses/BadRequest'

  /clients/{client_id}:
    parameters:
      - $ref: '#/components/parameters/clientIdPathParam'
    get:
      'x-swagger-router-controller': 'clients/index'
      operationId: getClient
      summary: Get a single Client
      tags:
        - Client Admin APIs
      security:
        - bearerAdminAuth: []
        - bearerClientAdminAuth: []
      responses:
        200:
          description: Return details for the given Client object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Client'
        404:
          $ref: '#/components/responses/NotFound'
    delete:
      'x-swagger-router-controller': 'clients/index'
      operationId: deleteClient
      summary: Delete a Client and associated data
      description: In addition to deleting the Client, any roles belonging to this Client
        are also deleted.
      tags:
        -  Client Admin APIs
      security:
        - bearerAdminAuth: []
        - bearerClientAdminAuth: []
      responses:
        204:
          description: Successfully deleted the Client and data
        404:
          $ref: '#/components/responses/NotFound'
    put:
      'x-swagger-router-controller': 'clients/index'
      operationId: updateClient
      summary: Update a client
      tags:
        - Client Admin APIs
      security:
        - bearerAdminAuth: []
        - bearerClientAdminAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Client'
      responses:
        200:
          description: Return the details of updated client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Client'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        409:
          $ref: '#/components/responses/Conflict'
        500:
          $ref: '#/components/responses/InternalError'
        503:
          $ref: '#/components/responses/ServiceUnavailableError'

  /clients/{client_id}/roles:
    parameters:
      - $ref: '#/components/parameters/clientIdPathParam'
      - $ref: '#/components/parameters/includePermissionsQueryParam'
    get:
      'x-swagger-router-controller': 'clients/roles'
      operationId: listClientRoles
      summary: Return a list of Roles for the given Client
      tags:
        - Client Admin APIs
      security:
        - bearerAdminAuth: []
        - bearerClientAdminAuth: []
      responses:
        200:
          description: Return list of Roles for given Client object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionOfRolesWithPermissions'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalError'
        503:
          $ref: '#/components/responses/ServiceUnavailableError'
    post:
      'x-swagger-router-controller': 'clients/roles'
      operationId: createClientRole
      summary: Create a new Role for the given Client
      tags:
        - Client Admin APIs
      security:
        - bearerAdminAuth: []
        - bearerClientAdminAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
              required:
                - name
      responses:
        201:
          description: Return the newly created Role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        404:
          $ref: '#/components/responses/NotFound'

  /clients/{client_id}/permissions:
    parameters:
    - $ref: '#/components/parameters/clientIdPathParam'
    get:
      'x-swagger-router-controller': 'clients/permissions'
      operationId: getClientPermissions
      summary: Get a list of permissions for a client
      tags:
        - Client Admin APIs
      security:
        - bearerAdminAuth: []
        - bearerClientAdminAuth: []
      responses:
        200:
          description: List of permissions for a client
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                    - $ref: '#/components/schemas/PermissionObject'
                    - type: object
                      properties:
                        client_id: 
                          type: string
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalError'
        503:
          $ref: '#/components/responses/ServiceUnavailableError'
    post:
      'x-swagger-router-controller': 'clients/permissions'
      summary: Create a new permission for the given client
      operationId: createPermission
      tags:
        - Client Admin APIs
      security:
        - bearerAdminAuth: []
        - bearerClientAdminAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  $ref: '#/components/schemas/EntityNameDef'
                description:
                  $ref: '#/components/schemas/EntityDescriptionDef'
              required:
                - name
              additionalProperties: false
      responses:
        201:
          description: Returns the created permission
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermissionObject"
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        409:
          $ref: '#/components/responses/Conflict'
        500:
          $ref: '#/components/responses/InternalError'
        503:
          $ref: '#/components/responses/ServiceUnavailableError'

  /sessions:
    delete:
      operationId: invalidateSession
      'x-swagger-router-controller': 'endpoint_invalidate_session'
      summary: Invalidate an ongoing session for a persona.
      tags:
        - Admin APIs
      security:
        - bearerAdminAuth: []
      parameters:
        - name: sub
          in: query
          schema:
            $ref: '#/components/schemas/EntityNameDef'
          required: true
        - name: ucx
          description: Optional user context
          in: query
          schema:
            type: string
            nullable: true # Can't use shared schema with nullable in 3.0.x
            maxLength: 50
          required: false
        - name: iss
          in: query
          schema:
            type: string
          required: true
      responses:
        '200':
          description: 'Success: The session was invalidated.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        default:
          $ref: '#/components/responses/Default'

components:

  parameters:
  #---------------------
    clientIdPathParam:
      name: client_id
      description: Unique identifier for client.
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/EntityNameDef'
      examples:
        Client ID:
          value: datalake-api
    # client_id
    clientIdParam:
      name: client_id
      description: Unique identifier for the client.
      in: header
      required: true
      schema:
        $ref: '#/components/schemas/EntityNameDef'
      examples:
        Example 1 (client application ID):
          value: Newsletter+Application
        Example 2 (top-level):
          value: the-usher
        Example 3 (all client applications where persona has a role):
          value: "*"
    clientIdQueryParam:
      name: client_id
      description: Filter by client_id
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/EntityNameDef'
    clientKeyQueryParam:
      name: client_key
      description: Filter by client_key
      in: query
      required: false
      schema:
        type: integer
    nameQueryParam:
      name: name
      description: Filter by name
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/EntityNameDef'
    includePermissionsQueryParam:
      name: include_permissions
      in: query
      description: Includes permissions for each role
      required: false
      schema:
        type: boolean
        example: true
    roleKeyPathParam:
      name: role_key
      description: The unique role identifier
      in: path
      required: true
      schema:
        type: integer
    personaKeyPathParam:
      name: persona_key
      description: The unique persona identifier
      in: path
      required: true
      schema:
        type: integer
    permissionKeyPathParam:
      name: permission_key
      description: The unique permission identifier
      in: path
      required: true
      schema:
        type: integer
        minimum: 1
    # user_context
    userContextParam:
      name: user_context
      in: header
      required: false
      schema:
        $ref: '#/components/schemas/EntityNameDef'
    # scope
    scopeParam:
      name: scope
      description: |-
        Requested scope (optional). Space-separated list of permissions the client application wishes to have granted for this persona.
        If this is not specified, then all entitled permissions are **granted**.
      in: query
      required: false
      schema:
        type: string
        pattern: '[0-9a-zA-Z-_ :]+'
      examples:
        Example 1 (Scope):
          value: app:read app:create
    # lifetime
    lifetimeParam:
      name: lifetime
      description: How long this token should be valid, in seconds.
      in: query
      required: false
      schema:
        type: string
        pattern: '[0-9]{1,5}'
    # payload format
    payloadFormatParam:
      name: payload_format
      description: The JSON format for returning the payload
      in: header
      required: false
      schema:
        type: string
        enum:
          - dictionary
          - array
          - collection
          - hierarchy

  schemas:
#---------------------
# Entities

# BASE DEFINITIONS
    EntityNameDef:
      type: string
      maxLength: 50
      pattern: '[0-9a-zA-Z-_:\*]{1,50}'
    EntityDescriptionDef:
      type: string
      maxLength: 100
      pattern: '[0-9a-zA-Z-_:\*]{1,100}'

    Role:
      type: object
      properties:
        key:
          type: integer
          minimum: 1
          format: int32
        clientkey:
          type: integer
          minimum: 1
          format: int32
        name:
          $ref: '#/components/schemas/EntityNameDef'
        description:
          type: string
          nullable: true
          maxLength: 100
      required:
        - key
        - clientkey
        - name
      example:
        key: 10
        name: usher:admin
        clientkey: fake-client
      
    RoleWithPermissions:
      allOf:
      - $ref: '#/components/schemas/Role'
      - type: object
        properties:
          permissions: 
            $ref: '#/components/schemas/ArrayOfPermissionObject'

    CollectionOfRoles:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Role'

    CollectionOfRolesWithPermissions:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/RoleWithPermissions'

    Permission:
      type: object
      properties:
        permission:
          $ref: '#/components/schemas/EntityNameDef'
        description:
          $ref: '#/components/schemas/EntityDescriptionDef'
      required:
        - permission

    PermissionObject:
      type: object
      properties:
        key:
          type: integer
          minimum: 1
          format: int32
        clientkey:
          type: integer
          minimum: 1
          format: int32
        name:
          $ref: '#/components/schemas/EntityNameDef'
        description:
          $ref: '#/components/schemas/EntityDescriptionDef'
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - key
        - name
        - clientkey

    ArrayOfPermissions:
      type: array
      items:
        type: array
        items:
          $ref: '#/components/schemas/EntityNameDef'

    CollectionOfPermissions:
      type: array
      items:
        $ref: '#/components/schemas/Permission'

    ArrayOfPermissionObject:
      type: array
      items:
        $ref: '#/components/schemas/PermissionObject'

    DictionaryOfPermissions:
      type: object
      additionalProperties: false
      properties:
        permission:
          type: array
          items:
            $ref: '#/components/schemas/EntityNameDef'

    Client:
      type: object
      properties:
        key:
          type: integer
          minimum: 1
          format: int32
        client_id:
          $ref: '#/components/schemas/EntityNameDef'
        name:
          $ref: '#/components/schemas/EntityNameDef'
        description:
          type: string
        secret:
          type: string
          maxLength: 50
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - client_id
        - name
      example:
        key: 1
        client_id: newsletter-app
        name: The Newsletter App
        description: Application for reading the newsletter on a mobile device
        secret: secretphraseused
        created_at: '2024-08-13T20:59:37.072Z'
        updated_at: '2024-08-13T20:59:37.072Z'

    ArrayOfSelfClients:
      type: array
      items:
        type: object
        properties:
          client_id:
            $ref: '#/components/schemas/EntityNameDef'
          clientname:
            $ref: '#/components/schemas/EntityNameDef'
      example:
        - client_id: the-usher
          clientname: The Usher
        - client_id: client-app1
          clientname: Client Application 1
        - client_id: client-app2
          clientname: Client Application 2

    Persona:
      type: object
      properties:
        key:
          type: integer
          minimum: 1
          format: int32
        tenantkey:
          type: integer
          minimum: 1
          format: int32
        user_context:
          type: string
          nullable: true
        sub_claim:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - key
        - tenantkey
        - sub_claim

# SCOPE
#---------------------
    ArrayOfScope:
      type: array
      items:
        type: array
        items: {}
#---------------------
    CollectionOfScope:
      type: array
      items:
        type: object
        additionalProperties: false
        properties:
          role:
            $ref: '#/components/schemas/EntityNameDef'
          permission:
            type: array
            items:
              $ref: '#/components/schemas/EntityNameDef'
#---------------------
    DictionaryOfScope:
      type: object
      additionalProperties: false
      properties:
        role:
          type: array
          items:
            $ref: '#/components/schemas/EntityNameDef'
        permission:
          type: array
          items:
            type: array
            items:
              $ref: '#/components/schemas/EntityNameDef'
#---------------------
    HierarchyOfScope:
      type: array
      items:
          type: object
          properties:
            role:
              $ref: '#/components/schemas/EntityNameDef'
            permission:
              type: array
              items:
                $ref: '#/components/schemas/EntityNameDef'
# TOKEN
#---------------------
    Token:
      type: object
      additionalProperties: false
      properties:
          token_type:
            type: string
          access_token:
            type: string
          refresh_token:
            type: string
          expires_in:
            type: integer
            format: int32
      required:
        - token_type
        - access_token
        - refresh_token
        - expires_in
      example:
        "Example Access Token":
          token_type: "Bearer"
          access_token: "OPAQUE TOKEN"
          refresh_token: "2550f150-b75a-459b-8d98-19961b651892"
          expires_in: 3600

# KEYS
#---------------------
    Key:
      type: object
      additionalProperties: false
      properties:
        kty:
          type: string
        kid:
          type: string
        use:
          type: string
        alg:
          type: string
        n:
          type: string
        e:
          type: string

# JWKS
#---------------------
    Jwks:
      type: object
      additionalProperties: false
      properties:
        keys:
          type: array
          maxItems: 1
          items:
            $ref: '#/components/schemas/Key'
      required:
        - keys
      example:
        {"keys":[
          {
            "kid":"2020-02-12A",
            "kty":"RSA",
            "alg":"RS256",
            "use":"sig",
            "key_ops": "verify",
            "n":"2kVO54uvOhDfpn3SUrWA-iaVhlBry6MgiUImReN_4jpYf-aBA-f0mgDmF-708bspPluzGjG6KRDg0UtGl3PpndyZk9PDAxgHbdzY6bRwHLchxB7RW4NYF4CgScqAQ38HbFmUQlQOj-V_Xadb_PSUoV-acM0aGjBig-t5mRSvdoedg1nF9Lt4eJ-1DV0lw-xS5XHKzzS0s9aJtwUuR38Iem3tF5k_o71cvnbKM9T_kQhASn9RGloS9LXgjWsChNiyP0KgMLINdYo3x-hdUbpZCiit0b3fvJQIsX2BXeOcgtEGuTNcxYPdbLMD5wA7TLzSFWrkJ0ZemVAuSilOyfaHdw",
            "e":"AQAB",
        }]}

# CONFIG
#---------------------
    ServerConfig:
      type: object
      additionalProperties: false
      properties:
        token_endpoint:
          type: string
        jwks_uri:
          type: string
        the-usher-package-version:
          type: string
          maxLength: 40
          pattern: '^[\d]+\.[\d]+\.[\d]+$'
      required:
        - token_endpoint
        - jwks_uri
        - the-usher-package-version
      example:
        token_endpoint: $SERVER_URL/self/token
        jwks_uri: $SERVER_URL/.well-known/jwks.json
        the-usher-package-version: 1.2.0

    # RESPONSE SCHEMAS
    #---------------------
    Success:
      type: object
      additionalProperties: false
      properties:
        code:
          type: integer
          minimum: 200
          maximum: 299
        message:
          type: string
      required:
        - code
        - message

    # Error response body
    Error:
      type: object
      additionalProperties: false
      properties:
        code:
          type: integer
          minimum: 100
          maximum: 600
        message:
          type: string
          pattern: '.'
      required:
        - code
        - message

  securitySchemes:
    bearerSelfAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    bearerAdminAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    bearerClientAdminAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  responses:

    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 400
            message: Bad Request

    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 401
            message: Unauthorized

    Forbidden:
      description: The server understood the request but refuses to authorize it
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 403
            message: Forbidden

    NotFound:
      description: The specified resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 404
            message: Not Found

    Conflict:
      description: Resource already exists
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 409
            message: Resource already exists!

    UnsupportedMediaType:
      description: The request entity has a media type which the server or resource does not support
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 415
            message: Unsupported Media Type

    TooManyRequests:
      description: The user has sent too many requests in a given amount of time
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 429
            message: Too Many Requests

    InternalError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 500
            message: Internal Error!

    ServiceUnavailableError:
      description: Service Unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 503
            message: Service Unavailable!

    Default:
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'