# coding: utf-8

"""
    BinoAuth Tenant API

     A comprehensive multi-tenant authentication and authorization API supporting OAuth2, OpenID Connect, API keys, and multiple authentication methods.  ## Features  - **Multi-Tenant Architecture**: Isolated tenant-specific authentication - **OAuth2 & OpenID Connect**: Full OAuth2/OIDC implementation with PKCE support - **API Keys**: Long-lived keys for programmatic access - **Multiple Auth Methods**: Password, magic links, phone OTP, social login, MFA - **Session Management**: Secure session handling with Redis backing - **Comprehensive Security**: Rate limiting, audit logging, secure token handling  ## Authentication Methods  ### 1. Session-Based (Web Applications) - HTTP-only secure cookies - Automatic session management - CSRF protection  ### 2. API Keys (Programmatic Access) - Long-lived keys with scoped permissions - SHA-256 hashed storage - Usage tracking and analytics - **Header**: `X-API-Key: ak_live_...`  ### 3. OAuth2 Bearer Tokens - Short-lived JWT tokens - Full OAuth2/OIDC support - Refresh token capability - **Header**: `Authorization: Bearer ...`  ## Getting Started  ### For Web Applications 1. Use `/auth/login` for password authentication 2. Session cookies are automatically managed 3. Access protected endpoints directly  ### For Mobile Applications   1. Use OAuth2 authorization code flow with PKCE 2. Handle deep links for OAuth callbacks 3. Store and use refresh tokens for long-lived sessions  ### For Backend Services 1. Create API keys via `/api-keys` endpoint 2. Use API keys for direct authentication 3. Generate short-lived tokens when needed  ## Error Handling  All endpoints return structured error responses:  ```json {   \"detail\": \"Error description\",   \"error\": \"error_code\",    \"error_description\": \"Detailed error message\" } ```  ## Rate Limiting  API endpoints are rate limited to prevent abuse: - Authentication endpoints: 10 requests/minute - API key operations: 100 requests/hour   - General endpoints: 1000 requests/hour  ## Support  - Documentation: [API Documentation](https://docs.binoauth.com) - Support: support@binoauth.com - Status: [Status Page](https://status.binoauth.com)

    The version of the OpenAPI document: 1.0.0
    Contact: support@binoauth.com
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
"""  # noqa: E501

import warnings
from pydantic import validate_call, Field, StrictFloat, StrictStr, StrictInt
from typing import Any, Dict, List, Optional, Tuple, Union
from typing_extensions import Annotated

from pydantic import StrictBool, StrictStr
from typing import Any, List, Optional
from binoauth.tenant.models.login_response import LoginResponse
from binoauth.tenant.models.provider_response import ProviderResponse
from binoauth.tenant.models.provider_type import ProviderType

from binoauth.tenant.api_client import ApiClient, RequestSerialized
from binoauth.tenant.api_response import ApiResponse
from binoauth.tenant.rest import RESTResponseType


class ExternalAuthApi:
    """NOTE: This class is auto generated by OpenAPI Generator
    Ref: https://openapi-generator.tech

    Do not edit the class manually.
    """

    def __init__(self, api_client=None) -> None:
        if api_client is None:
            api_client = ApiClient.get_default()
        self.api_client = api_client


    @validate_call
    def get_active_providers_api_v1_auth_external_active_providers_get(
        self,
        return_to: StrictStr,
        redirect_uri: Optional[StrictStr] = None,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
            Tuple[
                Annotated[StrictFloat, Field(gt=0)],
                Annotated[StrictFloat, Field(gt=0)]
            ]
        ] = None,
        _request_auth: Optional[Dict[StrictStr, Any]] = None,
        _content_type: Optional[StrictStr] = None,
        _headers: Optional[Dict[StrictStr, Any]] = None,
        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
    ) -> List[ProviderResponse]:
        """Get Active Social Login Providers

        Get list of configured and active social login providers.          This endpoint returns all social login providers that are currently     enabled and configured for the tenant, along with their authorization URLs.          **Use Case:**     Use this endpoint to dynamically display available social login options     in your application's login interface.          **Parameters:**     - `redirect_uri`: The path to redirect to after authentication (relative to tenant domain)     - `return_to`: The final destination URL after successful authentication          **Response:**     Returns an array of provider objects, each containing:     - Provider name and display information     - Authorization URL for initiating OAuth flow     - Supported scopes and capabilities          **Example Usage:**     ```bash     curl \"/api/v1/auth/external/active-providers?redirect_uri=auth/callback&return_to=/dashboard\"     ```

        :param return_to: (required)
        :type return_to: str
        :param redirect_uri:
        :type redirect_uri: str
        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
                                 (connection, read) timeouts.
        :type _request_timeout: int, tuple(int, int), optional
        :param _request_auth: set to override the auth_settings for an a single
                              request; this effectively ignores the
                              authentication in the spec for a single request.
        :type _request_auth: dict, optional
        :param _content_type: force content-type for the request.
        :type _content_type: str, Optional
        :param _headers: set to override the headers for a single
                         request; this effectively ignores the headers
                         in the spec for a single request.
        :type _headers: dict, optional
        :param _host_index: set to override the host_index for a single
                            request; this effectively ignores the host_index
                            in the spec for a single request.
        :type _host_index: int, optional
        :return: Returns the result object.
        """ # noqa: E501

        _param = self._get_active_providers_api_v1_auth_external_active_providers_get_serialize(
            return_to=return_to,
            redirect_uri=redirect_uri,
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
            _host_index=_host_index
        )

        _response_types_map: Dict[str, Optional[str]] = {
            '200': "List[ProviderResponse]",
            '400': None,
            '422': "HTTPValidationError",
        }
        response_data = self.api_client.call_api(
            *_param,
            _request_timeout=_request_timeout
        )
        response_data.read()
        return self.api_client.response_deserialize(
            response_data=response_data,
            response_types_map=_response_types_map,
        ).data


    @validate_call
    def get_active_providers_api_v1_auth_external_active_providers_get_with_http_info(
        self,
        return_to: StrictStr,
        redirect_uri: Optional[StrictStr] = None,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
            Tuple[
                Annotated[StrictFloat, Field(gt=0)],
                Annotated[StrictFloat, Field(gt=0)]
            ]
        ] = None,
        _request_auth: Optional[Dict[StrictStr, Any]] = None,
        _content_type: Optional[StrictStr] = None,
        _headers: Optional[Dict[StrictStr, Any]] = None,
        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
    ) -> ApiResponse[List[ProviderResponse]]:
        """Get Active Social Login Providers

        Get list of configured and active social login providers.          This endpoint returns all social login providers that are currently     enabled and configured for the tenant, along with their authorization URLs.          **Use Case:**     Use this endpoint to dynamically display available social login options     in your application's login interface.          **Parameters:**     - `redirect_uri`: The path to redirect to after authentication (relative to tenant domain)     - `return_to`: The final destination URL after successful authentication          **Response:**     Returns an array of provider objects, each containing:     - Provider name and display information     - Authorization URL for initiating OAuth flow     - Supported scopes and capabilities          **Example Usage:**     ```bash     curl \"/api/v1/auth/external/active-providers?redirect_uri=auth/callback&return_to=/dashboard\"     ```

        :param return_to: (required)
        :type return_to: str
        :param redirect_uri:
        :type redirect_uri: str
        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
                                 (connection, read) timeouts.
        :type _request_timeout: int, tuple(int, int), optional
        :param _request_auth: set to override the auth_settings for an a single
                              request; this effectively ignores the
                              authentication in the spec for a single request.
        :type _request_auth: dict, optional
        :param _content_type: force content-type for the request.
        :type _content_type: str, Optional
        :param _headers: set to override the headers for a single
                         request; this effectively ignores the headers
                         in the spec for a single request.
        :type _headers: dict, optional
        :param _host_index: set to override the host_index for a single
                            request; this effectively ignores the host_index
                            in the spec for a single request.
        :type _host_index: int, optional
        :return: Returns the result object.
        """ # noqa: E501

        _param = self._get_active_providers_api_v1_auth_external_active_providers_get_serialize(
            return_to=return_to,
            redirect_uri=redirect_uri,
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
            _host_index=_host_index
        )

        _response_types_map: Dict[str, Optional[str]] = {
            '200': "List[ProviderResponse]",
            '400': None,
            '422': "HTTPValidationError",
        }
        response_data = self.api_client.call_api(
            *_param,
            _request_timeout=_request_timeout
        )
        response_data.read()
        return self.api_client.response_deserialize(
            response_data=response_data,
            response_types_map=_response_types_map,
        )


    @validate_call
    def get_active_providers_api_v1_auth_external_active_providers_get_without_preload_content(
        self,
        return_to: StrictStr,
        redirect_uri: Optional[StrictStr] = None,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
            Tuple[
                Annotated[StrictFloat, Field(gt=0)],
                Annotated[StrictFloat, Field(gt=0)]
            ]
        ] = None,
        _request_auth: Optional[Dict[StrictStr, Any]] = None,
        _content_type: Optional[StrictStr] = None,
        _headers: Optional[Dict[StrictStr, Any]] = None,
        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
    ) -> RESTResponseType:
        """Get Active Social Login Providers

        Get list of configured and active social login providers.          This endpoint returns all social login providers that are currently     enabled and configured for the tenant, along with their authorization URLs.          **Use Case:**     Use this endpoint to dynamically display available social login options     in your application's login interface.          **Parameters:**     - `redirect_uri`: The path to redirect to after authentication (relative to tenant domain)     - `return_to`: The final destination URL after successful authentication          **Response:**     Returns an array of provider objects, each containing:     - Provider name and display information     - Authorization URL for initiating OAuth flow     - Supported scopes and capabilities          **Example Usage:**     ```bash     curl \"/api/v1/auth/external/active-providers?redirect_uri=auth/callback&return_to=/dashboard\"     ```

        :param return_to: (required)
        :type return_to: str
        :param redirect_uri:
        :type redirect_uri: str
        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
                                 (connection, read) timeouts.
        :type _request_timeout: int, tuple(int, int), optional
        :param _request_auth: set to override the auth_settings for an a single
                              request; this effectively ignores the
                              authentication in the spec for a single request.
        :type _request_auth: dict, optional
        :param _content_type: force content-type for the request.
        :type _content_type: str, Optional
        :param _headers: set to override the headers for a single
                         request; this effectively ignores the headers
                         in the spec for a single request.
        :type _headers: dict, optional
        :param _host_index: set to override the host_index for a single
                            request; this effectively ignores the host_index
                            in the spec for a single request.
        :type _host_index: int, optional
        :return: Returns the result object.
        """ # noqa: E501

        _param = self._get_active_providers_api_v1_auth_external_active_providers_get_serialize(
            return_to=return_to,
            redirect_uri=redirect_uri,
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
            _host_index=_host_index
        )

        _response_types_map: Dict[str, Optional[str]] = {
            '200': "List[ProviderResponse]",
            '400': None,
            '422': "HTTPValidationError",
        }
        response_data = self.api_client.call_api(
            *_param,
            _request_timeout=_request_timeout
        )
        return response_data.response


    def _get_active_providers_api_v1_auth_external_active_providers_get_serialize(
        self,
        return_to,
        redirect_uri,
        _request_auth,
        _content_type,
        _headers,
        _host_index,
    ) -> RequestSerialized:

        _host = None

        _collection_formats: Dict[str, str] = {
        }

        _path_params: Dict[str, str] = {}
        _query_params: List[Tuple[str, str]] = []
        _header_params: Dict[str, Optional[str]] = _headers or {}
        _form_params: List[Tuple[str, str]] = []
        _files: Dict[
            str, Union[str, bytes, List[str], List[bytes], List[Tuple[str, bytes]]]
        ] = {}
        _body_params: Optional[bytes] = None

        # process the path parameters
        # process the query parameters
        if return_to is not None:

            _query_params.append(('return_to', return_to))

        if redirect_uri is not None:

            _query_params.append(('redirect_uri', redirect_uri))

        # process the header parameters
        # process the form parameters
        # process the body parameter


        # set the HTTP header `Accept`
        if 'Accept' not in _header_params:
            _header_params['Accept'] = self.api_client.select_header_accept(
                [
                    'application/json'
                ]
            )


        # authentication setting
        _auth_settings: List[str] = [
        ]

        return self.api_client.param_serialize(
            method='GET',
            resource_path='/api/v1/auth/external/active-providers',
            path_params=_path_params,
            query_params=_query_params,
            header_params=_header_params,
            body=_body_params,
            post_params=_form_params,
            files=_files,
            auth_settings=_auth_settings,
            collection_formats=_collection_formats,
            _host=_host,
            _request_auth=_request_auth
        )




    @validate_call
    def get_providers_api_v1_auth_external_providers_get(
        self,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
            Tuple[
                Annotated[StrictFloat, Field(gt=0)],
                Annotated[StrictFloat, Field(gt=0)]
            ]
        ] = None,
        _request_auth: Optional[Dict[StrictStr, Any]] = None,
        _content_type: Optional[StrictStr] = None,
        _headers: Optional[Dict[StrictStr, Any]] = None,
        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
    ) -> object:
        """Get All Available Providers

        Get complete list of all supported social login providers.          This endpoint returns all social login providers supported by the system,     regardless of whether they are configured or enabled for the current binoauth.tenant.          **Use Case:**     Use this endpoint to:     - Display all available provider options in admin configuration     - Show providers that can be enabled for the tenant     - Get provider metadata and configuration requirements          **Response:**     Returns an array of all supported providers with:     - Provider identifiers and names     - Configuration requirements     - Capability information     - Setup instructions          **Example Usage:**     ```bash     curl \"/api/v1/auth/external/providers\"     ```          **Difference from /active-providers:**     - `/providers`: All supported providers (for configuration)     - `/active-providers`: Only enabled providers (for login UI)

        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
                                 (connection, read) timeouts.
        :type _request_timeout: int, tuple(int, int), optional
        :param _request_auth: set to override the auth_settings for an a single
                              request; this effectively ignores the
                              authentication in the spec for a single request.
        :type _request_auth: dict, optional
        :param _content_type: force content-type for the request.
        :type _content_type: str, Optional
        :param _headers: set to override the headers for a single
                         request; this effectively ignores the headers
                         in the spec for a single request.
        :type _headers: dict, optional
        :param _host_index: set to override the host_index for a single
                            request; this effectively ignores the host_index
                            in the spec for a single request.
        :type _host_index: int, optional
        :return: Returns the result object.
        """ # noqa: E501

        _param = self._get_providers_api_v1_auth_external_providers_get_serialize(
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
            _host_index=_host_index
        )

        _response_types_map: Dict[str, Optional[str]] = {
            '200': "object",
        }
        response_data = self.api_client.call_api(
            *_param,
            _request_timeout=_request_timeout
        )
        response_data.read()
        return self.api_client.response_deserialize(
            response_data=response_data,
            response_types_map=_response_types_map,
        ).data


    @validate_call
    def get_providers_api_v1_auth_external_providers_get_with_http_info(
        self,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
            Tuple[
                Annotated[StrictFloat, Field(gt=0)],
                Annotated[StrictFloat, Field(gt=0)]
            ]
        ] = None,
        _request_auth: Optional[Dict[StrictStr, Any]] = None,
        _content_type: Optional[StrictStr] = None,
        _headers: Optional[Dict[StrictStr, Any]] = None,
        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
    ) -> ApiResponse[object]:
        """Get All Available Providers

        Get complete list of all supported social login providers.          This endpoint returns all social login providers supported by the system,     regardless of whether they are configured or enabled for the current binoauth.tenant.          **Use Case:**     Use this endpoint to:     - Display all available provider options in admin configuration     - Show providers that can be enabled for the tenant     - Get provider metadata and configuration requirements          **Response:**     Returns an array of all supported providers with:     - Provider identifiers and names     - Configuration requirements     - Capability information     - Setup instructions          **Example Usage:**     ```bash     curl \"/api/v1/auth/external/providers\"     ```          **Difference from /active-providers:**     - `/providers`: All supported providers (for configuration)     - `/active-providers`: Only enabled providers (for login UI)

        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
                                 (connection, read) timeouts.
        :type _request_timeout: int, tuple(int, int), optional
        :param _request_auth: set to override the auth_settings for an a single
                              request; this effectively ignores the
                              authentication in the spec for a single request.
        :type _request_auth: dict, optional
        :param _content_type: force content-type for the request.
        :type _content_type: str, Optional
        :param _headers: set to override the headers for a single
                         request; this effectively ignores the headers
                         in the spec for a single request.
        :type _headers: dict, optional
        :param _host_index: set to override the host_index for a single
                            request; this effectively ignores the host_index
                            in the spec for a single request.
        :type _host_index: int, optional
        :return: Returns the result object.
        """ # noqa: E501

        _param = self._get_providers_api_v1_auth_external_providers_get_serialize(
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
            _host_index=_host_index
        )

        _response_types_map: Dict[str, Optional[str]] = {
            '200': "object",
        }
        response_data = self.api_client.call_api(
            *_param,
            _request_timeout=_request_timeout
        )
        response_data.read()
        return self.api_client.response_deserialize(
            response_data=response_data,
            response_types_map=_response_types_map,
        )


    @validate_call
    def get_providers_api_v1_auth_external_providers_get_without_preload_content(
        self,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
            Tuple[
                Annotated[StrictFloat, Field(gt=0)],
                Annotated[StrictFloat, Field(gt=0)]
            ]
        ] = None,
        _request_auth: Optional[Dict[StrictStr, Any]] = None,
        _content_type: Optional[StrictStr] = None,
        _headers: Optional[Dict[StrictStr, Any]] = None,
        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
    ) -> RESTResponseType:
        """Get All Available Providers

        Get complete list of all supported social login providers.          This endpoint returns all social login providers supported by the system,     regardless of whether they are configured or enabled for the current binoauth.tenant.          **Use Case:**     Use this endpoint to:     - Display all available provider options in admin configuration     - Show providers that can be enabled for the tenant     - Get provider metadata and configuration requirements          **Response:**     Returns an array of all supported providers with:     - Provider identifiers and names     - Configuration requirements     - Capability information     - Setup instructions          **Example Usage:**     ```bash     curl \"/api/v1/auth/external/providers\"     ```          **Difference from /active-providers:**     - `/providers`: All supported providers (for configuration)     - `/active-providers`: Only enabled providers (for login UI)

        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
                                 (connection, read) timeouts.
        :type _request_timeout: int, tuple(int, int), optional
        :param _request_auth: set to override the auth_settings for an a single
                              request; this effectively ignores the
                              authentication in the spec for a single request.
        :type _request_auth: dict, optional
        :param _content_type: force content-type for the request.
        :type _content_type: str, Optional
        :param _headers: set to override the headers for a single
                         request; this effectively ignores the headers
                         in the spec for a single request.
        :type _headers: dict, optional
        :param _host_index: set to override the host_index for a single
                            request; this effectively ignores the host_index
                            in the spec for a single request.
        :type _host_index: int, optional
        :return: Returns the result object.
        """ # noqa: E501

        _param = self._get_providers_api_v1_auth_external_providers_get_serialize(
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
            _host_index=_host_index
        )

        _response_types_map: Dict[str, Optional[str]] = {
            '200': "object",
        }
        response_data = self.api_client.call_api(
            *_param,
            _request_timeout=_request_timeout
        )
        return response_data.response


    def _get_providers_api_v1_auth_external_providers_get_serialize(
        self,
        _request_auth,
        _content_type,
        _headers,
        _host_index,
    ) -> RequestSerialized:

        _host = None

        _collection_formats: Dict[str, str] = {
        }

        _path_params: Dict[str, str] = {}
        _query_params: List[Tuple[str, str]] = []
        _header_params: Dict[str, Optional[str]] = _headers or {}
        _form_params: List[Tuple[str, str]] = []
        _files: Dict[
            str, Union[str, bytes, List[str], List[bytes], List[Tuple[str, bytes]]]
        ] = {}
        _body_params: Optional[bytes] = None

        # process the path parameters
        # process the query parameters
        # process the header parameters
        # process the form parameters
        # process the body parameter


        # set the HTTP header `Accept`
        if 'Accept' not in _header_params:
            _header_params['Accept'] = self.api_client.select_header_accept(
                [
                    'application/json'
                ]
            )


        # authentication setting
        _auth_settings: List[str] = [
        ]

        return self.api_client.param_serialize(
            method='GET',
            resource_path='/api/v1/auth/external/providers',
            path_params=_path_params,
            query_params=_query_params,
            header_params=_header_params,
            body=_body_params,
            post_params=_form_params,
            files=_files,
            auth_settings=_auth_settings,
            collection_formats=_collection_formats,
            _host=_host,
            _request_auth=_request_auth
        )




    @validate_call
    def social_callback_api_v1_auth_external_callback_provider_get(
        self,
        provider: ProviderType,
        code: StrictStr,
        state: StrictStr,
        link: Optional[StrictBool] = None,
        error: Optional[StrictStr] = None,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
            Tuple[
                Annotated[StrictFloat, Field(gt=0)],
                Annotated[StrictFloat, Field(gt=0)]
            ]
        ] = None,
        _request_auth: Optional[Dict[StrictStr, Any]] = None,
        _content_type: Optional[StrictStr] = None,
        _headers: Optional[Dict[StrictStr, Any]] = None,
        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
    ) -> LoginResponse:
        """Social Login Callback

        Handle OAuth callback from external social login providers.          This endpoint processes the OAuth callback after a user has authenticated     with an external provider (Google, Facebook, GitHub, etc.).          **Supported Providers:**     - Google     - Facebook       - GitHub     - Microsoft     - Apple     - LinkedIn          **Flow:**     1. User clicks social login button     2. Redirected to provider's OAuth page     3. User grants permissions     4. Provider redirects back to this callback     5. User is authenticated or account is linked          **Parameters:**     - `provider`: The social login provider name     - `code`: Authorization code from the provider     - `state`: Security state parameter to prevent CSRF     - `link`: Optional flag to link account instead of login     - `error`: Error code if authentication failed          **Account Linking:**     If `link=true`, this will link the social account to an existing user     instead of logging them in directly.

        :param provider: (required)
        :type provider: ProviderType
        :param code: (required)
        :type code: str
        :param state: (required)
        :type state: str
        :param link:
        :type link: bool
        :param error:
        :type error: str
        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
                                 (connection, read) timeouts.
        :type _request_timeout: int, tuple(int, int), optional
        :param _request_auth: set to override the auth_settings for an a single
                              request; this effectively ignores the
                              authentication in the spec for a single request.
        :type _request_auth: dict, optional
        :param _content_type: force content-type for the request.
        :type _content_type: str, Optional
        :param _headers: set to override the headers for a single
                         request; this effectively ignores the headers
                         in the spec for a single request.
        :type _headers: dict, optional
        :param _host_index: set to override the host_index for a single
                            request; this effectively ignores the host_index
                            in the spec for a single request.
        :type _host_index: int, optional
        :return: Returns the result object.
        """ # noqa: E501

        _param = self._social_callback_api_v1_auth_external_callback_provider_get_serialize(
            provider=provider,
            code=code,
            state=state,
            link=link,
            error=error,
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
            _host_index=_host_index
        )

        _response_types_map: Dict[str, Optional[str]] = {
            '200': "LoginResponse",
            '302': None,
            '400': None,
            '422': "HTTPValidationError",
        }
        response_data = self.api_client.call_api(
            *_param,
            _request_timeout=_request_timeout
        )
        response_data.read()
        return self.api_client.response_deserialize(
            response_data=response_data,
            response_types_map=_response_types_map,
        ).data


    @validate_call
    def social_callback_api_v1_auth_external_callback_provider_get_with_http_info(
        self,
        provider: ProviderType,
        code: StrictStr,
        state: StrictStr,
        link: Optional[StrictBool] = None,
        error: Optional[StrictStr] = None,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
            Tuple[
                Annotated[StrictFloat, Field(gt=0)],
                Annotated[StrictFloat, Field(gt=0)]
            ]
        ] = None,
        _request_auth: Optional[Dict[StrictStr, Any]] = None,
        _content_type: Optional[StrictStr] = None,
        _headers: Optional[Dict[StrictStr, Any]] = None,
        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
    ) -> ApiResponse[LoginResponse]:
        """Social Login Callback

        Handle OAuth callback from external social login providers.          This endpoint processes the OAuth callback after a user has authenticated     with an external provider (Google, Facebook, GitHub, etc.).          **Supported Providers:**     - Google     - Facebook       - GitHub     - Microsoft     - Apple     - LinkedIn          **Flow:**     1. User clicks social login button     2. Redirected to provider's OAuth page     3. User grants permissions     4. Provider redirects back to this callback     5. User is authenticated or account is linked          **Parameters:**     - `provider`: The social login provider name     - `code`: Authorization code from the provider     - `state`: Security state parameter to prevent CSRF     - `link`: Optional flag to link account instead of login     - `error`: Error code if authentication failed          **Account Linking:**     If `link=true`, this will link the social account to an existing user     instead of logging them in directly.

        :param provider: (required)
        :type provider: ProviderType
        :param code: (required)
        :type code: str
        :param state: (required)
        :type state: str
        :param link:
        :type link: bool
        :param error:
        :type error: str
        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
                                 (connection, read) timeouts.
        :type _request_timeout: int, tuple(int, int), optional
        :param _request_auth: set to override the auth_settings for an a single
                              request; this effectively ignores the
                              authentication in the spec for a single request.
        :type _request_auth: dict, optional
        :param _content_type: force content-type for the request.
        :type _content_type: str, Optional
        :param _headers: set to override the headers for a single
                         request; this effectively ignores the headers
                         in the spec for a single request.
        :type _headers: dict, optional
        :param _host_index: set to override the host_index for a single
                            request; this effectively ignores the host_index
                            in the spec for a single request.
        :type _host_index: int, optional
        :return: Returns the result object.
        """ # noqa: E501

        _param = self._social_callback_api_v1_auth_external_callback_provider_get_serialize(
            provider=provider,
            code=code,
            state=state,
            link=link,
            error=error,
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
            _host_index=_host_index
        )

        _response_types_map: Dict[str, Optional[str]] = {
            '200': "LoginResponse",
            '302': None,
            '400': None,
            '422': "HTTPValidationError",
        }
        response_data = self.api_client.call_api(
            *_param,
            _request_timeout=_request_timeout
        )
        response_data.read()
        return self.api_client.response_deserialize(
            response_data=response_data,
            response_types_map=_response_types_map,
        )


    @validate_call
    def social_callback_api_v1_auth_external_callback_provider_get_without_preload_content(
        self,
        provider: ProviderType,
        code: StrictStr,
        state: StrictStr,
        link: Optional[StrictBool] = None,
        error: Optional[StrictStr] = None,
        _request_timeout: Union[
            None,
            Annotated[StrictFloat, Field(gt=0)],
            Tuple[
                Annotated[StrictFloat, Field(gt=0)],
                Annotated[StrictFloat, Field(gt=0)]
            ]
        ] = None,
        _request_auth: Optional[Dict[StrictStr, Any]] = None,
        _content_type: Optional[StrictStr] = None,
        _headers: Optional[Dict[StrictStr, Any]] = None,
        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
    ) -> RESTResponseType:
        """Social Login Callback

        Handle OAuth callback from external social login providers.          This endpoint processes the OAuth callback after a user has authenticated     with an external provider (Google, Facebook, GitHub, etc.).          **Supported Providers:**     - Google     - Facebook       - GitHub     - Microsoft     - Apple     - LinkedIn          **Flow:**     1. User clicks social login button     2. Redirected to provider's OAuth page     3. User grants permissions     4. Provider redirects back to this callback     5. User is authenticated or account is linked          **Parameters:**     - `provider`: The social login provider name     - `code`: Authorization code from the provider     - `state`: Security state parameter to prevent CSRF     - `link`: Optional flag to link account instead of login     - `error`: Error code if authentication failed          **Account Linking:**     If `link=true`, this will link the social account to an existing user     instead of logging them in directly.

        :param provider: (required)
        :type provider: ProviderType
        :param code: (required)
        :type code: str
        :param state: (required)
        :type state: str
        :param link:
        :type link: bool
        :param error:
        :type error: str
        :param _request_timeout: timeout setting for this request. If one
                                 number provided, it will be total request
                                 timeout. It can also be a pair (tuple) of
                                 (connection, read) timeouts.
        :type _request_timeout: int, tuple(int, int), optional
        :param _request_auth: set to override the auth_settings for an a single
                              request; this effectively ignores the
                              authentication in the spec for a single request.
        :type _request_auth: dict, optional
        :param _content_type: force content-type for the request.
        :type _content_type: str, Optional
        :param _headers: set to override the headers for a single
                         request; this effectively ignores the headers
                         in the spec for a single request.
        :type _headers: dict, optional
        :param _host_index: set to override the host_index for a single
                            request; this effectively ignores the host_index
                            in the spec for a single request.
        :type _host_index: int, optional
        :return: Returns the result object.
        """ # noqa: E501

        _param = self._social_callback_api_v1_auth_external_callback_provider_get_serialize(
            provider=provider,
            code=code,
            state=state,
            link=link,
            error=error,
            _request_auth=_request_auth,
            _content_type=_content_type,
            _headers=_headers,
            _host_index=_host_index
        )

        _response_types_map: Dict[str, Optional[str]] = {
            '200': "LoginResponse",
            '302': None,
            '400': None,
            '422': "HTTPValidationError",
        }
        response_data = self.api_client.call_api(
            *_param,
            _request_timeout=_request_timeout
        )
        return response_data.response


    def _social_callback_api_v1_auth_external_callback_provider_get_serialize(
        self,
        provider,
        code,
        state,
        link,
        error,
        _request_auth,
        _content_type,
        _headers,
        _host_index,
    ) -> RequestSerialized:

        _host = None

        _collection_formats: Dict[str, str] = {
        }

        _path_params: Dict[str, str] = {}
        _query_params: List[Tuple[str, str]] = []
        _header_params: Dict[str, Optional[str]] = _headers or {}
        _form_params: List[Tuple[str, str]] = []
        _files: Dict[
            str, Union[str, bytes, List[str], List[bytes], List[Tuple[str, bytes]]]
        ] = {}
        _body_params: Optional[bytes] = None

        # process the path parameters
        if provider is not None:
            _path_params['provider'] = provider.value
        # process the query parameters
        if code is not None:

            _query_params.append(('code', code))

        if state is not None:

            _query_params.append(('state', state))

        if link is not None:

            _query_params.append(('link', link))

        if error is not None:

            _query_params.append(('error', error))

        # process the header parameters
        # process the form parameters
        # process the body parameter


        # set the HTTP header `Accept`
        if 'Accept' not in _header_params:
            _header_params['Accept'] = self.api_client.select_header_accept(
                [
                    'application/json'
                ]
            )


        # authentication setting
        _auth_settings: List[str] = [
        ]

        return self.api_client.param_serialize(
            method='GET',
            resource_path='/api/v1/auth/external/callback/{provider}',
            path_params=_path_params,
            query_params=_query_params,
            header_params=_header_params,
            body=_body_params,
            post_params=_form_params,
            files=_files,
            auth_settings=_auth_settings,
            collection_formats=_collection_formats,
            _host=_host,
            _request_auth=_request_auth
        )
