Skip to content

Cloudflare Base Settings

See main reference

Bases: Enum

Source code in start_cloudflare/main.py
Python
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
class CFSecurityKey(Enum):
    EMAIL = "X-Auth-Email"
    API = "X-Auth-Key"
    USER_SERVICE = "X-Auth-User-Service-Key"
    BEARER = "Authorization"

    def as_header(self, value: str) -> dict[str, str]:
        """Helper to create request headers based on the key.

        Examples:
            >>> CFSecurityKey.BEARER.as_header('Adria-Ripoli')
            {'Authorization': 'Bearer Adria-Ripoli'}

        Args:
            value (str): Value to include in the header

        Returns:
            dict[str, str]: A dictionary that can be combined later to form part of the request URL header
        """  # noqa: E501
        if self.name == "BEARER":
            return {"Authorization": f"Bearer {value}"}
        return {self.value: value}

Functions

as_header(value)

Helper to create request headers based on the key.

Examples:

Python Console Session
>>> CFSecurityKey.BEARER.as_header('Adria-Ripoli')
{'Authorization': 'Bearer Adria-Ripoli'}

Parameters:

Name Type Description Default
value str

Value to include in the header

 required

Returns:

Type Description
dict[str, str]

dict[str, str]: A dictionary that can be combined later to form part of the request URL header
Source code in start_cloudflare/main.py
Python
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
def as_header(self, value: str) -> dict[str, str]:
    """Helper to create request headers based on the key.

    Examples:
        >>> CFSecurityKey.BEARER.as_header('Adria-Ripoli')
        {'Authorization': 'Bearer Adria-Ripoli'}

    Args:
        value (str): Value to include in the header

    Returns:
        dict[str, str]: A dictionary that can be combined later to form part of the request URL header
    """  # noqa: E501
    if self.name == "BEARER":
        return {"Authorization": f"Bearer {value}"}
    return {self.value: value}

Bases: BaseSettings

This is a base class. Bare minimum: CF_ACCT_ID needs to be set.

Add secrets to .env file:

Field in .env Cloudflare API Credential Where credential found
CF_ACCT_ID, defaults to 'ACCT' Signup Account ID Assigned on signup https://dash.cloudflare.com/<ACCT_ID>/
Optional: CF_ACCT_EMAIL Account Email What you signed up with
Optional: CF_GLOBAL_API_KEY See docs https://dash.cloudflare.com/profile/api-tokens
Optional: CF_ORIGIN_CA_KEY See docs https://dash.cloudflare.com/profile/api-tokens

Examples:

Python Console Session
>>> import os
>>> cf = CF()
>>> cf
CF(version=4, email=None)
>>> cf.account_id
'ACCT'
>>> from start_cloudflare import CF
>>> os.environ['CF_ACCT_ID'] = "<ACCT_ID> from https://dash.cloudflare.com/<ACCT_ID>/"
>>> cf = CF()
>>> cf
CF(version=4, email=None)
>>> cf.account_id
'<ACCT_ID> from https://dash.cloudflare.com/<ACCT_ID>/'
>>> CF_API_URL
'https://api.cloudflare.com'
Source code in start_cloudflare/main.py
Python
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
class CF(BaseSettings):
    """
    This is a base class. Bare minimum: `CF_ACCT_ID` needs to be set.

    Add secrets to .env file:

    Field in .env | Cloudflare API Credential | Where credential found
    :--|:--:|:--
    `CF_ACCT_ID`, defaults to 'ACCT' | Signup Account ID | Assigned on signup `https://dash.cloudflare.com/<ACCT_ID>/`
    Optional: `CF_ACCT_EMAIL` | Account Email | What you signed up with
    Optional: `CF_GLOBAL_API_KEY` | See [docs](https://developers.cloudflare.com/fundamentals/api/get-started/keys/) | `https://dash.cloudflare.com/profile/api-tokens`
    Optional: `CF_ORIGIN_CA_KEY` | See [docs](https://developers.cloudflare.com/fundamentals/api/get-started/ca-keys/) | `https://dash.cloudflare.com/profile/api-tokens`

    Examples:
        >>> import os
        >>> cf = CF()
        >>> cf
        CF(version=4, email=None)
        >>> cf.account_id
        'ACCT'
        >>> from start_cloudflare import CF
        >>> os.environ['CF_ACCT_ID'] = "<ACCT_ID> from https://dash.cloudflare.com/<ACCT_ID>/"
        >>> cf = CF()
        >>> cf
        CF(version=4, email=None)
        >>> cf.account_id
        '<ACCT_ID> from https://dash.cloudflare.com/<ACCT_ID>/'
        >>> CF_API_URL
        'https://api.cloudflare.com'

    """  # noqa: E501

    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")  # type: ignore # noqa: E501
    account_id: str | None = Field(
        default="ACCT",
        repr=False,
        validation_alias="CF_ACCT_ID",
    )
    version: int = Field(
        default=4,
        repr=True,
        validation_alias="CF_API_VERSION",
    )
    email: EmailStr | None = Field(
        default=None,
        repr=True,
        validation_alias="CF_ACCT_EMAIL",
    )
    global_api_key: str | None = Field(
        default=None,
        repr=False,
        validation_alias="CF_GLOBAL_API_KEY",
    )
    origin_ca_key: str | None = Field(
        default=None,
        repr=False,
        validation_alias="CF_ORIGIN_CA_KEY",
    )

    @property
    def head_email(self) -> dict[str, str]:
        """Get partial header involving 'X-Auth-Email' key, provided the
        'CF_ACCT_EMAIL' is set.

        Examples:
            >>> import os
            >>> os.environ['CF_ACCT_EMAIL'] = 'brightness@long.ago'
            >>> cf = CF()
            >>> cf.head_email
            {'X-Auth-Email': 'brightness@long.ago'}

        Returns:
            dict[str, str]: Partial header
        """
        if self.email:
            return CFSecurityKey.EMAIL.as_header(self.email)
        raise Exception("Need to set email.")

    @property
    def head_auth_key(self) -> dict:
        """Get partial header involving the 'X-Auth-Email' key, provided the
        'X-Auth-Key' is set.

        Examples:
            >>> import os
            >>> os.environ['CF_GLOBAL_API_KEY'] = 'mytoken'
            >>> cf = CF()
            >>> cf.head_auth_key
            {'X-Auth-Key': 'mytoken'}

        Returns:
            dict[str, str]: Partial header
        """
        if self.global_api_key:
            return CFSecurityKey.API.as_header(self.global_api_key)
        raise Exception("Need to set global api key.")

    @classmethod
    def set_bearer_auth(cls, token: str) -> dict:
        """Get partial header involving the 'Authorization' key, provided the
        'X-Auth-Key' is set.

        Examples:
            >>> CF.set_bearer_auth('Guidanio-Cerra')
            {'Authorization': 'Bearer Guidanio-Cerra'}

        Returns:
            dict[str, str]: Partial header
        """
        return CFSecurityKey.BEARER.as_header(token)

    @property
    def base(self) -> str:
        """Create the base url for the Cloudflare API with version 4 as default

        Examples:
            >>> cf = CF()
            >>> cf.base
            'https://api.cloudflare.com/client/v4'
            >>> import os
            >>> os.environ['CF_API_VERSION'] = '5'
            >>> cf = CF()
            >>> cf.base
            'https://api.cloudflare.com/client/v5'

        Returns:
            str: Partial URL
        """

        return f"{CF_API_URL}/client/v{self.version}"

    def add_account_endpoint(self, path: str) -> str:
        """Set url endpoint following the API reference /accounts/{path}

        Examples:
            >>> cf = CF()
            >>> cf.add_account_endpoint("/test/hello/world")
            'https://api.cloudflare.com/client/v4/accounts/test/hello/world'

        Args:
            path (str): Needs to start with "/"

        Returns:
            str: URL involving "accounts" to fetch endpoint terminating in `path`
        """

        if not path.startswith("/"):
            raise Exception("Path string should start with /")
        return f"{self.base}/accounts{path}"

Attributes

base: str property

Create the base url for the Cloudflare API with version 4 as default

Examples:

Python Console Session
>>> cf = CF()
>>> cf.base
'https://api.cloudflare.com/client/v4'
>>> import os
>>> os.environ['CF_API_VERSION'] = '5'
>>> cf = CF()
>>> cf.base
'https://api.cloudflare.com/client/v5'

Returns:

Name Type Description
str str

Partial URL

head_auth_key: dict property

Get partial header involving the 'X-Auth-Email' key, provided the 'X-Auth-Key' is set.

Examples:

Python Console Session
>>> import os
>>> os.environ['CF_GLOBAL_API_KEY'] = 'mytoken'
>>> cf = CF()
>>> cf.head_auth_key
{'X-Auth-Key': 'mytoken'}

Returns:

Type Description
dict

dict[str, str]: Partial header

head_email: dict[str, str] property

Get partial header involving 'X-Auth-Email' key, provided the 'CF_ACCT_EMAIL' is set.

Examples:

Python Console Session
>>> import os
>>> os.environ['CF_ACCT_EMAIL'] = 'brightness@long.ago'
>>> cf = CF()
>>> cf.head_email
{'X-Auth-Email': 'brightness@long.ago'}

Returns:

Type Description
dict[str, str]

dict[str, str]: Partial header

Functions

add_account_endpoint(path)

Set url endpoint following the API reference /accounts/{path}

Examples:

Python Console Session
>>> cf = CF()
>>> cf.add_account_endpoint("/test/hello/world")
'https://api.cloudflare.com/client/v4/accounts/test/hello/world'

Parameters:

Name Type Description Default
path str

Needs to start with "/"

 required

Returns:

Name Type Description
str str

URL involving "accounts" to fetch endpoint terminating in path
Source code in start_cloudflare/main.py
Python
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
def add_account_endpoint(self, path: str) -> str:
    """Set url endpoint following the API reference /accounts/{path}

    Examples:
        >>> cf = CF()
        >>> cf.add_account_endpoint("/test/hello/world")
        'https://api.cloudflare.com/client/v4/accounts/test/hello/world'

    Args:
        path (str): Needs to start with "/"

    Returns:
        str: URL involving "accounts" to fetch endpoint terminating in `path`
    """

    if not path.startswith("/"):
        raise Exception("Path string should start with /")
    return f"{self.base}/accounts{path}"

set_bearer_auth(token) classmethod

Get partial header involving the 'Authorization' key, provided the 'X-Auth-Key' is set.

Examples:

Python Console Session
>>> CF.set_bearer_auth('Guidanio-Cerra')
{'Authorization': 'Bearer Guidanio-Cerra'}

Returns:

Type Description
dict

dict[str, str]: Partial header
Source code in start_cloudflare/main.py
Python
133
134
135
136
137
138
139
140
141
142
143
144
145
@classmethod
def set_bearer_auth(cls, token: str) -> dict:
    """Get partial header involving the 'Authorization' key, provided the
    'X-Auth-Key' is set.

    Examples:
        >>> CF.set_bearer_auth('Guidanio-Cerra')
        {'Authorization': 'Bearer Guidanio-Cerra'}

    Returns:
        dict[str, str]: Partial header
    """
    return CFSecurityKey.BEARER.as_header(token)