openapi.yml

openapi: 3.0.0
info:
  title: Common Fate
  version: "1.0"
  contact:
    name: Common Fate
    url: "https://commonfate.io"
  description: Common Fate API
servers:
  - url: "http://localhost:8080"
paths:
  /api/v1/access-rules:
    get:
      summary: List Access Rules
      tags:
        - End User
      responses:
        "200":
          $ref: "#/components/responses/ListAccessRulesResponse"
      operationId: user-list-access-rules
      description: Get all access rules as an end user.
  "/api/v1/access-rules/{ruleId}":
    get:
      summary: Get Access Rule
      tags:
        - End User
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RequestAccessRule"
        "401":
          $ref: "#/components/responses/ErrorResponse"
        "404":
          $ref: "#/components/responses/ErrorResponse"
      operationId: user-get-access-rule
      description: |-
        Get details for an Access Rule.

        End users are only able to view Access Rules if they are a member of the group the rule relates to, or if they are designated as an approver for the Access Rule. If a user doesn't meet these conditions, a HTTP401 unauthorized error is returned.
    parameters:
      - schema:
          type: string
        name: ruleId
        in: path
        required: true
  "/api/v1/access-rules/{ruleId}/approvers":
    get:
      summary: List Access Rule approvers
      tags:
        - End User
      responses:
        "200":
          $ref: "#/components/responses/ListAccessRuleApproversResponse"
        "401":
          $ref: "#/components/responses/ErrorResponse"
        "404":
          $ref: "#/components/responses/ErrorResponse"
      operationId: user-get-access-rule-approvers
      description: |-
        Get the approvers for an access rule. 
        This returns a list of user IDs.

        End users are only able to view Access Rules if they are a member of the group the rule relates to, or if they are designated as an approver for the Access Rule. If a user doesn't meet these conditions, a HTTP401 unauthorized error is returned.
    parameters:
      - schema:
          type: string
        name: ruleId
        in: path
        required: true
  /api/v1/requests:
    get:
      summary: List my requests
      tags:
        - End User
      responses:
        "200":
          $ref: "#/components/responses/ListRequestsResponse"
      operationId: user-list-requests
      description: |-
        List requests.
        The reviewer query param allows you to fetch requests which you can review.
      parameters:
        - schema:
            type: string
            enum:
              - APPROVED
              - DECLINED
              - CANCELLED
              - PENDING
          in: query
          name: status
          description: omit this param to view all results
        - schema:
            type: boolean
          in: query
          name: reviewer
          description: "show requests that the user is a reviewer for, rather than requests that the user has made themselves"
        - schema:
            type: string
          in: query
          name: nextToken
          description: encrypted token containing pagination info
    parameters: []
    post:
      summary: Create a request
      operationId: user-create-request
      responses:
        "200":
          $ref: "#/components/responses/CreateRequestResponse"
      description: |-
        Make a request to access something.

        Users must specify an Access Rule when making a request. Users are authorized to make a request if they are in a group that the Access Rule references. Otherwise, a HTTP 404 response will be returned.
      requestBody:
        $ref: "#/components/requestBodies/CreateRequestRequest"
      tags:
        - End User
  /api/v1/requests/upcoming:
    get:
      summary: Your GET endpoint
      tags:
        - End User
      responses:
        "200":
          $ref: "#/components/responses/ListRequestsResponse"
      operationId: user-list-requests-upcoming
      description: Display pending requests and approved requests that are currently active or scheduled to begin some time in future.
      parameters:
        - schema:
            type: string
          in: query
          description: encrypted token containing pagination info
          name: nextToken
  /api/v1/requests/past:
    get:
      summary: Your GET endpoint
      tags:
        - End User
      responses:
        "200":
          $ref: "#/components/responses/ListRequestsResponse"
      operationId: user-list-requests-past
      description: |
        Display show cancelled, expired, and revoked requests.
      parameters:
        - schema:
            type: string
          in: query
          name: nextToken
          description: encrypted token containing pagination info
  "/api/v1/requests/{requestId}":
    parameters:
      - schema:
          type: string
        name: requestId
        in: path
        required: true
    get:
      summary: Get a request
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RequestDetail"
        "404":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      operationId: user-get-request
      description: |-
        Returns a HTTP401 response if the user is not the requestor or a reviewer.


        Use /api/v1/admin/requests/{requestId} as an administrator to view information for requests not made by the current user (note: requires that the user is a Common Fate administrator).
      tags:
        - End User
      parameters: []
  "/api/v1/requests/{requestId}/events":
    parameters:
      - schema:
          type: string
        name: requestId
        in: path
        required: true
    get:
      summary: List request events
      responses:
        "200":
          $ref: "#/components/responses/ListRequestEventsResponse"
        "401":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      operationId: user-list-request-events
      description: |
        Returns a HTTP401 response if the user is not the requestor or a reviewer.
      tags:
        - End User
      parameters: []
  "/api/v1/requests/{requestId}/review":
    parameters:
      - schema:
          type: string
        name: requestId
        in: path
        required: true
    post:
      summary: Review a request
      operationId: user-review-request
      responses:
        "200":
          $ref: "#/components/responses/ReviewResponse"
      tags:
        - End User
      description: "Review an access request made by a user. The reviewing user must be an approver for a request. Users cannot review their own requests, even if they are an approver for the Access Rule."
      requestBody:
        $ref: "#/components/requestBodies/ReviewRequest"
  "/api/v1/requests/{requestId}/cancel":
    parameters:
      - schema:
          type: string
        name: requestId
        in: path
        required: true
    post:
      summary: Cancel a request
      operationId: user-cancel-request
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties: {}
        "400":
          $ref: "#/components/responses/ErrorResponse"
        "404":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      tags:
        - End User
      description: Users can cancel an access request that they have created while it is in the PENDING state.
  "/api/v1/requests/{requestid}/revoke":
    parameters:
      - schema:
          type: string
        name: requestid
        in: path
        required: true
    post:
      summary: Revoke an active request
      operationId: user-revoke-request
      responses:
        "200":
          description: OK
        "400":
          $ref: "#/components/responses/ErrorResponse"
        "404":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      tags:
        - End User
      description: "Admins and approvers can revoke access previously approved. Effective immediately "
  "/api/v1/requests/{requestId}/access-instructions":
    parameters:
      - schema:
          type: string
        name: requestId
        in: path
        required: true
    get:
      summary: Get Access Instructions
      tags:
        - End User
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: ./accesshandler/openapi.yml#/components/schemas/AccessInstructions
      operationId: user-get-access-instructions
      description: |-
        Get access instructions for a request.

        Returns information on how to access the role or resource.
  "/api/v1/requests/{requestId}/access-token":
    parameters:
      - schema:
          type: string
        name: requestId
        in: path
        required: true
    get:
      summary: Get Access Token
      tags:
        - End User
      responses:
        "200":
          $ref: "#/components/responses/AccessTokenResponse"
        "404":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      operationId: user-get-access-token
      description: |-
        Get access token for a request.

        Returns information on how to access the role or resource.
  "/api/v1/users/{userId}":
    parameters:
      - schema:
          type: string
        name: userId
        in: path
        required: true
    get:
      summary: Get a user
      tags:
        - End User
      operationId: user-get-user
      description: Returns a Common Fate user.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "401":
          description: Unauthorized
        "404":
          description: Not Found
  /api/v1/users/me:
    get:
      summary: Get details for the current user
      tags:
        - End User
      operationId: user-get-me
      description: Returns information about the currently logged in user.
      responses:
        "200":
          $ref: "#/components/responses/AuthUserResponse"
        "401":
          description: Unauthorized
  /api/v1/admin/access-rules:
    get:
      summary: List Access Rules
      tags:
        - Admin
      responses:
        "200":
          $ref: "#/components/responses/ListAccessRulesDetailResponse"
      operationId: admin-list-access-rules
      description: List all access rules
      parameters:
        - schema:
            type: string
            enum:
              - ACTIVE
              - ARCHIVED
          in: query
          name: status
          description: Filter Access Rules by a particular status.
        - schema:
            type: string
          in: query
          name: nextToken
          description: encrypted token containing pagination info
    post:
      summary: Create Access Rule
      operationId: admin-create-access-rule
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccessRuleDetail"
        "400":
          $ref: "#/components/responses/ErrorResponse"
        "401":
          $ref: "#/components/responses/ErrorResponse"
      description: Create an access rule
      requestBody:
        $ref: "#/components/requestBodies/CreateAccessRuleRequest"
      tags:
        - Admin
    parameters: []
  "/api/v1/admin/access-rules/{ruleId}":
    get:
      summary: Get Access Rule
      tags:
        - Admin
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccessRuleDetail"
        "401":
          $ref: "#/components/responses/ErrorResponse"
        "404":
          $ref: "#/components/responses/ErrorResponse"
      operationId: admin-get-access-rule
      description: Get an Access Rule.
    parameters:
      - schema:
          type: string
        name: ruleId
        in: path
        required: true
    put:
      summary: Update Access Rule
      operationId: admin-update-access-rule
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccessRuleDetail"
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
        "404":
          description: Not Found
        "500":
          description: Internal Server Error
      requestBody:
        $ref: "#/components/requestBodies/CreateAccessRuleRequest"
      description: Updates an Access Rule. Updating a rule creates a new version.
      tags:
        - Admin
  "/api/v1/admin/access-rules/{ruleId}/archive":
    parameters:
      - schema:
          type: string
        name: ruleId
        in: path
        required: true
    post:
      summary: Archive Access Rule
      operationId: admin-archive-access-rule
      tags:
        - Admin
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccessRuleDetail"
        "401":
          $ref: "#/components/responses/ErrorResponse"
        "404":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      description: |-
        Marks an access rule as archived.
        Any pending requests for this access rule will be cancelled.
  "/api/v1/admin/access-rules/{ruleId}/versions":
    get:
      summary: Get Access Rule version history
      tags:
        - Admin
      responses:
        "200":
          $ref: "#/components/responses/ListAccessRulesDetailResponse"
        "401":
          description: Unauthorized
        "404":
          description: Not Found
      operationId: admin-get-access-rule-versions
      description: Returns a version history for a particular Access Rule.
    parameters:
      - schema:
          type: string
        name: ruleId
        in: path
        required: true
  "/api/v1/admin/access-rules/{ruleId}/versions/{version}":
    get:
      summary: Get Access Rule Version
      tags:
        - Admin
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccessRuleDetail"
        "401":
          $ref: "#/components/responses/ErrorResponse"
        "404":
          $ref: "#/components/responses/ErrorResponse"
      operationId: admin-get-access-rule-version
      description: Returns a specific version for an Access Rule.
    parameters:
      - schema:
          type: string
        name: ruleId
        in: path
        required: true
      - schema:
          type: string
        name: version
        in: path
        required: true
  /api/v1/admin/deployment/version:
    get:
      summary: Get deployment version details
      tags:
        - Admin
      responses:
        "200":
          $ref: "#/components/responses/DeploymentVersionResponse"
      operationId: admin-get-deployment-version
      description: Returns the version information
    parameters: []
  /api/v1/admin/requests:
    get:
      summary: Your GET endpoint
      tags:
        - Admin
      responses:
        "200":
          $ref: "#/components/responses/ListRequestsResponse"
      operationId: admin-list-requests
      description: Return a list of all requests
      parameters:
        - schema:
            type: string
            enum:
              - APPROVED
              - DECLINED
              - CANCELLED
              - PENDING
          in: query
          description: omit this param to view all results
          name: status
        - schema:
            type: string
          in: query
          name: nextToken
          description: encrypted token containing pagination info
  "/api/v1/admin/requests/{requestId}":
    parameters:
      - schema:
          type: string
        name: requestId
        in: path
        required: true
    get:
      summary: Get a request
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RequestDetail"
        "404":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      operationId: admin-get-request
      description: Returns an access request.
      tags:
        - End User
      parameters: []
  "/api/v1/admin/users/{userId}":
    parameters:
      - schema:
          type: string
        name: userId
        in: path
        required: true
    post:
      summary: Update User
      operationId: admin-update-user
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          $ref: "#/components/responses/ErrorResponse"
        "401":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      description: Update a user including group membership
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                groups:
                  type: array
                  items:
                    type: string
              required:
                - groups
      tags:
        - Admin
  /api/v1/admin/users:
    get:
      summary: Returns a list of users
      tags:
        - Admin
      responses:
        "200":
          $ref: "#/components/responses/ListUserResponse"
      operationId: admin-list-users
      description: Fetch a list of users
      parameters:
        - schema:
            type: string
          in: query
          name: nextToken
          description: encrypted token containing pagination info
    post:
      summary: Create User
      operationId: admin-create-user
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          $ref: "#/components/responses/ErrorResponse"
        "401":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      description: Create new user in the Cognito user pool if it is enabled.
      requestBody:
        $ref: "#/components/requestBodies/CreateUserRequest"
      tags:
        - Admin
  /api/v1/admin/groups:
    get:
      summary: List groups
      tags:
        - Admin
      operationId: admin-list-groups
      description: Lists all active groups
      responses:
        "200":
          $ref: "#/components/responses/ListGroupsResponse"
      parameters:
        - schema:
            type: string
          in: query
          name: nextToken
          description: encrypted token containing pagination info
        - schema:
            type: string
            enum:
              - INTERNAL
              - EXTERNAL
          in: query
          name: source
    parameters: []
    post:
      summary: Create Group
      operationId: admin-create-group
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Group"
        "400":
          $ref: "#/components/responses/ErrorResponse"
        "401":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      description: Create new group in the Cognito user pool if it is enabled.
      requestBody:
        $ref: "#/components/requestBodies/CreateGroupRequest"
      tags:
        - Admin
  "/api/v1/admin/groups/{groupId}":
    parameters:
      - schema:
          type: string
        name: groupId
        in: path
        required: true
    get:
      summary: Get Group Details
      tags:
        - Admin
      operationId: admin-get-group
      description: Returns information for a group.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Group"
    put:
      summary: Update Group
      operationId: admin-update-group
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Group"
        "400":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      requestBody:
        $ref: "#/components/requestBodies/CreateGroupRequest"
      description: Update a group
      tags:
        - Admin
    delete:
      summary: Delete Group
      operationId: admin-delete-group
      tags:
        - Admin
      responses:
        "200":
          description: OK
        "404":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      description: Delete an internal group
  /api/v1/admin/providers:
    get:
      summary: List providers
      tags:
        - Admin
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Provider"
        "401":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      operationId: admin-list-providers
      description: List providers
    parameters: []
  "/api/v1/admin/providers/{providerId}":
    get:
      summary: List providers
      tags:
        - Admin
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Provider"
        "401":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      operationId: admin-get-provider
      description: Get provider by id
    parameters:
      - schema:
          type: string
        name: providerId
        in: path
        required: true
  "/api/v1/admin/providers/{providerId}/args":
    parameters:
      - schema:
          type: string
        name: providerId
        in: path
        required: true
    get:
      summary: Get provider arg schema
      tags:
        - Admin
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: ./accesshandler/openapi.yml#/components/schemas/ArgSchema
        "401":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      operationId: admin-get-provider-args
      description: Gets the argSchema describing the args for this provider
  "/api/v1/admin/providers/{providerId}/args/{argId}/options":
    parameters:
      - schema:
          type: string
        name: providerId
        in: path
        required: true
      - schema:
          type: string
        name: argId
        in: path
        required: true
    get:
      summary: List provider arg options
      tags:
        - Admin
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: ./accesshandler/openapi.yml#/components/schemas/ArgOptions
        "401":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      operationId: admin-list-provider-arg-options
      description: "Returns the options for a particular Access Provider argument. The options may be cached. To refresh the cache, pass the `refresh` query parameter."
      parameters:
        - schema:
            type: boolean
          in: query
          name: refresh
          description: invalidate the cache and refresh the provider's options.
  /api/v1/admin/providersetups:
    get:
      summary: List the provider setups in progress
      tags:
        - Admin
      responses:
        "200":
          $ref: "#/components/responses/ListProviderSetupsResponse"
      operationId: admin-list-providersetups
      description: List providers which are still in the process of being set up.
    parameters: []
    post:
      summary: Begin the setup process for a new Access Provider
      operationId: admin-create-providersetup
      tags:
        - Admin
      responses:
        "201":
          $ref: "#/components/responses/ProviderSetupResponse"
        "400":
          $ref: "#/components/responses/ErrorResponse"
      description: Begins the guided setup process for a new Access Provider.
      requestBody:
        $ref: "#/components/requestBodies/CreateProviderSetupRequest"
  "/api/v1/admin/providersetups/{providersetupId}":
    get:
      summary: Get an in-progress provider setup
      tags:
        - Admin
      responses:
        "200":
          $ref: "#/components/responses/ProviderSetupResponse"
      operationId: admin-get-providersetup
      description: Get the setup instructions for an Access Provider.
    parameters:
      - schema:
          type: string
        name: providersetupId
        in: path
        required: true
    delete:
      summary: Delete an in-progress provider setup
      operationId: admin-delete-providersetup
      tags:
        - Admin
      responses:
        "200":
          $ref: "#/components/responses/ProviderSetupResponse"
      description: |-
        Removes an in-progress provider setup and deletes all data relating to it.

        Returns the deleted provider.
  "/api/v1/admin/providersetups/{providersetupId}/instructions":
    get:
      summary: Get the setup instructions for an Access Provider
      tags:
        - Admin
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProviderSetupInstructions"
      operationId: admin-get-providersetup-instructions
      description: Get the setup instructions for an Access Provider.
    parameters:
      - schema:
          type: string
        name: providersetupId
        in: path
        required: true
  "/api/v1/admin/providersetups/{providersetupId}/validate":
    parameters:
      - schema:
          type: string
        name: providersetupId
        in: path
        required: true
    post:
      summary: Validate the configuration for a Provider Setup
      operationId: admin-validate-providersetup
      responses:
        "200":
          $ref: "#/components/responses/ProviderSetupResponse"
      tags:
        - Admin
      description: |-
        Validates the configuration values for an access provider being setup.

        Will return a HTTP200 OK response even if there are validation errors. The errors can be found by inspecting the validation diagnostics in the `configValidation` field.

        Will return a HTTP400 response if the provider cannot be validated (for example, the config values for the provider are incomplete).
  "/api/v1/admin/providersetups/{providersetupId}/complete":
    parameters:
      - schema:
          type: string
        name: providersetupId
        in: path
        required: true
    post:
      summary: Complete a ProviderSetup
      operationId: admin-complete-providersetup
      tags:
        - Admin
      description: "If Runtime Configuration is enabled, this will write the Access Provider to the configuration storage and activate it. If Runtime Configuration is disabled, this endpoint does nothing."
      responses:
        "200":
          $ref: "#/components/responses/CompleteProviderSetupResponse"
  "/api/v1/admin/providersetups/{providersetupId}/steps/{stepIndex}/complete":
    parameters:
      - schema:
          type: integer
        name: stepIndex
        in: path
        required: true
        description: The step index to update the completion status for.
      - schema:
          type: string
        name: providersetupId
        in: path
        required: true
    put:
      summary: Update the completion status for a Provider setup step
      operationId: admin-submit-providersetup-step
      responses:
        "200":
          $ref: "#/components/responses/ProviderSetupResponse"
      description: The updated provider setup.
      requestBody:
        $ref: "#/components/requestBodies/ProviderSetupStepCompleteRequest"
      tags:
        - Admin
  /api/v1/admin/identity/sync:
    parameters: []
    post:
      summary: Sync Identity
      operationId: admin-sync-identity
      responses:
        "200":
          description: OK
        "401":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      description: Run the identity sync operation on demand
      tags:
        - Admin
  /api/v1/admin/identity:
    get:
      summary: Get identity configuration
      tags:
        - Admin
      responses:
        "200":
          $ref: "#/components/responses/IdentityConfigurationResponse"
        "401":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      operationId: admin-get-identity-configuration
      description: Get information about the identity configuration
  /api/v1/access-rules/lookup:
    get:
      summary: Lookup an access rule based on the target
      tags:
        - End User
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/LookupAccessRule"
        "404":
          $ref: "#/components/responses/ErrorResponse"
      operationId: user-lookup-access-rule
      parameters:
        - schema:
            type: string
            enum:
              - commonfate/aws-sso
          in: query
          name: type
          description: the provider type i.e. commonfate/aws-sso. type should be encoded i.e.  backslash -> %2
        - schema:
            type: string
          in: query
          name: permissionSetArn.label
          description: "the permissionSetArn label, typically resembles a role name i.e. AdminstratorAccess"
        - schema:
            type: string
          in: query
          name: accountId
          description: the aws account id
      description: Endpoint returns an array of relevant access rules (used in combination with granted cli)
  /api/v1/favorites:
    get:
      summary: ListFavorites
      tags:
        - End User
      responses:
        "200":
          $ref: "#/components/responses/ListFavoritesResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      operationId: user-list-favorites
      description: "Returns a list of the user's favourited access requests. "
    post:
      summary: Create Favorite
      operationId: user-create-favorite
      tags:
        - End User
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FavoriteDetail"
        "400":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      requestBody:
        $ref: "#/components/requestBodies/CreateFavoriteRequest"
      description: "Favorites an access request for a given user. This is used for frequent access requests saving time and repeated actions. "
    parameters: []
  "/api/v1/favorites/{id}":
    get:
      summary: Get Favorite
      tags:
        - End User
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FavoriteDetail"
        "404":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      operationId: user-get-favorite
      description: "Returns a detailed favorite response. This is used to display a favorite's details on the frontend. "
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
    delete:
      summary: ""
      operationId: user-delete-favorite
      tags:
        - End User
      responses:
        "200":
          description: OK
      description: Delete a saved favorite
    put:
      summary: ""
      operationId: user-update-favorite
      tags:
        - End User
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FavoriteDetail"
      description: Update a favorite with new FavoriteDetails
      requestBody:
        $ref: "#/components/requestBodies/CreateFavoriteRequest"
  "/api/v1/admin/handlers/{id}":
    get:
      summary: Get handler
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TGHandler"
        "401":
          $ref: "#/components/responses/ErrorResponse"
        "404":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      operationId: admin-get-handler
      tags:
        - Admin
      description: ""
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
    delete:
      summary: ""
      operationId: admin-delete-handler
      responses:
        "204":
          description: Returns no content
          content:
            application/json:
              schema:
                type: object
                properties: {}
        "401":
          $ref: "#/components/responses/ErrorResponse"
        "404":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      description: Removes a handler
      tags:
        - Admin
  /api/v1/admin/handlers:
    get:
      summary: Get handlers
      responses:
        "200":
          $ref: "#/components/responses/ListHandlersResponse"
        "401":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      operationId: admin-list-handlers
      description: ""
      tags:
        - Admin
    post:
      summary: Register a handler
      operationId: admin-register-handler
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TGHandler"
        "400":
          $ref: "#/components/responses/ErrorResponse"
        "401":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      requestBody:
        $ref: "#/components/requestBodies/RegisterHandlerRequest"
      tags:
        - Admin
      description: ""
    parameters: []
  "/api/v1/admin/target-groups/{id}":
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
    get:
      summary: Get target group (detailed)
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TargetGroup"
        "401":
          $ref: "#/components/responses/ErrorResponse"
        "404":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      operationId: admin-get-target-group
      tags:
        - Admin
    delete:
      summary: delete target group
      operationId: admin-delete-target-group
      responses:
        "204":
          description: No Content
        "401":
          $ref: "#/components/responses/ErrorResponse"
        "404":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      description: delete target group
      tags:
        - Admin
  /api/v1/admin/target-groups:
    get:
      summary: Get target groups
      responses:
        "200":
          $ref: "#/components/responses/ListTargetGroupResponse"
        "401":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      operationId: admin-list-target-groups
      tags:
        - Admin
    post:
      summary: Create target group
      operationId: admin-create-target-group
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TargetGroup"
        "400":
          $ref: "#/components/responses/ErrorResponse"
        "401":
          $ref: "#/components/responses/ErrorResponse"
        "409":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      requestBody:
        $ref: "#/components/requestBodies/CreateTargetGroupRequest"
      tags:
        - Admin
    parameters: []
  "/api/v1/admin/target-groups/{id}/link":
    parameters:
      - schema:
          type: string
        name: id
        description: Target group ID
        in: path
        required: true
    post:
      summary: Link a target group deployment to its target group
      operationId: admin-create-target-group-link
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TargetRoute"
        "400":
          $ref: "#/components/responses/ErrorResponse"
        "401":
          $ref: "#/components/responses/ErrorResponse"
        "404":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      requestBody:
        $ref: "#/components/requestBodies/CreateTargetGroupLink"
      tags:
        - Admin
  "/api/v1/admin/target-groups/{id}/unlink":
    parameters:
      - schema:
          type: string
        name: id
        description: Target group ID
        in: path
        required: true
    post:
      summary: Unlink a target group deployment from its target group
      operationId: admin-remove-target-group-link
      responses:
        "200":
          description: OK
        "400":
          $ref: "#/components/responses/ErrorResponse"
        "401":
          $ref: "#/components/responses/ErrorResponse"
        "404":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      parameters:
        - schema:
            type: string
          in: query
          name: deploymentId
          required: true
        - schema:
            type: string
          in: query
          name: kind
          required: true
      description: ""
      tags:
        - Admin
  "/api/v1/admin/target-groups/{id}/routes":
    parameters:
      - schema:
          type: string
        name: id
        description: Target group ID
        in: path
        required: true
    get:
      summary: ""
      operationId: admin-list-target-routes
      responses:
        "200":
          $ref: "#/components/responses/ListTargetGroupRoutes"
        "404":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      description: Lists all routes for a given Target Group
  /api/v1/admin/healthcheck-handlers:
    post:
      summary: Healthcheck Handlers
      operationId: admin-healthcheck-handlers
      responses:
        "204":
          description: No Content
        "401":
          $ref: "#/components/responses/ErrorResponse"
        "500":
          $ref: "#/components/responses/ErrorResponse"
      description: Runs the healthcheck for handlers
      tags:
        - Admin
    parameters: []
components:
  schemas:
    User:
      title: User
      type: object
      x-examples:
        Josh:
          id: string
          email: string
          name: string
          picture: "https://avatars.githubusercontent.com/u/17420369?v=4"
        Chris:
          id: string
          email: chris@commonfate.io
          name: Chris Norman
          picture: "https://avatars.githubusercontent.com/u/14214200?v=4"
      properties:
        id:
          type: string
        email:
          type: string
        firstName:
          type: string
        picture:
          type: string
        status:
          $ref: "#/components/schemas/IdpStatus"
        lastName:
          type: string
        updatedAt:
          type: string
          x-go-type: time.Time
          format: time
        groups:
          type: array
          items:
            type: string
      required:
        - id
        - email
        - firstName
        - picture
        - status
        - lastName
        - updatedAt
        - groups
    Request:
      title: Request
      type: object
      description: A request to access something made by an end user in Common Fate.
      properties:
        id:
          type: string
          x-go-name: ID
        requestor:
          type: string
        status:
          $ref: "#/components/schemas/RequestStatus"
        reason:
          type: string
        timing:
          $ref: "#/components/schemas/RequestTiming"
        requestedAt:
          type: string
          x-go-type: time.Time
          format: time
        accessRuleId:
          type: string
        accessRuleVersion:
          type: string
        updatedAt:
          type: string
          x-go-type: time.Time
          format: time
        grant:
          $ref: "#/components/schemas/Grant"
        approvalMethod:
          $ref: "#/components/schemas/ApprovalMethod"
      required:
        - id
        - requestor
        - status
        - timing
        - requestedAt
        - accessRuleId
        - accessRuleVersion
        - updatedAt
    RequestDetail:
      title: Request
      type: object
      description: A request to access something made by an end user in Common Fate.
      properties:
        id:
          type: string
          x-go-name: ID
        requestor:
          type: string
        status:
          $ref: "#/components/schemas/RequestStatus"
        reason:
          type: string
        timing:
          $ref: "#/components/schemas/RequestTiming"
        requestedAt:
          type: string
          x-go-type: time.Time
          format: time
        accessRule:
          $ref: "#/components/schemas/AccessRule"
        updatedAt:
          type: string
          x-go-type: time.Time
          format: time
        grant:
          $ref: "#/components/schemas/Grant"
        canReview:
          type: boolean
          description: true if the requesting user is a reviewer of this request.
        approvalMethod:
          $ref: "#/components/schemas/ApprovalMethod"
        arguments:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/With"
      required:
        - id
        - requestor
        - status
        - timing
        - requestedAt
        - accessRule
        - updatedAt
        - canReview
        - arguments
    RequestStatus:
      type: string
      description: |
        The status of an Access Request.
      enum:
        - APPROVED
        - PENDING
        - CANCELLED
        - DECLINED
      title: RequestStatus
    AccessRule:
      title: AccessRule
      type: object
      description: Access Rule contains information for an end user to make a request for access.
      properties:
        id:
          type: string
          x-go-name: ID
          example: rul_28w2Eebt2Q8nFQJ2dKa1FTE9X0J
        version:
          type: string
          description: |
            A unique version identifier for the Access Rule. Updating a rule creates a new version. 
            When a rule is updated, it's ID remains consistent.
        name:
          type: string
          example: Okta admin
        description:
          type: string
          example: Admin access to Okta
        target:
          $ref: "#/components/schemas/AccessRuleTarget"
        timeConstraints:
          $ref: "#/components/schemas/TimeConstraints"
        isCurrent:
          type: boolean
        createdAt:
          type: string
          x-go-type: time.Time
        updatedAt:
          type: string
          x-go-type: time.Time
      required:
        - id
        - version
        - name
        - description
        - target
        - timeConstraints
        - isCurrent
        - createdAt
        - updatedAt
    AccessRuleDetail:
      title: AccessRuleDetail
      type: object
      description: AccessRuleDetail contains detailed information about a rule and is used in administrative apis.
      properties:
        id:
          type: string
          x-go-name: ID
          example: rul_28w2Eebt2Q8nFQJ2dKa1FTE9X0J
        version:
          type: string
          description: |
            A unique version identifier for the Access Rule. Updating a rule creates a new version. 
            When a rule is updated, it's ID remains consistent.
        status:
          $ref: "#/components/schemas/AccessRuleStatus"
        groups:
          description: The group IDs that the access rule applies to.
          type: array
          items:
            type: string
        approval:
          $ref: "#/components/schemas/ApproverConfig"
        name:
          type: string
          example: Okta admin
        description:
          type: string
          example: Admin access to Okta
        metadata:
          $ref: "#/components/schemas/AccessRuleMetadata"
        target:
          $ref: "#/components/schemas/AccessRuleTargetDetail"
        timeConstraints:
          $ref: "#/components/schemas/TimeConstraints"
        isCurrent:
          type: boolean
      required:
        - id
        - version
        - status
        - groups
        - approval
        - name
        - description
        - metadata
        - target
        - timeConstraints
        - isCurrent
    RequestAccessRule:
      title: RequestAccessRule
      type: object
      description: Access Rule contains information for an end user to make a request for access.
      properties:
        id:
          type: string
          x-go-name: ID
          example: rul_28w2Eebt2Q8nFQJ2dKa1FTE9X0J
        version:
          type: string
          description: |
            A unique version identifier for the Access Rule. Updating a rule creates a new version. 
            When a rule is updated, it's ID remains consistent.
        name:
          type: string
          example: Okta admin
        description:
          type: string
          example: Admin access to Okta
        target:
          $ref: "#/components/schemas/RequestAccessRuleTarget"
        timeConstraints:
          $ref: "#/components/schemas/TimeConstraints"
        isCurrent:
          type: boolean
        canRequest:
          type: boolean
      required:
        - id
        - version
        - name
        - description
        - target
        - timeConstraints
        - isCurrent
        - canRequest
    AccessRuleTarget:
      title: AccessRuleTarget
      type: object
      description: A target for an access rule
      properties:
        provider:
          $ref: "#/components/schemas/Provider"
      required:
        - provider
    AccessRuleTargetDetail:
      title: AccessRuleTargetDetail
      type: object
      description: A detailed target for an access rule
      properties:
        provider:
          $ref: "#/components/schemas/Provider"
        with:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/AccessRuleTargetDetailArguments"
        targetGroup:
          type: string
      required:
        - provider
        - with
    CreateAccessRuleTarget:
      title: CreateAccessRuleTarget
      type: object
      description: a request body for creating a Access Rule Target
      properties:
        providerId:
          type: string
        with:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/CreateAccessRuleTargetDetailArguments"
      required:
        - providerId
        - with
    RequestAccessRuleTarget:
      title: AccessRuleTargetDetail
      type: object
      description: A detailed target for an access rule request
      properties:
        provider:
          $ref: "#/components/schemas/Provider"
        arguments:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/RequestArgument"
      required:
        - provider
        - arguments
    AccessRuleStatus:
      type: string
      description: The status of an Access Rule.
      enum:
        - ACTIVE
        - ARCHIVED
      title: AccessRuleStatus
    AccessRuleMetadata:
      title: AccessRuleMetadata
      type: object
      properties:
        createdAt:
          type: string
          x-go-type: time.Time
        createdBy:
          type: string
        updatedAt:
          type: string
          x-go-type: time.Time
          format: time
        updatedBy:
          type: string
        updateMessage:
          type: string
      required:
        - createdAt
        - createdBy
        - updatedAt
        - updatedBy
    ApproverConfig:
      title: ApproverConfig
      type: object
      description: Approver config for access rules
      properties:
        users:
          type: array
          description: The user IDs of the approvers for the request.
          items:
            type: string
        groups:
          type: array
          items:
            type: string
    TimeConstraints:
      title: TimeConstraints
      type: object
      description: Time configuration for an Access Rule.
      properties:
        maxDurationSeconds:
          type: integer
          description: The maximum duration in seconds the access is allowed for.
          minimum: 60
          exclusiveMinimum: false
          maximum: 15724800
      required:
        - maxDurationSeconds
    Provider:
      title: Provider
      type: object
      x-examples:
        AWS:
          id: string
          name: string
          type: aws
        Okta:
          id: string
          name: string
          type: okta
      description: "Provider "
      properties:
        id:
          type: string
        type:
          type: string
      required:
        - id
        - type
    Group:
      title: Group
      type: object
      description: ""
      properties:
        name:
          type: string
        description:
          type: string
        id:
          type: string
        memberCount:
          type: integer
        members:
          type: array
          items:
            type: string
        source:
          type: string
      required:
        - name
        - description
        - id
        - memberCount
        - members
        - source
    IdpStatus:
      type: string
      title: IdpStatus
      x-stoplight:
        id: a3fdr17gch04a
      enum:
        - ARCHIVED
        - ACTIVE
    ReviewDecision:
      type: string
      title: ReviewDecision
      enum:
        - APPROVED
        - DECLINED
      description: A decision made on an Access Request.
    Grant:
      description: A temporary assignment of a user to a principal.
      type: object
      title: Grant
      properties:
        status:
          type: string
          description: The current state of the grant.
          enum:
            - PENDING
            - ACTIVE
            - ERROR
            - REVOKED
            - EXPIRED
        subject:
          type: string
          minLength: 1
          description: The email address of the user to grant access to.
          format: email
        provider:
          type: string
          minLength: 1
          description: The ID of the provider to grant access to.
          example: okta
        start:
          type: string
          format: date-time
          description: The start time of the grant.
          example: "2022-06-13T03:39:30.921Z"
          x-go-type: time.Time
        end:
          type: string
          format: date-time
          description: The end time of the grant.
          example: "2022-06-13T03:39:30.921Z"
          x-go-type: time.Time
      required:
        - status
        - subject
        - provider
        - start
        - end
    RequestEvent:
      title: RequestEvent
      x-stoplight:
        id: x15z5qclesdq9
      type: object
      properties:
        id:
          type: string
        requestId:
          type: string
        createdAt:
          type: string
          x-go-type: time.Time
          format: time
        actor:
          type: string
        fromStatus:
          $ref: "#/components/schemas/RequestStatus"
        toStatus:
          $ref: "#/components/schemas/RequestStatus"
        fromTiming:
          $ref: "#/components/schemas/RequestTiming"
        toTiming:
          $ref: "#/components/schemas/RequestTiming"
        fromGrantStatus:
          type: string
          description: The current state of the grant.
          enum:
            - PENDING
            - ACTIVE
            - ERROR
            - REVOKED
            - EXPIRED
        toGrantStatus:
          type: string
          description: The current state of the grant.
          enum:
            - PENDING
            - ACTIVE
            - ERROR
            - REVOKED
            - EXPIRED
        grantCreated:
          type: boolean
        requestCreated:
          type: boolean
        grantFailureReason:
          type: string
        recordedEvent:
          type: object
          x-go-type: "map[string]string"
          description: An event which was recorded relating to the grant.
      required:
        - id
        - requestId
        - createdAt
    RequestTiming:
      title: RequestTiming
      x-stoplight:
        id: 4ooyqlf8xba5b
      type: object
      properties:
        durationSeconds:
          type: integer
        startTime:
          type: string
          description: iso8601 timestamp in UTC timezone
          x-go-type: time.Time
          format: time
      required:
        - durationSeconds
    TargetSchema:
      title: TargetSchema
      x-stoplight:
        id: tk7obmea4shbx
      type: object
      additionalProperties:
        $ref: "#/components/schemas/TargetArgument"
    TargetArgument:
      title: TargetArgument
      x-stoplight:
        id: 1b080aa3276c2
      type: object
      description: "Define the metadata, data type and UI elements for the argument"
      properties:
        id:
          type: string
        title:
          type: string
        description:
          type: string
        ruleFormElement:
          type: string
          enum:
            - INPUT
            - MULTISELECT
            - SELECT
        requestFormElement:
          type: string
          enum:
            - SELECT
          description: "Optional form element for the request form, if not provided, defaults to multiselect"
        groups:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/TargetArgumentGroup"
      required:
        - id
        - title
        - ruleFormElement
        - requestFormElement
        - groups
    TargetArgumentGroup:
      title: TargetArgumentGroup
      x-stoplight:
        id: b65de9db1722a
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        description:
          type: string
      required:
        - id
        - title
      description: An argument group
    ApprovalMethod:
      type: string
      description: "Describes whether a request has been approved automatically or from a review "
      title: ApprovalMethod
      x-stoplight:
        id: 689mlt8aqxnx4
      enum:
        - AUTOMATIC
        - REVIEWED
    RequestArgument:
      title: RequestArgument
      x-stoplight:
        id: 1sgrgc47iwg61
      type: object
      properties:
        title:
          type: string
        options:
          type: array
          items:
            $ref: "#/components/schemas/WithOption"
        description:
          type: string
        requiresSelection:
          type: boolean
          description: This will be true if a selection is require when creating a request
        formElement:
          type: string
          enum:
            - SELECT
      required:
        - title
        - options
        - requiresSelection
    With:
      title: With
      x-stoplight:
        id: 1sgrgc47iwg61
      type: object
      properties:
        title:
          type: string
        label:
          type: string
        value:
          type: string
        optionDescription:
          type: string
        fieldDescription:
          type: string
      required:
        - title
        - label
        - value
    WithOption:
      title: WithOption
      x-stoplight:
        id: xoejiu5ci05du
      type: object
      properties:
        value:
          type: string
        label:
          type: string
        valid:
          type: boolean
        description:
          type: string
      required:
        - value
        - label
        - valid
    CreateRequestWith:
      title: CreateRequestWith
      x-stoplight:
        id: 8oa3c4w7ml7tx
      type: object
      additionalProperties:
        type: array
        items:
          type: string
    CreateRequestWithSubRequest:
      title: CreateRequestWithSubRequest
      x-stoplight:
        id: 8oa3c4w7ml7tx
      type: array
      items:
        $ref: "#/components/schemas/CreateRequestWith"
    ProviderSetup:
      title: ProviderSetup
      x-stoplight:
        id: 1nm3rev9qez9b
      type: object
      description: A provider in the process of being set up through the guided setup workflow in Common Fate. These providers are **not** yet active.
      properties:
        id:
          type: string
          description: A unique ID for the provider setup. This is a random KSUID to avoid potential conflicts with user-specified provider IDs in the `deployment.yml` file.
        type:
          type: string
          description: The type of the Access Provider being set up.
        version:
          type: string
          description: The version of the provider.
        status:
          type: string
          enum:
            - COMPLETE
            - VALIDATION_FAILED
            - VALIDATING
            - INITIAL_CONFIGURATION_IN_PROGRESS
            - VALIDATION_SUCEEDED
          description: The status of the setup process.
        steps:
          type: array
          description: An overview of the steps indicating whether they are complete.
          items:
            $ref: "#/components/schemas/ProviderSetupStepOverview"
        configValues:
          type: object
          description: The current configuration values.
          additionalProperties: false
          x-go-type: "map[string]string"
        configValidation:
          type: array
          items:
            $ref: ./accesshandler/openapi.yml#/components/schemas/ProviderConfigValidation
      required:
        - id
        - type
        - version
        - status
        - steps
        - configValues
        - configValidation
    ProviderSetupInstructions:
      title: ProviderSetupInstructions
      x-stoplight:
        id: w5avwzeow2bj9
      type: object
      properties:
        stepDetails:
          type: array
          items:
            $ref: "#/components/schemas/ProviderSetupStepDetails"
      required:
        - stepDetails
    ProviderSetupStepOverview:
      title: ProviderSetupStepOverview
      x-stoplight:
        id: 1nm3rev9qez9b
      type: object
      description: Indicates whether a setup step is complete or not.
      properties:
        complete:
          type: boolean
          description: Whether the step has been completed.
      required:
        - complete
    ProviderSetupStepDetails:
      title: ProviderSetupStepDetails
      x-stoplight:
        id: w5avwzeow2bj9
      type: object
      properties:
        title:
          type: string
        instructions:
          type: string
        configFields:
          type: array
          items:
            $ref: "#/components/schemas/ProviderConfigField"
      required:
        - title
        - instructions
        - configFields
    ProviderConfigField:
      title: ProviderConfigField
      x-stoplight:
        id: w5avwzeow2bj9
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        isOptional:
          type: boolean
          description: Whether the config value is optional.
        isSecret:
          type: boolean
          description: Whether or not the config field is a secret (like an API key or a password)
        secretPath:
          type: string
          description: "the path to where the secret will be stored, in a secrets manager like AWS SSM Parameter Store."
      required:
        - id
        - name
        - description
        - isOptional
        - isSecret
    ProviderConfigValue:
      title: ProviderConfigValue
      x-stoplight:
        id: fv4rhbdwpfki9
      type: object
      properties:
        id:
          type: string
          description: The ID of the config field.
        value:
          type: string
          description: The value entered by the user.
      required:
        - id
        - value
    ProviderSetupValidation:
      title: ProviderSetupValidation
      x-stoplight:
        id: 1nm3rev9qez9b
      type: object
      description: A validation against the configuration values of the Access Provider.
      properties:
        id:
          type: string
          description: "The ID of the validation, such as `list-sso-users`."
        status:
          type: string
          enum:
            - IN_PROGRESS
            - SUCCESS
            - PENDING
            - ERROR
          description: The status of the validation.
        fieldsValidated:
          type: array
          description: "The particular config fields validated, if any."
          items: {}
        logs:
          type: array
          items:
            $ref: "#/components/schemas/Diagnostic"
      required:
        - id
        - status
        - fieldsValidated
    LookupAccessRule:
      title: LookupAccessRule
      x-stoplight:
        id: phxrq09t2fv2z
      type: object
      description: A matched access rule with option values if they are required for the access rule request
      properties:
        accessRule:
          $ref: "#/components/schemas/AccessRule"
        selectableWithOptionValues:
          type: array
          description: "If the matched access rule has selectable fields, this array will contain the matched values to be used to prefill the form when requesting"
          items:
            $ref: "#/components/schemas/KeyValue"
      required:
        - accessRule
    KeyValue:
      title: KeyValue
      x-stoplight:
        id: 35jvelu9x12l2
      type: object
      properties:
        key:
          type: string
        value:
          type: string
      required:
        - key
        - value
    AccessRuleTargetDetailArguments:
      title: AccessRuleTargetDetailArguments
      x-stoplight:
        id: e4h3bs3hxeqyx
      type: object
      description: ""
      properties:
        values:
          type: array
          items:
            type: string
        groupings:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        formElement:
          type: string
          enum:
            - INPUT
            - MULTISELECT
      required:
        - values
        - groupings
        - formElement
    CreateAccessRuleTargetDetailArguments:
      title: CreateAccessRuleTargetDetailArguments
      x-stoplight:
        id: e4h3bs3hxeqyx
      type: object
      description: ""
      properties:
        values:
          type: array
          items:
            type: string
        groupings:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
      required:
        - values
        - groupings
    Favorite:
      title: Favorite
      x-stoplight:
        id: wyyga2547rs1n
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        ruleId:
          type: string
      required:
        - id
        - name
        - ruleId
    FavoriteDetail:
      title: FavoriteDetail
      x-stoplight:
        id: wyyga2547rs1n
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        with:
          $ref: "#/components/schemas/CreateRequestWithSubRequest"
        reason:
          type: string
        timing:
          $ref: "#/components/schemas/RequestTiming"
      required:
        - id
        - name
        - with
        - timing
      description: "Detailed object for a Favorite. "
    TGHandler:
      title: TGHandler
      x-stoplight:
        id: dfd783fec606a
      type: object
      x-tags:
        - Target Groups
      properties:
        id:
          type: string
        runtime:
          type: string
        functionArn:
          type: string
        awsAccount:
          type: string
        awsRegion:
          type: string
        healthy:
          type: boolean
        diagnostics:
          type: array
          items:
            $ref: "#/components/schemas/Diagnostic"
      required:
        - id
        - runtime
        - functionArn
        - awsAccount
        - awsRegion
        - healthy
        - diagnostics
      description: |-
        Handler represents a deployment of a provider. 
        Handlers can be linked to target groups via routes
    TargetGroupFrom:
      title: TargetGroupFrom
      x-stoplight:
        id: 1beeb9df4c57d
      type: object
      properties:
        publisher:
          type: string
        name:
          type: string
        version:
          type: string
        kind:
          type: string
      required:
        - publisher
        - name
        - version
        - kind
      description: Specifies a particular Access Provider to create a Target Group schema from.
    TargetGroup:
      title: TargetGroup
      x-stoplight:
        id: wcyzfn1kp9xkx
      type: object
      properties:
        id:
          type: string
        schema:
          $ref: "#/components/schemas/TargetSchema"
        from:
          $ref: "#/components/schemas/TargetGroupFrom"
        icon:
          type: string
        createdAt:
          type: string
          x-go-type: time.Time
        updatedAt:
          type: string
          x-go-type: time.Time
          format: time
      required:
        - id
        - schema
        - from
        - icon
    TargetRoute:
      type: object
      x-stoplight:
        id: a3339ab311211
      title: TargetRoute
      properties:
        targetGroupId:
          type: string
        handlerId:
          type: string
        kind:
          type: string
        priority:
          type: integer
        valid:
          type: boolean
        diagnostics:
          type: array
          items:
            $ref: "#/components/schemas/Diagnostic"
      required:
        - targetGroupId
        - handlerId
        - kind
        - priority
        - valid
        - diagnostics
    Diagnostic:
      title: Diagnostic
      x-stoplight:
        id: fb62cbb9bc444
      type: object
      properties:
        level:
          $ref: "#/components/schemas/LogLevel"
        code:
          type: string
        message:
          type: string
      required:
        - level
        - code
        - message
    LogLevel:
      title: LogLevel
      x-stoplight:
        id: pcykc8l1vd4o2
      type: string
      enum:
        - INFO
        - WARNING
        - ERROR
  responses:
    ErrorResponse:
      description: An error returned from the service.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
            required:
              - error
          examples: {}
    ListUserResponse:
      description: Paginated list of users
      content:
        application/json:
          schema:
            type: object
            properties:
              users:
                type: array
                items:
                  $ref: "#/components/schemas/User"
              next:
                type: string
                nullable: true
            required:
              - users
              - next
          examples: {}
    ListAccessRulesResponse:
      description: A list of Access Rules.
      content:
        application/json:
          schema:
            type: object
            properties:
              accessRules:
                type: array
                items:
                  $ref: "#/components/schemas/AccessRule"
              next:
                type: string
                nullable: true
            required:
              - accessRules
              - next
    ListRequestsResponse:
      description: Paginated list of Requests
      content:
        application/json:
          schema:
            type: object
            properties:
              requests:
                type: array
                items:
                  $ref: "#/components/schemas/Request"
              next:
                type: string
                nullable: true
            required:
              - requests
              - next
    ListGroupsResponse:
      description: Returns a list of Groups
      content:
        application/json:
          schema:
            type: object
            properties:
              groups:
                type: array
                items:
                  $ref: "#/components/schemas/Group"
              next:
                type: string
                nullable: true
            required:
              - groups
              - next
    ReviewResponse:
      description: Response for reviewing a request.
      content:
        application/json:
          schema:
            type: object
            properties:
              request:
                $ref: "#/components/schemas/Request"
    ListAccessRuleApproversResponse:
      description: A list of user ids who can approver an access rule request
      content:
        application/json:
          schema:
            type: object
            properties:
              users:
                type: array
                items:
                  type: string
              next:
                type: string
                nullable: true
            required:
              - users
              - next
    ListAccessRulesDetailResponse:
      description: Example response
      content:
        application/json:
          schema:
            type: object
            properties:
              accessRules:
                type: array
                items:
                  $ref: "#/components/schemas/AccessRuleDetail"
              next:
                type: string
                nullable: true
            required:
              - accessRules
              - next
    AuthUserResponse:
      description: Details about the authenticated user
      content:
        application/json:
          schema:
            type: object
            properties:
              user:
                $ref: "#/components/schemas/User"
              isAdmin:
                description: Whether the user is an administrator of Common Fate.
                type: boolean
            required:
              - user
              - isAdmin
    ListRequestEventsResponse:
      description: Paginated list of RequestEvent
      content:
        application/json:
          schema:
            type: object
            properties:
              events:
                type: array
                items:
                  $ref: "#/components/schemas/RequestEvent"
              next:
                type: string
                nullable: true
            required:
              - events
              - next
    ProviderSetupResponse:
      description: Returns a ProviderSetup object.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ProviderSetup"
    ListProviderSetupsResponse:
      description: A list of in-progress Access Providers being set up by the Common Fate administrators.
      content:
        application/json:
          schema:
            type: object
            properties:
              providerSetups:
                type: array
                items:
                  $ref: "#/components/schemas/ProviderSetup"
            required:
              - providerSetups
    CompleteProviderSetupResponse:
      description: The response when completing an Access Provider guided setup.
      content:
        application/json:
          schema:
            type: object
            properties:
              deploymentConfigUpdateRequired:
                type: boolean
                description: Whether a manual update is required to the Common Fate deployment configuration (`deployment.yml`) to activate the provider.
            required:
              - deploymentConfigUpdateRequired
    IdentityConfigurationResponse:
      description: Returns information about the identity configuration of this deployment.
      content:
        application/json:
          schema:
            type: object
            properties:
              identityProvider:
                type: string
              administratorGroupId:
                type: string
            required:
              - identityProvider
              - administratorGroupId
    DeploymentVersionResponse:
      description: Deployment version information.
      content:
        application/json:
          schema:
            type: object
            properties:
              version:
                type: string
                description: 'The deployment version. Will be a semver, such as "v0.9.0" for official releases, or "dev+GIT_HASH" for pre-release builds.'
            required:
              - version
    ListFavoritesResponse:
      description: Returns a list of Favorites
      content:
        application/json:
          schema:
            type: object
            properties:
              next:
                type: string
                nullable: true
              favorites:
                type: array
                items:
                  $ref: "#/components/schemas/Favorite"
            required:
              - next
              - favorites
    AccessTokenResponse:
      description: "If the request has an access token, hasToken will be true"
      content:
        application/json:
          schema:
            type: object
            properties:
              hasToken:
                type: boolean
              token:
                type: string
            required:
              - hasToken
    ListTargetGroupResponse:
      description: Example response
      content:
        application/json:
          schema:
            type: object
            properties:
              targetGroups:
                type: array
                items:
                  $ref: "#/components/schemas/TargetGroup"
              next:
                type: string
            required:
              - targetGroups
    ListHandlersResponse:
      description: Response obj for ListTargetGroupDeploymentAPIResponse
      content:
        application/json:
          schema:
            type: object
            properties:
              res:
                type: array
                items:
                  $ref: "#/components/schemas/TGHandler"
              next:
                type: string
            required:
              - res
              - next
    ListTargetGroupRoutes:
      description: Example response
      content:
        application/json:
          schema:
            type: object
            properties:
              routes:
                type: array
                items:
                  $ref: "#/components/schemas/TargetRoute"
              next:
                type: string
            required:
              - routes
    CreateRequestResponse:
      description: Details about the created Access Requests.
      content:
        application/json:
          schema:
            type: object
            properties:
              requests:
                type: array
                items:
                  $ref: "#/components/schemas/Request"
            required:
              - requests
  examples: {}
  securitySchemes: {}
  requestBodies:
    CreateAccessRuleRequest:
      content:
        application/json:
          schema:
            type: object
            properties:
              groups:
                description: The group IDs that the access rule applies to.
                type: array
                items:
                  type: string
              approval:
                $ref: "#/components/schemas/ApproverConfig"
              name:
                type: string
                example: Okta admin
                pattern: '[a-zA-Z0-9,.;:()[\]?!\-_`~&/\n\s]'
                minLength: 1
                maxLength: 400
              description:
                type: string
                example: Admin access to Okta
                pattern: '[a-zA-Z0-9,.;:()[\]?!\-_`~&/\n\s]|^$'
                minLength: 0
                maxLength: 2048
              target:
                $ref: "#/components/schemas/CreateAccessRuleTarget"
              timeConstraints:
                $ref: "#/components/schemas/TimeConstraints"
            required:
              - groups
              - approval
              - name
              - description
              - target
              - timeConstraints
    CreateUserRequest:
      content:
        application/json:
          schema:
            type: object
            properties:
              email:
                type: string
                format: email
                minLength: 1
                maxLength: 2048
              firstName:
                type: string
                minLength: 1
                maxLength: 2048
                pattern: '[a-zA-Z0-9,.;:()[\]?!\-_`~&/\n\s]'
              lastName:
                type: string
                minLength: 1
                maxLength: 2048
                pattern: '[a-zA-Z0-9,.;:()[\]?!\-_`~&/\n\s]'
              isAdmin:
                type: boolean
            required:
              - email
              - firstName
              - lastName
              - isAdmin
      description: ""
    CreateRequestRequest:
      content:
        application/json:
          schema:
            type: object
            properties:
              accessRuleId:
                type: string
                pattern: '[a-zA-Z0-9,.;:()[\]?!\-_`~&/\n\s]'
                minLength: 1
                maxLength: 400
              reason:
                type: string
                minLength: 0
                maxLength: 2048
              timing:
                $ref: "#/components/schemas/RequestTiming"
              with:
                $ref: "#/components/schemas/CreateRequestWithSubRequest"
            required:
              - accessRuleId
              - timing
    ReviewRequest:
      content:
        application/json:
          schema:
            type: object
            properties:
              decision:
                $ref: "#/components/schemas/ReviewDecision"
              comment:
                type: string
                minLength: 0
                maxLength: 2048
              overrideTiming:
                $ref: "#/components/schemas/RequestTiming"
            required:
              - decision
      description: |-
        An approver's review of an Access Request.
        The access request timing can be overriden by including override timing in the request body.
        If it is omitted, the original request timing will be used.
    ProviderSetupStepCompleteRequest:
      content:
        application/json:
          schema:
            type: object
            properties:
              complete:
                type: boolean
                description: Whether the step is complete or not.
              configValues:
                type: object
                additionalProperties:
                  type: string
                description: The config values entered by the user which correspond to the setup step.
                x-go-type: "map[string]string"
            required:
              - complete
              - configValues
    CreateProviderSetupRequest:
      content:
        application/json:
          schema:
            type: object
            properties:
              providerType:
                type: string
                description: The type of the provider to set up.
                pattern: '[a-zA-Z0-9,.;:()[\]?!\-_`~&/\n\s]'
                minLength: 0
                maxLength: 2048
            required:
              - providerType
      description: Begin the guided setup process for a new Access Provider.
    CreateGroupRequest:
      content:
        application/json:
          schema:
            type: object
            properties:
              name:
                type: string
                minLength: 1
                pattern: "^[a-zA-Z0-9_.-]"
                maxLength: 2048
              description:
                type: string
                minLength: 0
                maxLength: 2048
              members:
                type: array
                items:
                  type: string
            required:
              - name
              - members
    CreateFavoriteRequest:
      content:
        application/json:
          schema:
            type: object
            properties:
              accessRuleId:
                type: string
                pattern: '[a-zA-Z0-9,.;:()[\]?!\-_`~&/\n\s]'
                minLength: 1
                maxLength: 400
              reason:
                type: string
                pattern: '[a-zA-Z0-9,.;:()[\]?!\-_`~&/\n\s]|^$'
                minLength: 0
                maxLength: 2048
              timing:
                $ref: "#/components/schemas/RequestTiming"
              with:
                $ref: "#/components/schemas/CreateRequestWithSubRequest"
              name:
                type: string
            required:
              - accessRuleId
              - timing
              - name
    CreateTargetGroupRequest:
      content:
        application/json:
          schema:
            type: object
            properties:
              from:
                $ref: "#/components/schemas/TargetGroupFrom"
              id:
                type: string
                maxLength: 64
                pattern: "^[-a-zA-Z0-9]*$"
            required:
              - from
              - id
    RegisterHandlerRequest:
      content:
        application/json:
          schema:
            type: object
            properties:
              id:
                type: string
                description: "The ID of the target group to deploy to. User, provided"
                pattern: "^[-a-zA-Z0-9]*$"
                maxLength: 64
              runtime:
                type: string
                default: aws-lambda
              awsAccount:
                type: string
                pattern: "^[0-9]{12}"
              awsRegion:
                type: string
                pattern: ^(us(-gov)?|ap|ca|cn|eu|sa)-(central|(north|south)?(east|west)?)-\d$
                minLength: 9
                example: us-east-1
            required:
              - id
              - runtime
              - awsAccount
              - awsRegion
    CreateTargetGroupLink:
      content:
        application/json:
          schema:
            type: object
            properties:
              deploymentId:
                type: string
              priority:
                type: integer
                maximum: 999
                minimum: 0
              kind:
                type: string
            required:
              - deploymentId
              - priority
              - kind
tags:
  - name: End User
  - name: Admin
  - name: Target Groups