permissionsService.yml

imports:
  common: ./common.yml
service:
  base-path: /v0/permissions
  auth: true
  availability: pre-release
  endpoints:
    checkResourceAuthorizationForUser:
      path: /checkResourceAuthorizationForUser
      docs: Admin endpoint to check whether the specified user is authorized to read the specified resource.
      method: POST
      request:
        name: CheckResourceAuthorizationForUserRequest
        body:
          properties:
            resourceIdentifier:
              type: common.ResourceIdentifier
              docs: |
                The resource identifier for which you want to check authorization.
            userEmail:
              type: string
              docs: |
                The user email to check authorization for.
            disableCache:
              type: optional<boolean>
              docs: |
                If specified, Credal will bypass the permissions cache and check current permissions for this resource
      response: CheckResourceAuthorizationResponse
      examples:
        - name: Example0
          request:
            resourceIdentifier:
              type: external-resource-id
              externalResourceId: 170NrBm0Do7gdzvr54UvyslPVWkQFOA0lgNycFmdZJQr
              resourceType: GOOGLE_DRIVE_ITEM
            userEmail: john.smith@foo.com
          response:
            body:
              authorized: true
    checkBulkResourcesAuthorizationForUser:
      path: /checkBulkResourcesAuthorizationForUser
      docs: Admin endpoint to check whether the specified user is authorized to read the specified set of resources.
      method: POST
      request:
        name: CheckBulkResourcesAuthorizationForUserRequest
        body:
          properties:
            resourceIdentifiers:
              type: list<common.ResourceIdentifier>
              docs: |
                The set of resource identifier for which you want to check authorization. Currently limited to 20 resources.
            userEmail:
              type: string
              docs: |
                The user email to check authorization for.
            disableCache:
              type: optional<boolean>
              docs: |
                If specified, Credal will bypass the permissions cache and check current permissions for all resources specified.
      response: CheckBulkResourcesAuthorizationResponse
      examples:
        - name: Example0
          request:
            resourceIdentifiers:
              - type: url
                url: https://docs.google.com/document/d/170NrBm0Do7gdzvr54UvyslPVWkQFOA0lgNycFmdZJQr/edit
              - type: external-resource-id
                externalResourceId: sfsdfvr54UvyslPVWkQFOA0dfsdfsdflgNycFmdZJQr
                resourceType: ZENDESK_TICKET
            userEmail: john.smith@foo.com
          response:
            body:
              - externalResourceId:
                  externalResourceId: 170NrBm0Do7gdzvr54UvyslPVWkQFOA0lgNycFmdZJQr
                  resourceType: GOOGLE_DRIVE_ITEM
                inputUrl: https://docs.google.com/document/d/170NrBm0Do7gdzvr54UvyslPVWkQFOA0lgNycFmdZJQr/edit
                authorized: true
              - externalResourceId:
                  externalResourceId: "123456"
                  resourceType: ZENDESK_TICKET
                authorized: true
    listCachedAuthorizedResourcesForUser:
      path: /listCachedAuthorizedResourcesForUser
      docs:
        Admin endpoint to list all resources that the specified user is authorized to read. Note this endpoint returns cached results and may not be up-to-date.
        You can use the checkResourceAuthorizationForUser endpoint with disableCache set to true to get the most up-to-date results.
      method: POST
      request:
        name: ListCachedAuthorizedResourcesForUserRequest
        body:
          properties:
            userEmail:
              type: string
              docs: |
                The user email to list authorized resources for.
            resourceType:
              type: optional<common.ResourceType>
              docs: |
                The type of resource you want to list. If not specified, all resource types will be listed.
            limit:
              type: optional<integer>
              docs: |
                The maximum number of resources to return. Defaults to 100.
            offset:
              type: optional<integer>
              docs: |
                The offset to use for pagination. If not specified, the first page of results will be returned.
      response: AuthorizedResourceListPage
      examples:
        - name: Example0
          request:
            userEmail: john.smith@foo.com
          response:
            body:
              - credalId: 2b5cf2b8-3df3-11ef-9a96-332d4470d189
                externalId:
                  externalResourceId: 170NrBm0Do7gdzvr54UvyslPVWkQFOA0lgNycFmdZJQr
                  resourceType: GOOGLE_DRIVE_ITEM
              - credalId: eb5a0a00-3d9a-11ef-836d-375bf4e237a6
                externalId:
                  externalResourceId: "123456"
                  resourceType: ZENDESK_TICKET
types:
  Group:
    properties:
      name: string
      id: optional<string>
  User:
    properties:
      email: string
      name: optional<string>
      id: optional<string>
  Principal:
    union:
      group: Group
      user: User
  AuthorizedResource:
    properties:
      credalId: uuid
      externalId: common.ExternalResourceId
  AuthorizedResourceListPage: list<AuthorizedResource>
  PrincipalListPage:
    properties:
      principals: list<Principal>
      nextPageToken: optional<string>
  CheckResourceAuthorizationResponse:
    properties:
      authorized: boolean
  ResourceAuthorizationResult:
    properties:
      externalResourceId: common.ExternalResourceId
      inputUrl: optional<string>
      authorized: boolean
  CheckBulkResourcesAuthorizationResponse:
    type: list<ResourceAuthorizationResult>
  Action:
    enum:
      - READ