openapi: 3.0.3
info:
  title: Open Cloud Mesh API
  description: >
    Open Cloud Mesh OpenAPI Specification.
    The semantic of the Protocol Specification is detailed in the
    [IETF-RFC.md](https://github.com/cs3org/OCM-API/blob/develop/IETF-RFC.md) document.
  version: 1.3.0
  x-logo:
    url: logo.png
servers:
  - url: https://{discovery_fqdn}
    variables:
      discovery_fqdn:
        default: cloud.example.org
paths:
  /.well-known/ocm:
    get:
      summary: Discovery endpoint
      description: >
        Following [RFC8615], this endpoint returns the properties and
        capabilities offered by an OCM Server. This endpoint MUST be
        served at the OCM Server's root FQDN, e.g. as in
        `https://cloud.example.org/.well-known/ocm`. See [OCM API Discovery](https://github.com/cs3org/OCM-API/blob/develop/IETF-RFC.md#ocm-api-discovery)
        for more details.
      responses:
        "200":
          description: The API endpoint, version, public key, and capabilities of this OCM
            Server
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Discovery"
  /ocm-provider:
    get:
      summary: Legacy discovery endpoint
      description: >
        This endpoint is a replica of `/.well-known/ocm`, and MUST be served
        at the OCM Server's root FQDN as well to ensure backwards compatibility.
        OCM Servers MUST support both.
      responses:
        "200":
          description: See `/.well-known/ocm`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Discovery"
  /shares:
    post:
      summary: Share Creation Notification endpoint
      description: >
        This endpoint is used by a Sending Server to notify a Receiving Server that
        a new Share has been created. See [Share Creation Notification](https://github.com/cs3org/OCM-API/blob/develop/IETF-RFC.md#share-creation-notification)
        for more details.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewShare"
        description: The JSON object to create a new share at the consumer side.
        required: true
      responses:
        "201":
          description: >
            Consumer successfully received the share. The response might contain
            the display name of the recipient of the share for general user
            experience improvement.
          content:
            application/json:
              schema:
                type: object
                properties:
                  recipientDisplayName:
                    type: string
                    description: >
                      Display name of the recipient
                    example: John Doe
                  recipientPublicKeys:
                    type: array
                    items:
                      type: string
                    description: >
                      The public key(s) of the recipient. This value MUST be provided
                      in case the Share Creation Notification includes the `ssh` protocol.
        "400":
          description: >
            Bad request due to invalid parameters, e.g. when `shareWith` is not
            found or required properties are missing.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/400"
        "401":
          description: Sender cannot be authenticated as a trusted service.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Sender is not authorized to create shares.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "501":
          description: The Receiver doesn't support incoming external shares, the share
            type or the resource type is not supported.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "503":
          description: The Receiver is temporary unavailable (e.g. due to planned
            maintenance).
          headers:
            Retry-After:
              description: >
                Indication for the client when the service could be requested
                again in HTTP Date format as used by the Internet Message
                Format [RFC5322] (e.g. `Wed, 21 Oct 2015 07:28:00 GMT`) or the
                number of seconds (e.g. 3000 if you the service is expected to
                be available again within 50 minutes).
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /notifications:
    post:
      summary: Share Acceptance Notification endpoint
      description: >
        This optional endpoint is used to inform the other party about a change
        that concerns a previously known entity, such as a Share or a trusted User.
        See [Share Acceptance Notification](https://github.com/cs3org/OCM-API/blob/develop/IETF-RFC.md#share-acceptance-notification)
        for more details.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewNotification"
        description: The JSON object with a new notification
        required: true
      responses:
        "201":
          description: >
            Receiver succesfully received the notification. The response body
            MAY contain
            a JSON object with some resonse data, depending on the actual notification.
        "400":
          description: |
            Bad request due to invalid parameters, e.g. when `type` is invalid
            or missing.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/400"
        "401":
          description: Client cannot be authenticated as a trusted service.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Trusted service is not authorized to create notifications.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "501":
          description: |
            The receiver doesn't support notifications, the resource type is not
            supported.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "503":
          description: |
            The receiver is temporary unavailable (e.g. due to planned
            maintenance).
          headers:
            Retry-After:
              description: |
                Indication for the client when the service could be requested
                again in HTTP Date format as used by the Internet Message Format
                [RFC5322] (e.g. `Wed, 21 Oct 2015 07:28:00 GMT`) or the number
                of seconds (e.g. 3000 if you the service is expected to be
                available again within 50 minutes).
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /invite-accepted:
    post:
      summary: Invitation Acceptance endpoint
      description: >
        This optional endpoint is used to inform the Sender that an Invitation was accepted.
        See [Invite flow](https://github.com/cs3org/OCM-API/blob/develop/IETF-RFC.md#invite-flow)
        for more details.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AcceptedInvite"
        description: The JSON object to notify the OCM provider that an invite has been
          accepted.
        required: true
      responses:
        "200":
          description: Invitation Acceptance Request successful (see [Invite Acceptance
            Response](https://github.com/cs3org/OCM-API/blob/develop/IETF-RFC.md#invite-acceptance-response-details))
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AcceptedInviteResponse"
        "400":
          description: The Invitation Token is invalid or does not exist (see [Invite
            Acceptance
            Response](https://github.com/cs3org/OCM-API/blob/develop/IETF-RFC.md#invite-acceptance-response-details))
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Invite Receiver OCM Server is not trusted to accept this Invite
            (see [Invite Acceptance
            Response](https://github.com/cs3org/OCM-API/blob/develop/IETF-RFC.md#invite-acceptance-response-details))
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Invitation already accepted (see [Invite Acceptance
            Response](https://github.com/cs3org/OCM-API/blob/develop/IETF-RFC.md#invite-acceptance-response-details))
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  parameters:
    id:
      name: id
      in: path
      description: Unique ID to identify the share at the consumer side.
      required: true
      schema:
        type: string
    page:
      name: page
      in: query
      required: false
      description: >
        Default parameter to handle paging through collections. However, this
        parameter is NOT mandatory, as clients should use the HAL navigation
        links (e.g. `_links.next.href`) to paginate. These links enable the
        possibility to use vendor specific pagination.
      schema:
        type: integer
        default: 1
  schemas:
    "400":
      type: object
      allOf:
        - $ref: "#/components/schemas/Error"
        - properties:
            validationErrors:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                    example: shareWith
                  message:
                    type: string
                    description: >
                      A validation error message which is understandable for
                      both humans and machines (e.g. no use of special
                      characters) providing more information on the cause of the
                      validation error.
                    example: NOT_FOUND
    Error:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: >
            An error message which is understandable for both humans and
            machines (e.g. no use of special characters) providing more
            information on the cause of the error.
          example: RESOURCE_NOT_FOUND
    Discovery:
      type: object
      required:
        - enabled
        - apiVersion
        - endPoint
        - resourceTypes
      properties:
        enabled:
          type: boolean
          description: Whether the OCM service is enabled at this endpoint
        apiVersion:
          type: string
          description: The OCM API version this endpoint supports
          example: 1.3.0
        endPoint:
          type: string
          description: The URI of the OCM API available at this endpoint
          example: https://cloud.example.org/ocm
        provider:
          type: string
          description: A friendly branding name of this endpoint
          example: MyCloudStorage
        resourceTypes:
          type: array
          description: |
            A list of all supported resource types with their access protocols.
            Each resource type is identified by its `name`: the list MUST NOT
            contain more than one resource type object per given `name`.
          items:
            type: object
            properties:
              name:
                type: string
                description: >
                  A supported resource type (file, calendar, contact, ...).
                  Implementations MUST offer support for at least one resource type,
                  where `file` is the commonly supported one.
                  Each resource type is identified by its `name`: the list MUST NOT
                  contain more than one resource type object per given `name`
                example: file
              shareTypes:
                type: array
                description: |
                  The supported recipient share types.
                  MUST contain `"user"` at a minimum, plus optionally
                  `"group"` and `"federation"`.
                items:
                  type: string
                  enum:
                    - user
                    - group
                    - federation
                example:
                  - user
              protocols:
                type: object
                description: >
                  The supported protocols to access shared resources at this endpoint.
                  Implementations MUST support at least `webdav` for `file` resources,
                  any other combination of resources and protocols is optional.
                properties:
                  webdav:
                    type: string
                    description: >
                      The top-level WebDAV path at this endpoint. In order to access
                      a remote shared resource, implementations SHOULD use this path
                      as a prefix (see sharing examples).
                  webapp:
                    type: string
                    description: >
                      The top-level path for web apps at this endpoint. In order to
                      access a remote web app, implementations SHOULD use this path
                      as a prefix (see sharing examples).
                  ssh:
                    type: string
                    description: >
                      The top-level address in the form `host:port` of an endpoint
                      that supports ssh and scp with a public/private key based
                      authentication.
                additionalProperties:
                    type: string
                    description: >
                      Any additional protocol supported for this resource type MAY
                      be advertised here, where the value MAY correspond to a top-level
                      URI to be used for that protocol.
                example:
                  webdav: /remote/dav/ocm/
                  webapp: /apps/ocm/
                  talk: /apps/spreed/api/
        capabilities:
          type: array
          description: >
            The optional capabilities exposed at this endpoint according to the
            present specifications.
          items:
            type: string
            enum:
              - enforce-mfa
              - exchange-token
              - http-sig
              - invites
              - invite-wayf
              - notifications
              - protocol-object
              - webdav-uri
          example:
            - webdav-uri
            - protocol-object
            - http-sig
        criteria:
          type: array
          description: |
            The criteria for accepting a Share Creation Notification.
            As all Receiving Servers should require the use of TLS in API calls,
            it is not necessary to expose that as a criterium.
          items:
            type: string
            enum:
              - http-request-signatures
              - token-exchange
              - denylist
              - allowlist
              - invite
          example:
            - allowlist
            - invite
        publicKey:
          type: object
          deprecated: true
          description: >
            DEPRECATED: Use public keys from /.well-known/jwks.json
            instead for RFC 9421 support.
            Legacy field for draft-cavage HTTP Signatures (RSA only).
            Maintained for backward compatibility with existing deployments.
            The signatory is optional but it MUST contain `keyId` and `publicKeyPem`.
          properties:
            keyId:
              type: string
              description: >
                unique id of the key in URI format. The hostname set the origin
                of the request and MUST be identical to the current discovery endpoint.
              example: https://cloud.example.org/ocm#signature
            publicKeyPem:
              type: string
              description: |
                PEM-encoded RSA public key for draft-cavage signatures.
              example: |
                -----BEGIN PUBLIC KEY-----
                MII...QDD
                -----END PUBLIC KEY-----
        tokenEndPoint:
          type: string
          format: uri
          description: >
            Optional URL path of the Token Exchange endpoint to obtain bearer tokens in exchange for codes.
            If the `exchange-token` capability is exposed, the tokenEndPoint MUST be advertised in the discovery response.

            **Token Exchange API:**
            This optional endpoint allows obtaining a (potentially short-lived) bearer token in exchange for a secret.

            **HTTP Request:**
            - Method: POST
            - URL: The URL discovered in this field
            - Content-Type: application/x-www-form-urlencoded
            - Body: TokenRequest schema (form-encoded, required)

            **HTTP Responses:**
            - 200: Token issued (application/json with TokenResponse schema)
            - 400: Token denied (application/json with Error schema)

            See TokenRequest and TokenResponse schemas for the complete data structure.
          example: /index.php/apps/sciencemesh/token
        inviteAcceptDialog:
          type: string
          description: >
            Optional URL path of a web page where a user can accept an invite, when query parameters `"token"` and `"providerDomain"` are provided.
            Implementations that offer the `invites` capability SHOULD provide this URL as well in order to enhance the UX of the Invite Flow.
            If for example `"/index.php/apps/sciencemesh/accept"` is specified here then a Where-Are-You-From page could redirect the end-user
            to `/index.php/apps/sciencemesh/accept?token=zi5kooKu3ivohr9a&providerDomain=example.com`.
          example: /index.php/apps/sciencemesh/accept
    NewShare:
      type: object
      required:
        - shareWith
        - name
        - providerId
        - owner
        - sender
        - shareType
        - resourceType
        - protocol
      properties:
        shareWith:
          type: string
          description: >
            OCM Address of the user, group or federation the
            provider wants to share the resource with. This MUST be known
            in advance, either via a previous Invitation or through other means.
          example: 51dc30ddc473d43a6011e9ebba6ca770@geant.org
        name:
          type: string
          description: Name of the resource (file or folder).
          example: resource.txt
        description:
          type: string
          description: Optional description of the resource (file or folder).
          example: |
            This is the Open API Specification file (in YAML format) of the Open
            Cloud Mesh API.
        providerId:
          type: string
          description: >
            Opaque value to identify the Shared Resource at the provider side.
            This MUST be unique per Resource and per share, such that multiple
            shares of a given Resource are guaranteed to get different values.
          example: 7c084226-d9a1-11e6-bf26-cec0c932ce01
        owner:
          description: |
            OCM Address of the user who owns the resource.
          type: string
          example: 6358b71804dfa8ab069cf05ed1b0ed2a@apiwise.nl
        sender:
          description: |
            OCM Address of the user that wants to share the
            resource.
          type: string
          example: 527bd5b5d689e2c32ae974c6229ff785@apiwise.nl
        ownerDisplayName:
          type: string
          description: |
            Display name of the owner of the resource
          example: Dimitri
        senderDisplayName:
          type: string
          description: |
            Display name of the user that wants to share the resource
          example: John Doe
        shareType:
          type: string
          enum:
            - user
            - group
            - federation
          description: |
            Recipient share type
          example: user
        resourceType:
          type: string
          description: |
            Resource type (file, folder, calendar, contact, ...)
          example: file
        expiration:
          type: integer
          description: >
            The expiration time for the share, in seconds of UTC time since Unix
            epoch. If omitted, it is assumed that the share does not expire. A sender
            server MAY use the `expiration` to signal that the resource represents
            a cached copy of a dataset that was made available for an efficient
            data transfer to the destination server.
        protocol:
          type: object
          description: |
            JSON object with specific options for each protocol.
            The supported protocols are:
            - `webdav`, to access the data via WebDAV
            - `webapp`, to access remote web applications
            - `ssh`, to access the data via SFTP/SCP
            Other custom protocols might be added in the future.
          required:
            - name
          properties:
            name:
              type: string
              description: >
                The name of the protocol. Default: `multi`.
                If `multi` is given, one or more protocol endpoints are expected
                to be defined according to the optional properties specified below.
                Otherwise, at least `webdav` is expected to be supported, and
                its options MAY be given in the opaque `options` payload for
                compatibility with v1.0 implementations (see examples). Note
                though that this format is deprecated.
                Warning: client implementers should be aware that v1.1 servers
                MAY support both `webdav` and `multi`, but v1.0 servers MAY
                only support `webdav`.
                This field may be removed in a future major version of the spec.
            options:
              type: object
              description: >
                This property is now deprecated. Implementations are
                encouraged to
                transition to the new optional properties defined below, such that
                this field may be removed in a future major version of the spec.
            webdav:
              type: object
              required:
                - uri
                - permissions
              properties:
                accessTypes:
                  type: array
                  description: >
                    The type of access being granted to the remote resource.
                    If omitted, it defaults to `['remote']`.
                    - `remote` signals the recipient that the resource is available
                      for remote access and interactive browsing.
                    - `datatx` signals the recipient to transfer the resource
                      from the given URI. The recipient MAY delegate a third-party
                      service to execute the data transfer on their behalf.
                  items:
                    type: string
                    enum:
                      - remote
                      - datatx
                uri:
                  type: string
                  description: >
                    An URI to access the remote resource. The URI SHOULD be relative,
                    such as a key or a UUID, in which case the prefix exposed by the
                    `/.well-known/ocm` endpoint MUST be used to access the resource, or
                    it MAY be absolute, including a hostname. The latter is deprecated.
                    In all cases, for a `folder` resource, the composed URI acts
                    as the root path, such that other files located within it SHOULD
                    be accessible by appending their relative path to that URI.
                sharedSecret:
                  type: string
                  description: >
                    A secret to be used to access the resource, such as a bearer token.
                    To prevent leaking it in logs it MUST NOT appear in any URI.
                permissions:
                  type: array
                  description: >
                    The permissions granted to the sharee.
                    - `read` allows read-only access including download of a copy.
                    - `write` allows create, update, and delete rights on the resource.
                    - `share` allows re-share rights on the resource.
                  items:
                    type: string
                    enum:
                      - read
                      - write
                      - share
                requirements:
                  type: array
                  items:
                    type: string
                    description: >
                      A list of requirements that the recipient provider MUST fulfill
                      to access the resource. Requirements are optional, but if it is
                      present it MUST NOT be empty. A recipient provider MUST reject
                      a share whose requirements it does not understand.
                      The following requirements are currently supported:
                      - `must-use-mfa` requires the user accessing the resource to be
                        MFA-authenticated. This requirement MAY be used if the
                        recipient provider exposes the `enforce-mfa` capability.
                      - `must-exchange-token` requires the recipient to exchange the given
                        `sharedSecret` via a signed HTTPS request to tokenEndPoint at the
                        Sending Server, in order to get a short-lived token to be used
                        for subsequent access [RFC6749]. This requirement MAY be used if
                        the recipient provider exposes the `exchange-token` capability.
                    enum:
                      - must-use-mfa
                      - must-exchange-token
                size:
                  type: integer
                  description: >
                    The size of the resource to be transferred, useful especially
                    in case of `datatx` access type.
            webapp:
              type: object
              properties:
                uri:
                  type: string
                  description: >
                    An URI to a client-browsable view of the remote resource, such that
                    users may use a web application available at the sender site.
                    The URI SHOULD be relative, such as a key or a UUID, in which case
                    the prefix exposed by the `/.well-known/ocm` endpoint MUST be used
                    to access the resource, or it MAY be absolute, including a hostname.
                    Similar considerations as for the `webdav` case apply here.
                    In all cases, for a `folder` resource, the composed URI acts
                    as the root path, such that other files located within SHOULD
                    be accessible by appending their relative path to that URI.
                viewMode:
                  type: string
                  description: |
                    The permissions granted to the sharee.
                    - `view` allows access to the web app in view-only mode.
                    - `read` allows read and download access via the web app.
                    - `write` allows full editing rights via the web app.
                  enum:
                    - view
                    - read
                    - write
                sharedSecret:
                  type: string
                  description: >
                    An optional secret to be used to access the remote web app, such as
                    a bearer token.  To prevent leaking it in logs it MUST NOT appear
                    in any URI.  In a multi-protocol share scenario with WebDAV, the
                    access requirements provided in the `webdav` part MUST apply for
                    `webapp` accesses as well.
            ssh:
              type: object
              properties:
                accessTypes:
                  type: array
                  description: >
                    The type of access being granted to the remote resource.
                    If omitted, it defaults to `['remote']`.
                    - `remote` signals the recipient that the resource is available
                      for remote access, e.g. via sshfs.
                    - `datatx` signals the recipient to transfer the resource from
                      the given URI via scp. The recipient MAY delegate a third-party
                      service to execute the data transfer on their behalf.
                  items:
                    type: string
                    enum:
                      - remote
                      - datatx
                uri:
                  type: string
                  description: >
                    The full address to be used for ssh or scp access, in the form
                    `username@host.fqdn:port/resource/path`, where authentication is
                    expected to take place via public/private key.
          additionalProperties:
            type: object
            description: >
              Any optional additional protocols supported for this resource
              MAY be provided here, along with their custom payload. Appropriate
              capabilities SHOULD be advertised in order for a sender to ensure
              the recipient can parse such customized payloads.
          example:
            singleProtocolLegacy:
              name: webdav
              options:
                sharedSecret: hfiuhworzwnur98d3wjiwhr
                permissions: some permissions scheme
            singleProtocolNew:
              name: multi
              webdav:
                uri: 7c084226-d9a1-11e6-bf26-cec0c932ce01
                sharedSecret: hfiuhworzwnur98d3wjiwhr
                permissions:
                  - read
                  - write
            multipleProtocols:
              name: multi
              webdav:
                accessTypes: ['remote', 'datatx']
                uri: 7c084226-d9a1-11e6-bf26-cec0c932ce01
                sharedSecret: hfiuhworzwnur98d3wjiwhr
                permissions:
                  - read
                requirements:
                  - mfa-enforced
              webapp:
                uri: 7c084226-d9a1-11e6-bf26-cec0c932ce01
                sharedSecret: hfiuhworzwnur98d3wjiwhr
                viewMode: read
              ssh:
                accessType: ['datatx']
                uri: extuser@cloud.example.org:/7c084226-d9a1-11e6-bf26-cec0c932ce01
    NewNotification:
      type: object
      required:
        - notificationType
        - resourceType
        - providerId
      properties:
        notificationType:
          type: string
          description: |
            A notification type that is understandable for both humans and
            machines (e.g. no use of special characters) providing more
            information on the cause of the error.
            Values that MAY be used by implementations are:
            `SHARE_ACCEPTED`, `SHARE_DECLINED`, `REQUEST_RESHARE`,
            `SHARE_UNSHARED`, `RESHARE_UNDO`, `RESHARE_CHANGE_PERMISSION`,
            `USER_REMOVED`.
        resourceType:
          type: string
          description: |
            Resource type (file, folder, user, calendar, contact, ...)
        providerId:
          type: string
          description: |
            Identifier of the shared resource. If the resourceType is `file`,
            then see `NewShare/providerId` for the required information.
            If the resourceType is `user`, then this is the user identifier
            previously sent via `/invite-accepted`.
        notification:
          type: object
          description: |
            Optional additional parameters, depending on the notification
            and the resource type.
      example:
        shareWasAccepted:
          notificationType: SHARE_ACCEPTED
          resourceType: file
          providerId: 7c084226-d9a1-11e6-bf26-cec0c932ce01
          notification:
            message: Recipient accepted the share
            sharedSecret: hfiuhworzwnur98d3wjiwhr
        userWasRemoved:
          notificationType: USER_REMOVED
          resourceType: user
          providerId: 51dc30ddc473d43a6011e9ebba6ca770
    AcceptedInvite:
      type: object
      required:
        - recipientProvider
        - token
        - userID
        - email
        - name
      properties:
        recipientProvider:
          type: string
          format: fqdn
          description: FQDN of the receiver OCM service.
          example: receiver.org
        token:
          type: string
          description: Token received in the invite
          example: xyz
        userID:
          type: string
          description: Unique ID to identify the Invite Receiver at their OCM Server.
          example: 51dc30ddc473d43a6011e9ebba6ca770
        email:
          type: string
          description: Email address of the Invite Receiver.
          example: richard@gmail.com
        name:
          type: string
          description: Name of the Invite Receiver.
          example: Richard Feynman
    AcceptedInviteResponse:
      type: object
      required:
        - userID
        - email
        - name
      properties:
        userID:
          type: string
          description: Unique ID to identify the Invite Sender at their OCM Server.
          example: 9302
        email:
          type: string
          description: Email ID of the Invite Sender.
          example: john@sender.org
        name:
          type: string
          description: Name of the Invite Sender.
          example: John Doe
    TokenRequest:
      type: object
      required:
        - grant_type
        - client_id
        - code
      properties:
        client_id:
          type: string
          format: fqdn
          description: FQDN of the Receiving Server.
          example: receiver.org
        code:
          type: string
          description: Secret received in the Share Creation Notification
          example: xyz
        grant_type:
          type: string
          description: Must be set to 'authorization_code'
          enum: ["authorization_code"]
          example: authorization_code
        redirect_uri:
          type: string
          description: >
            Optional parameter that MUST be ignored by the server.
          example: https://receiver.org/ocm/callback
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
          description: The bearer token to be used to access the protocol-specific API(s)
          example: asdfgh
        token_type:
          type: string
          description: Must be set to 'Bearer'
          example: Bearer
        expires_in:
          type: number
          description: Number of seconds before this access_token will need to be refreshed.
          example: 300
