University of Chicago Gen3 Fence — credentials/api API

openapi: 3.0.0
info:
  title: Gen3 Fence OpenAPI Specification — credentials/api API
  version: 0.1.0
  description: >-
    Fence is the Gen3 authentication and authorization service, authored by the University of Chicago Center for Translational Data Science.
    Code: 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://gen3.datacommons.io/
  description: >-
    University of Chicago Center for Translational Data Science (CTDS) reference Gen3 data
    commons. Gen3 is deployable software authored by CTDS (github.com/uc-cdis), so the upstream
    specification ships a placeholder host; this is the base URL of the deployment CTDS itself
    operates. The datacommons.io domain is registered to CDIS, University of Chicago.
  x-operator: institution
  x-verified: '2026-08-19'
  x-verified-evidence: https://gen3.datacommons.io/.well-known/openid-configuration
tags:
- name: credentials/api
  description: API Credentials
paths:
  /credentials/api:
    get:
      tags:
      - credentials/api
      summary: List API keys for user
      description: List all the API keys for the current user
      security:
      - OAuth2:
        - user
      operationId: listAPIKeypairs
      responses:
        '200':
          description: List of API keys issued to user and their expiration
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/APIKeys'
    post:
      tags:
      - credentials/api
      summary: Receive API key
      description: Get a new API key for the current user. API keys can be used to retrieve access tokens which will allow for authed communication to our API. Can pass a list of requested OIDC scopes in the body. Automatically gives "openid" scope. Any additional scopes (like "user" for seeing user information or "data" for hitting signed url endpoint) must be explicitly requested and user must already have access.
      security:
      - OAuth2:
        - user
      operationId: getAPIKeypair
      responses:
        '200':
          description: API key id and actual key
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/NewAPIKey'
      requestBody:
        $ref: '#/components/requestBodies/APIKeyScopes'
  /credentials/api/{key_id}:
    delete:
      tags:
      - credentials/api
      summary: Delete user API key
      description: Delete a API access key for the current user
      security:
      - OAuth2:
        - user
      operationId: deleteAPIKeypair
      parameters:
      - name: key_id
        required: true
        in: path
        description: API Key key_id/jti
        schema:
          type: string
      responses:
        '204':
          description: successful deletion
        '404':
          description: Couldn't find key for current user, unable to delete given key
  /credentials/api/access_token:
    post:
      tags:
      - credentials/api
      summary: Receive access token when given API key
      description: Get a new temporary access token for the current user by providing a valid API key.
      security:
      - OAuth2:
        - user
      operationId: getAccessToken
      responses:
        '200':
          description: Access token
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/AccessToken'
      requestBody:
        $ref: '#/components/requestBodies/APIKey'
components:
  schemas:
    APIKeys:
      type: object
      properties:
        jtis:
          type: array
          description: List of API keys issued to the user
          items:
            type: object
            properties:
              jti:
                type: string
                description: JWT ID / key id
              exp:
                type: integer
                description: Key expiration (JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time)
      example:
        jtis:
        - jti: e9d58890-99b0-44f0-88bd-3ebc370b1329
          exp: 12345678
    AccessToken:
      type: object
      properties:
        access_token:
          type: string
          description: JWT access token
      example:
        access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.XbPfbIHMI6arZ3Y922BhjWgQzWXcXNrz0ogtVhfEd2o
    APIKeyScopes:
      type: object
      properties:
        scope:
          type: array
          description: list of OIDC scopes for the API Key
          items:
            type: string
      example:
        scope:
        - user
        - data
    APIKey:
      type: object
      properties:
        api_key:
          type: string
          description: JWT representing API key
      example:
        api_key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.XbPfbIHMI6arZ3Y922BhjWgQzWXcXNrz0ogtVhfEd2o
    NewAPIKey:
      type: object
      properties:
        key_id:
          type: string
          description: Key identifier
        api_key:
          type: string
          description: JWT representing API key
      example:
        key_id: e9d58890-99b0-44f0-88bd-3ebc370b1329
        api_key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.XbPfbIHMI6arZ3Y922BhjWgQzWXcXNrz0ogtVhfEd2o
  requestBodies:
    APIKey:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIKey'
      description: API key
      required: true
    APIKeyScopes:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/APIKeyScopes'
      description: API key scopes
      required: false
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          scopes:
            user: generic user access