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.2.2 x-logo: url: logo.png servers: - url: https://{discovery_fqdn} variables: discovery_fqdn: default: my-cloud-storage.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://my-cloud-storage.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.2.2 endPoint: type: string description: The URI of the OCM API available at this endpoint example: https://my-cloud-storage.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 - webdav-uri - protocol-object - invites - exchange-token - http-sig 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 publicKeys array 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://my-cloud-storage.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----- publicKeys: type: array description: > Array of public keys for RFC 9421 HTTP Message Signatures. Servers advertising the "rfc-http-sig" capability MUST provide this field. Clients SHOULD prefer RFC 9421 signatures when this capability is present. items: type: object required: - keyId - publicKeyPem - algorithm properties: keyId: type: string format: uri description: > Unique identifier for this key in URI format. Hostname MUST match the discovery endpoint hostname. example: https://my-cloud-storage.org/ocm#key-1 publicKeyPem: type: string description: | PEM-encoded public key for RFC 9421 signatures. example: | -----BEGIN PUBLIC KEY----- MCowBQYDK2VwAyEA... -----END PUBLIC KEY----- algorithm: type: string description: > Cryptographic algorithm identifier from the IANA HTTP Signature Algorithms Registry as defined in RFC 9421 Section 6.2. example: ed25519 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: accessType: 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: accessType: 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: accessType: ['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@my-cloud-storage.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