openapi: 3.0.0
info:
  title: Fence OpenAPI Specification admin/user credentials/google API
  version: 0.1.0
  description: Access management for Gen3 data commons. Code is available on [GitHub](https://github.com/uc-cdis/fence).
  termsOfService: http://cdis.uchicago.edu/terms/
  contact:
    email: cdis@uchicago.edu
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://example.domain/
tags:
- name: credentials/google
  description: Google Credentials
paths:
  /credentials/google:
    get:
      tags:
      - credentials/google
      summary: List access keys
      description: List all the Google access keys for the current user
      security:
      - OAuth2:
        - user
      operationId: listGoogleKeypairs
      responses:
        '200':
          description: Google keys info response
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/GoogleKeys'
    post:
      tags:
      - credentials/google
      summary: Receive temporary access key
      description: Get a new temporary Google access key for the current user. The response from this represents exactly what should be placed in a JSON credentials file to pass to Google's APIs.
      security:
      - OAuth2:
        - user
      operationId: getGoogleKeypair
      parameters:
      - name: expires_in
        required: false
        in: query
        description: the time (in seconds) during which the access key is valid. Must be less than the configured maximum (default is 10 days). If it's greater, the configured maximum will be used.
        schema:
          type: integer
      - name: userProject
        required: false
        in: query
        description: a Google Project to bill for accessing data in requester pays buckets in Google Storage. Will override any configured default billing projects. If Fence is configured to automatically attempt to provide the necessary service account(s) billing permission, the provided Google Project will need to have given the Fence admin service account necessary permissions to create custom roles and set Project IAM policies. Please see README for more information.
        schema:
          type: string
      responses:
        '200':
          description: Temporary private Google key in Google Credentials File format
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/GoogleKey'
    delete:
      tags:
      - credentials/google
      summary: Delete access keys
      description: Delete all Google access key for the current user/client
      security:
      - OAuth2:
        - user
      operationId: deleteAllGoogleKeypair
      parameters:
      - name: all
        required: true
        in: query
        description: Must be "true" to delete all keys
        schema:
          type: string
      responses:
        '204':
          description: successful deletion
        '404':
          description: Couldn't find key or service account for current user, unable to delete given key
        '405':
          description: all param not provided and is required to explicitly delete all keys
  /credentials/google/{access_key}:
    delete:
      tags:
      - credentials/google
      summary: Delete access key
      description: Delete a Google access key for the current user
      security:
      - OAuth2:
        - user
      operationId: deleteGoogleKeypair
      parameters:
      - name: access_key
        required: true
        in: path
        description: Google Key ID
        schema:
          type: string
      responses:
        '204':
          description: successful deletion
        '404':
          description: Couldn't find key or service account for current user, unable to delete given key
components:
  schemas:
    GoogleKey:
      type: object
      description: decoded Google private key data from privateKeyData field https://cloud.google.com/iam/reference/rest/v1/projects.serviceAccounts.keys#ServiceAccountPrivateKeyType
      properties:
        type:
          type: string
        project_id:
          type: string
        private_key_id:
          type: string
        private_key:
          type: string
        client_email:
          type: string
        client_id:
          type: string
        auth_uri:
          type: string
        token_uri:
          type: string
        auth_provider_x509_cert_url:
          type: string
        client_x509_cert_url:
          type: string
      example:
        type: service_account
        project_id: project-id
        private_key_id: some_number
        private_key: '-----"BEGIN PRIVATE KEY-----\n..." =\n-----END "PRIVATE KEY-----\n"'
        client_email: api@project-id.iam.gserviceaccount.com
        client_id: '...'
        auth_uri: https://accounts.google.com/o/oauth2/auth
        token_uri: https://accounts.google.com/o/oauth2/token
        auth_provider_x509_cert_url: https://www.googleapis.com/oauth2/v1/certs
        client_x509_cert_url: https://www.googleapis.com/...api%40project-id.iam.gserviceaccount.com
    GoogleKeys:
      type: object
      properties:
        access_keys:
          type: array
          description: List of Google keys info
          items:
            type: object
            properties:
              keyAlgorithm:
                type: string
                description: Specifies the algorithm (and possibly key size) for the key.
              validBeforeTime:
                type: string
                description: The key can be used before this timestamp.
              name:
                type: string
                description: The resource name of the service account key in the following format projects/{PROJECT_ID}/serviceAccounts/{ACCOUNT}/keys/{key}.
              validAfterTime:
                type: string
                description: The key can be used after this timestamp.
      example:
        access_keys:
        - keyAlgorithm: KEY_ALG_RSA_2048
          validBeforeTime: '2028-03-11T18:27:41Z'
          name: projects/example/serviceAccounts/example@example.iam.gserviceaccount.com/keys/1234567890abcdefghijklmnop
          validAfterTime: '2018-03-14T18:27:41Z'
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          scopes:
            user: generic user access