swagger: '2.0'

info:
  title: Sam
  description: |
    Workbench identity and access management.
  version: "0.1"
  license:
    name: BSD
    url: http://opensource.org/licenses/BSD-3-Clause
  termsOfService: https://github.com/broadinstitute/sam

basePath: /

produces:
  - application/json

security:
  - googleoauth:
      - openid
      - email
      - profile

securityDefinitions:
  googleoauth:
    type: oauth2
    authorizationUrl: 'https://accounts.google.com/o/oauth2/auth'
    flow: implicit
    scopes:
      openid: open id authorization
      email: email authorization
      profile: profile authorization

##########################################################################################
## PATHS
##########################################################################################
paths:

  /api/admin/user/{userId}:
    get:
      summary: gets the registration status of the user, by user id
      parameters:
        - in: path
          description: User ID to check the status of
          name: userId
          required: true
          type: string
      operationId: adminGetUserStatus
      tags:
        - Admin
      responses:
        200:
          description: status of specified user
          schema:
            $ref: '#/definitions/UserStatus'

  /api/admin/user/email/{email}:
    get:
      summary: gets the registration status of the user, by email
      parameters:
        - in: path
          description: Email address of user to check
          name: email
          required: true
          type: string
      operationId: adminGetUserByEmail
      tags:
        - Admin
      responses:
        200:
          description: status of specified user
          schema:
            $ref: '#/definitions/UserStatus'

  /api/admin/user/{userId}/disable:
    put:
      summary: disables the specified user
      parameters:
        - in: path
          description: User ID to disable
          name: userId
          required: true
          type: string
      operationId: disableUser
      tags:
        - Admin
      responses:
        200:
          description: status of specified user
          schema:
            $ref: '#/definitions/UserStatus'

  /api/admin/user/{userId}/enable:
    put:
      summary: enables the specified user
      parameters:
        - in: path
          description: User ID to enable
          name: userId
          required: true
          type: string
      operationId: enableUser
      tags:
        - Admin
      responses:
        200:
          description: status of specified user
          schema:
            $ref: '#/definitions/UserStatus'

  /api/admin/user/{userId}/petServiceAccount:
    delete:
      summary: deletes a user's pet service account
      responses:
        204:
          description: Successfully deleted pet service account
        403:
          description: You do not have admin privileges
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: path
          description: User ID whose pet to delete
          name: userId
          required: true
          type: string
      operationId: deletePet
      tags:
        - Admin

  /api/admin/user/{userId}/petServiceAccount/{project}:
    delete:
      summary: deletes a user's pet service account for a project
      responses:
        204:
          description: Successfully deleted pet service account for a project
        403:
          description: You do not have admin privileges
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: path
          description: User ID whose pet to delete
          name: userId
          required: true
          type: string
        - in: path
          description: Google project of the pet
          name: project
          required: true
          type: string
      operationId: deletePetPerProject
      tags:
        - Admin

  /api/config/v1/resourceTypes:
    get:
      responses:
        200:
          description: Success
          schema:
            type: array
            items:
              $ref: '#/definitions/ResourceType'
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      summary: Lists available resource types
      operationId: listResourceTypes
      tags:
        - Config

  /api/groups/v1:
    get:
      summary: Show all the groups the requesting user belongs to and their policy membership in each group
      responses:
        200:
          description: Managed Group memberships
          schema:
            type: array
            items:
              $ref: '#/definitions/ManagedGroupMembershipEntry'
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      operationId: listGroupMemberships
      tags:
        - Group

  /api/groups/v1/{groupName}:
    get:
      summary: Show email address of the group
      responses:
        200:
          description: Group found
          schema:
            description: Email address for the group
            type: string
        404:
          description: Group could not be found or you do not have the required permissions on this group
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: path
          description: Name of group
          name: groupName
          required: true
          type: string
      operationId: getGroup
      tags:
        - Group
    post:
      summary: Create a new group
      responses:
        201:
          description: Group created
        409:
          description: Group already exists
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: path
          description: Name of group
          name: groupName
          required: true
          type: string
      operationId: postGroup
      tags:
        - Group
    delete:
      summary: Delete group
      responses:
        204:
          description: Group deleted
        404:
          description: Group could not be found or you do not have the required permissions on this group
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: path
          description: Name of group
          name: groupName
          required: true
          type: string
      operationId: deleteGroup
      tags:
        - Group

  /api/groups/v1/{groupName}/requestAccess:
    post:
      summary: Request access to a managed group
      responses:
        204:
          description: Request sent
        404:
          description: Group could not be found or you do not have the required permissions on this group
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: path
          description: Name of group
          name: groupName
          required: true
          type: string
      operationId: requestAccess
      tags:
        - Group

  /api/groups/v1/{groupName}/{policyName}:
    get:
      summary: 'Get email addresses for members of the "admin" policy'
      responses:
        200:
          description: 'Email addresses in the "admin" policy'
          schema:
            $ref: '#/definitions/ArrayOfEmails'
        404:
          description: Group could not be found or you do not have the required permissions on this group
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: path
          description: Name of group
          name: groupName
          required: true
          type: string
        - in: path
          description: Name of policy
          name: policyName
          required: true
          type: string
          enum: ["member", "admin"]
      operationId: GetGroupAdminEmails
      tags:
        - Group
    put:
      summary: 'Overwrite email addresses of members of the "admin" policy'
      responses:
        201:
          description: Policy successfully updated
        404:
          description: Group does not exist or you are not a member of the policy for the group
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: path
          description: Name of group
          name: groupName
          required: true
          type: string
        - in: path
          description: Name of policy
          name: policyName
          required: true
          type: string
          enum: ["member", "admin"]
        - in: body
          description: The list of emails
          name: emailAddresses
          required: true
          schema:
            $ref: '#/definitions/ArrayOfEmails'
      operationId: OverwriteGroupAdminEmails
      tags:
        - Group

  /api/groups/v1/{groupName}/{policyName}/{email}:
    put:
      summary: Add email to the policy
      responses:
        204:
          description: Email successfully added
        400:
          description: Email is invalid
        403:
          description: You do not have permission to alter this policy
        404:
          description: Group does not exist, policy does not exist, or subject with specified email was not found
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: path
          description: Name of group
          name: groupName
          required: true
          type: string
        - in: path
          description: Name of policy
          name: policyName
          required: true
          type: string
          enum: ["member", "admin"]
        - in: path
          description: Email address
          name: email
          required: true
          type: string
      operationId: AddEmailToGroup
      tags:
        - Group
    delete:
      summary: Remove email from the policy
      responses:
        204:
          description: Email successfully removed
        403:
          description: You do not have permission to alter this policy
        404:
          description: Group does not exist or policy does not exist
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: path
          description: Name of group
          name: groupName
          required: true
          type: string
        - in: path
          description: Name of policy
          name: policyName
          required: true
          type: string
          enum: ["member", "admin"]
        - in: path
          description: Email address
          name: email
          required: true
          type: string
      operationId: RemoveEmailFromGroup
      tags:
        - Group

  /api/google/v1/group/{groupName}/sync:
    post:
      summary: Synchronize a managed-group with google group
      responses:
        200:
          description: Successfully synchronized group
          schema:
            $ref: '#/definitions/SyncReport'
        404:
          description: Group could not be found
          schema:
            $ref: '#/definitions/ErrorReport'
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: path
          description: Name of group
          name: groupName
          required: true
          type: string
      operationId: syncManagedGroup
      tags:
        - Google

  /api/google/v1/petServiceAccount/{project}/{userEmail}:
    get:
      summary: gets a key for the user's pet service account, get_pet_private_key action on cloud-extension/google required
      responses:
        200:
          description: 'json format key for a pet service account, see https://cloud.google.com/iam/docs/creating-managing-service-account-keys'
          schema:
            type: string
        404:
          description: 'user does not exist or caller does not have any access to cloud-extension/google resource'
          schema:
            $ref: '#/definitions/ErrorReport'
        403:
          description: 'caller has some access to cloud-extension/google but not to the get_pet_private_key action'
          schema:
            $ref: '#/definitions/ErrorReport'
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: path
          description: Google project of the pet
          name: project
          required: true
          type: string
        - in: path
          description: User's email address
          name: userEmail
          required: true
          type: string
      operationId: getUserPetServiceAccountKey
      tags:
        - Google

  /api/google/v1/user/petServiceAccount/{project}:
    get:
      summary: gets the pet service account for the specified user
      responses:
        200:
          description: 'user pet service account'
          schema:
            type: string
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: path
          description: Google project of the pet
          name: project
          required: true
          type: string
      operationId: getPetServiceAccount
      tags:
        - Google

  /api/google/v1/user/petServiceAccount/key:
    get:
      summary: gets a key for an arbitrary pet service account for the user
      responses:
        200:
          description: 'json format key for a pet service account, see https://cloud.google.com/iam/docs/creating-managing-service-account-keys'
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      operationId: getArbitraryPetServiceAccountKey
      tags:
        - Google

  /api/google/v1/user/petServiceAccount/token:
    post:
      summary: gets a token for an arbitrary pet service account for the user
      responses:
        200:
          description: 'an access token for the users pet service account'
          schema:
            type: string
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: body
          description: Scopes for the token
          name: scopes
          required: true
          schema:
            $ref: '#/definitions/ArrayOfScopes'
      operationId: getArbitraryPetServiceAccountToken
      tags:
        - Google

  /api/google/v1/user/petServiceAccount/{project}/key:
    get:
      summary: gets a key for the user's pet service account
      responses:
        200:
          description: 'json format key for a pet service account, see https://cloud.google.com/iam/docs/creating-managing-service-account-keys'
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: path
          description: Google project of the pet
          name: project
          required: true
          type: string
      operationId: getPetServiceAccountKey
      tags:
        - Google

  /api/google/v1/user/petServiceAccount/{project}/key/{keyId}:
    delete:
      summary: removes an existing key for the user's pet service account
      responses:
        204:
          description: 'user pet service account'
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: path
          description: Google project of the pet
          name: project
          required: true
          type: string
        - in: path
          description: key ID for the key to remove, private_key_id field of json key from get request
          name: keyId
          required: true
          type: string
      operationId: removePetServiceAccountKey
      tags:
        - Google

  /api/google/v1/user/petServiceAccount/{project}/token:
    post:
      summary: gets a token for the user's pet service account
      responses:
        200:
          description: 'an access token for the users pet service account'
          schema:
            type: string
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: path
          description: Google project of the pet
          name: project
          required: true
          type: string
        - in: body
          description: Scopes for the token
          name: scopes
          required: true
          schema:
            $ref: '#/definitions/ArrayOfScopes'
      operationId: getPetServiceAccountToken
      tags:
        - Google

  /api/google/v1/user/proxyGroup/{email}:
    get:
      summary: gets the proxy group email for the specified user
      responses:
        200:
          description: 'user proxy group'
          schema:
            type: string
        404:
          description: 'user not found'
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: path
          description: User email whose proxy group to retrieve
          name: email
          required: true
          type: string
      operationId: getProxyGroup
      tags:
        - Google

  /api/google/v1/resource/{resourceTypeName}/{resourceId}/{policyName}/sync:
    post:
      summary: Synchronize a policy's membership with google group. Once called all further membership changes will by automatically synchronized
      responses:
        200:
          description: Successfully synchronized membership
          schema:
            $ref: '#/definitions/SyncReport'
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: path
          description: Type of resource
          name: resourceTypeName
          required: true
          type: string
        - in: path
          description: Id of resource
          name: resourceId
          required: true
          type: string
        - in: path
          description: Name of policy to synchronize
          name: policyName
          required: true
          type: string
      operationId: syncPolicy
      tags:
        - Google

    get:
      summary: Gets the synchronization state (last synchronized date) for the group.
      responses:
        200:
          description: Success
          schema:
            $ref: '#/definitions/SyncStatus'
        204:
          description: Group is not synchronized to Google
        404:
          description: Group not found
      parameters:
        - in: path
          description: Type of resource
          name: resourceTypeName
          required: true
          type: string
        - in: path
          description: Id of resource
          name: resourceId
          required: true
          type: string
        - in: path
          description: Name of policy to synchronize
          name: policyName
          required: true
          type: string
      operationId: syncStatus
      tags:
        - Google

  /api/resources/v1/{resourceTypeName}:
    get:
      summary: List resources and policies for this resource for the caller
      responses:
        200:
          description: Success
          schema:
            type: array
            items:
              $ref: '#/definitions/ResourceAndAccessPolicy'
      parameters:
        - in: path
          description: Type of the resource
          name: resourceTypeName
          required: true
          type: string
      operationId: listResourcesAndPolicies
      tags:
        - Resources
    post:
      summary: Create a new resource, cannot be used when resource type allows id reuse
      responses:
        204:
          description: Successfully created resource
        400:
          description: Invalid policies, invalid auth domain, or resource type allows id reuse
          schema:
            $ref: '#/definitions/ErrorReport'
        409:
          description: Resource already exists
          schema:
            $ref: '#/definitions/ErrorReport'
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: path
          description: Type of resource to create
          name: resourceTypeName
          required: true
          type: string
        - in: body
          description: The details of the resource
          name: resourceCreate
          required: true
          schema:
            $ref: '#/definitions/CreateResourceRequest'
      operationId: createResource
      tags:
        - Resources

  /api/resources/v1/{resourceTypeName}/{resourceId}:
    delete:
      summary: Delete a resource
      responses:
        204:
          description: Successfully deleted resource
        403:
          description: You do not have permission to perform this action on the resource
        404:
          description: Resource type does not exist or you are not a member of any policy on the resource
      parameters:
        - in: path
          description: Type of the resource
          name: resourceTypeName
          required: true
          type: string
        - in: path
          description: Id of the resource
          name: resourceId
          required: true
          type: string
      operationId: deleteResource
      tags:
        - Resources
    post:
      summary: Create a new resource with default owner policy
      responses:
        204:
          description: Successfully created resource
        409:
          description: Resource already exists
          schema:
            $ref: '#/definitions/ErrorReport'
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: path
          description: Type of resource to create
          name: resourceTypeName
          required: true
          type: string
        - in: path
          description: Id of resource to create, must be unique for all resources of given type
          name: resourceId
          required: true
          type: string
      operationId: createResourceWithDefaults
      tags:
        - Resources

  /api/resources/v1/{resourceTypeName}/{resourceId}/policies:
    get:
      summary: List the policies for a resource
      responses:
        200:
          description: Policies successfully listed
          schema:
            type: array
            items:
              $ref: '#/definitions/AccessPolicyResponseEntry'
        403:
          description: You do not have permission to perform this action on the resource
        404:
          description: Resource type does not exist or you are not a member of any policy on the resource
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: path
          description: Type of resource
          name: resourceTypeName
          required: true
          type: string
        - in: path
          description: Id of resource
          name: resourceId
          required: true
          type: string
      operationId: listResourcePolicies
      tags:
        - Resources

  /api/resources/v1/{resourceTypeName}/{resourceId}/policies/{policyName}:
    get:
      summary: Gets a policy on a resource
      responses:
        200:
          description: Policy information
          schema:
            $ref: '#/definitions/AccessPolicyMembership'
        403:
          description: You do not have permission to perform this action on the resource
        404:
          description: Resource type does not exist or you are not a member of any policy on the resource or the policy does not exist
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: path
          description: Type of resource
          name: resourceTypeName
          required: true
          type: string
        - in: path
          description: Id of resource
          name: resourceId
          required: true
          type: string
        - in: path
          description: Name of the policy
          name: policyName
          required: true
          type: string
      operationId: getPolicy
      tags:
        - Resources
    put:
      summary: Overwrite a policy on a resource
      responses:
        201:
          description: Policy successfully created/updated
        403:
          description: You do not have permission to perform this action on the resource
        404:
          description: Resource type does not exist or you are not a member of any policy on the resource
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: path
          description: Type of resource
          name: resourceTypeName
          required: true
          type: string
        - in: path
          description: Id of resource
          name: resourceId
          required: true
          type: string
        - in: path
          description: Name of the policy
          name: policyName
          required: true
          type: string
        - in: body
          description: The details of the policy
          name: policyCreate
          required: true
          schema:
            $ref: '#/definitions/AccessPolicyMembership'
      operationId: overwritePolicy
      tags:
        - Resources

  /api/resources/v1/{resourceTypeName}/{resourceId}/policies/{policyName}/memberEmails/{email}:
    put:
      summary: Add a user to a policy
      responses:
        204:
          description: Successfully added a user to the policy
        400:
          description: email is not found
        403:
          description: You do not have permission to alter this policy
        404:
          description: Resource type does not exist, you are not a member of any policy on the resource, or user was not found
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: path
          description: Type of resource
          name: resourceTypeName
          required: true
          type: string
        - in: path
          description: Id of resource
          name: resourceId
          required: true
          type: string
        - in: path
          description: Name of the policy
          name: policyName
          required: true
          type: string
        - in: path
          description: Email of user to be added
          name: email
          required: true
          type: string
      operationId: addUserToPolicy
      tags:
        - Resources
    delete:
      summary: Remove a user from a policy
      responses:
        204:
          description: Successfully removed a user from the policy
        400:
          description: email is not found
        403:
          description: You do not have permission to alter this policy
        404:
          description: Resource type does not exist, you are not a member of any policy on the resource, or user was not found
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: path
          description: Type of resource
          name: resourceTypeName
          required: true
          type: string
        - in: path
          description: Id of resource
          name: resourceId
          required: true
          type: string
        - in: path
          description: Name of the policy
          name: policyName
          required: true
          type: string
        - in: path
          description: Email of user to be removed
          name: email
          required: true
          type: string
      operationId: removeUserFromPolicy
      tags:
        - Resources


  /api/resources/v1/{resourceTypeName}/{resourceId}/roles:
    get:
      summary: Query for the list of roles that the requesting user has on the resource
      responses:
        200:
          description: The list of roles that the requesting user has on the resource. Empty if resource does not exist or user has no role on that resource.
          schema:
            type: array
            items:
              type: string
        404:
          description: Resource type does not exist
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: path
          description: Type of resource to query
          name: resourceTypeName
          required: true
          type: string
        - in: path
          description: Id of resource to query
          name: resourceId
          required: true
          type: string
      operationId: resourceRoles
      tags:
        - Resources

  /api/resources/v1/{resourceTypeName}/{resourceId}/action/{action}:
    get:
      summary: Query if requesting user may perform the action
      responses:
        200:
          description: true if the user may perform the action, false if they may not or the resource does not exist
          schema:
            type: boolean
        500:
          description: Internal Error
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: path
          description: Type of resource to query
          name: resourceTypeName
          required: true
          type: string
        - in: path
          description: Id of resource to query
          name: resourceId
          required: true
          type: string
        - in: path
          description: Action to perform
          name: action
          required: true
          type: string
      operationId: resourceAction
      tags:
        - Resources

  /register/user/v1:
    get:
      summary: gets the registration status of the logged in user
      responses:
        200:
          description: 'user exists'
          schema:
            $ref: '#/definitions/UserStatus'
        404:
          description: user not found
          schema:
            $ref: '#/definitions/ErrorReport'
      parameters:
        - in: query
          description: when set to true does not check the various enabled status of the user
          name: userDetailsOnly
          required: false
          type: string
      operationId: getUserStatus
      tags:
        - Users
    post:
      summary: create current user in the system using login credentials
      responses:
        201:
          description: 'user successfully created'
          schema:
            $ref: '#/definitions/UserStatus'
        409:
          description: user already exists
          schema:
            $ref: '#/definitions/ErrorReport'
      operationId: createUser
      tags:
        - Users

  /status:
    get:
      summary: gets system status
      responses:
        200:
          description: 'system ok'
          schema:
            $ref: '#/definitions/SystemStatus'
        500:
          description: 'one or more subsystems down'
          schema:
            $ref: '#/definitions/SystemStatus'
      operationId: getSystemStatus
      tags:
        - Status
      security: [] # no security

##########################################################################################
## DEFINITIONS
##########################################################################################
definitions:

  AccessPolicyResponseEntry:
    description: ''
    required:
      - policyName
      - policy
    properties:
      policyName:
        type: string
      policy:
        $ref: '#/definitions/AccessPolicyMembership'

  AccessPolicyMembership:
    description: ''
    required:
      - memberEmails
      - actions
      - roles
    properties:
      memberEmails:
        type: array
        items:
          type: string
      actions:
        type: array
        items:
          type: string
      roles:
        type: array
        items:
          type: string

  ArrayOfEmails:
    description: An array of email addresses
    type: array
    items:
      type: string
    example:
      - person@company.com
      - group_name@company.com
      - foo@bar.com

  ArrayOfScopes:
    description: An array of scopes
    type: array
    items:
      type: string
    example:
      - https://www.googleapis.com/auth/userinfo.email
      - https://www.googleapis.com/auth/userinfo.profile

  CreateResourceRequest:
    description: information to create a resource
    required:
      - resourceId
      - policies
    properties:
      resourceId:
        type: string
        description: id of the resource to create
      policies:
        type: array
        items:
          $ref: '#/definitions/AccessPolicyMembership'
        description: map of initial policies to create
      authDomain:
        type: array
        items:
          type: string

  Enabled:
    description: the status of the user's account
    required:
      - ldap
      - allUsersGroup
      - google
    properties:
      ldap:
        type: boolean
        description: true if the user is enabled in ldap
      allUsersGroup:
        type: boolean
        description: true if the user is in the all users group
      google:
        type: boolean
        description: true if the user is in their proxy group

  ErrorReport:
    description: ''
    required:
      - source
      - message
      - causes
      - stackTrace
    properties:
      source:
        type: string
        description: service causing error
      message:
        type: string
        description: what went wrong
      exceptionClass:
        type: string
        description: class of exception thrown
      statusCode:
        type: integer
        description: HTTP status code
      causes:
        type: array
        description: errors triggering this one
        items:
          $ref: '#/definitions/ErrorReport'
      stackTrace:
        type: array
        description: stack trace
        items:
          $ref: '#/definitions/StackTraceElement'

  ManagedGroupMembershipEntry:
    type: object
    description: 'specification of a managed group with an access policy and the email associated with the managed group'
    required:
      - groupName
      - role
      - groupEmail
    properties:
      groupName:
        type: string
        description: The name of the managed group
      role:
        type: string
        description: User's role in the group
      groupEmail:
        type: string
        description: The email address associated with the group

  ResourceAndAccessPolicy:
    type: object
    description: 'specification of a resource with an access policy'
    required:
      - resourceId
      - accessPolicyName
    properties:
      resourceId:
        type: string
        description: The id of the resource
      accessPolicyName:
        type: string
        description: User's policy for the resource

  ResourceRole:
    type: object
    description: 'specification of a role for a resource'
    required:
      - roleName
      - actions
    properties:
      roleName:
        type: string
        description: The name of the role
      actions:
        type: array
        items:
          type: string
        description: List of actions that can be performed by members of this role

  ResourceType:
    type: object
    description: 'specification of a type of resource'
    required:
      - name
      - actions
      - roles
      - ownerRoleName
    properties:
      name:
        type: string
        description: The name of the resource type
      actions:
        type: array
        items:
          type: string
        description: List of actions that can be performed on a resource of this type
      roles:
        type: array
        description: List of roles that may exist on a resource of this type
        items:
          $ref: '#/definitions/ResourceRole'
      ownerRoleName:
        type: string
        description: The name of the role that can perform administrative functions on a resource of this type

  StackTraceElement:
    description: ''
    required:
      - className
      - methodName
      - fileName
      - lineNumber
    properties:
      className:
        type: string
        description: class name
      methodName:
        type: string
        description: method name
      fileName:
        type: string
        description: source file name
      lineNumber:
        type: integer
        description: line number

  SubsystemStatus:
    description: status of a subsystem Sam depends on
    properties:
      ok:
        type: boolean
        description: whether this system is up or down from Sam's point of view
      messages:
        type: array
        items:
          type: string

  SyncReport:
    description: results of an attempt to synchronize a group
    type: object
    additionalProperties:
      type: array
      items:
        $ref: '#/definitions/ResourceAndAccessPolicy'

  SyncReportItem:
    description: results of an attempt to synchronize a member
    properties:
      operation:
        type: string
      email:
        type: string
      errorReport:
        $ref: '#/definitions/ErrorReport'

  SyncStatus:
    description: status of group synchronization
    required:
      - lastSyncDate
    properties:
      lastSyncDate:
        type: string

  SystemStatus:
    description: status of each aubsystem Sam depends on
    type: object
    required:
      - ok
      - systems
    properties:
      ok:
        type: boolean
        description: true if everything is ok, false if anything is amiss
      systems:
        type: object
        description: Map[String, SubsystemStatus]

  UserInfo:
    description: the user's details
    required:
      - userSubjectId
      - userEmail
    properties:
      userSubjectId:
        type: string
        description: user id
      userEmail:
        type: string
        description: user email

  UserStatus:
    description: ''
    required:
      - userInfo
      - enabled
    properties:
      userInfo:
        $ref: '#/definitions/UserInfo'
      enabled:
        $ref: '#/definitions/Enabled'
        description: the status of the user's account