openapi: 3.1.0
info:
  title: WD My Cloud Home Authentication API
  description: The WD My Cloud Home REST API enables off-device applications to manage files and folders on a user's My Cloud Home NAS device. It supports file upload, download, listing, search, sharing, thumbnails, and device discovery via OAuth 2.0 authentication.
  version: v2
  termsOfService: https://www.westerndigital.com/legal/terms-of-use
  contact:
    name: Western Digital Developer Support
    url: https://developer.westerndigital.com/develop/wd-my-cloud-home/forms.html
  license:
    name: Western Digital Developer Terms
    url: https://developer.westerndigital.com/develop/wd-my-cloud-home/
servers:
- url: https://config.mycloud.com
  description: Configuration service — call first to get device and auth URLs
- url: https://device.mycloud.com
  description: Device service (dynamically resolved per device)
- url: https://wdc.auth0.com
  description: Authentication service
tags:
- name: Authentication
  description: OAuth 2.0 authorization and token operations.
paths:
  /authorize:
    get:
      operationId: authorizeUser
      summary: Authorize User
      description: Initiates the OAuth 2.0 authorization code flow. Redirects the user to the WD authentication page.
      tags:
      - Authentication
      servers:
      - url: https://wdc.auth0.com
      parameters:
      - name: client_id
        in: query
        required: true
        schema:
          type: string
        description: OAuth 2.0 client identifier.
      - name: redirect_uri
        in: query
        required: true
        schema:
          type: string
          format: uri
        description: URI to redirect to after authorization.
      - name: response_type
        in: query
        required: true
        schema:
          type: string
          enum:
          - code
        description: Must be "code" for authorization code flow.
      - name: scope
        in: query
        required: false
        schema:
          type: string
        description: 'Space-separated list of scopes. Supported: openid, email, profile, nas_read_only, nas_read_write.'
      - name: state
        in: query
        required: false
        schema:
          type: string
        description: CSRF protection state parameter.
      responses:
        '302':
          description: Redirect to authorization page.
  /oauth/token:
    post:
      operationId: getAccessToken
      summary: Get Access Token
      description: Exchange authorization code for an OAuth 2.0 access token. Also supports refresh_token grant type when offline_access scope was requested.
      tags:
      - Authentication
      servers:
      - url: https://wdc.auth0.com
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum:
                  - authorization_code
                  - refresh_token
                  description: OAuth 2.0 grant type.
                code:
                  type: string
                  description: Authorization code from the redirect.
                client_id:
                  type: string
                  description: OAuth 2.0 client identifier.
                client_secret:
                  type: string
                  description: OAuth 2.0 client secret.
                redirect_uri:
                  type: string
                  description: Redirect URI matching the original request.
                refresh_token:
                  type: string
                  description: Refresh token (for refresh_token grant).
              required:
              - grant_type
              - client_id
              - client_secret
      responses:
        '200':
          description: Access token response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
components:
  schemas:
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
          description: OAuth 2.0 access token.
        token_type:
          type: string
          enum:
          - Bearer
        expires_in:
          type: integer
          description: Token lifetime in seconds.
        refresh_token:
          type: string
          description: Refresh token (if offline_access scope requested).
        id_token:
          type: string
          description: OpenID Connect ID token.
        scope:
          type: string
          description: Space-separated list of granted scopes.
      required:
      - access_token
      - token_type
      - expires_in
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 Bearer token obtained via the /oauth/token endpoint. Include in Authorization header as "Bearer {token}".