0
# Types OAuthlib
1

2
Type stubs for oauthlib - a comprehensive Python library for implementing OAuth 1.0 and OAuth 2.0 authentication protocols. This package provides complete type definitions enabling static type checking for OAuth-enabled applications, authentication servers, and API integrations.
3

4
## Package Information
5

6
- **Package Name**: types-oauthlib
7
- **Language**: Python
8
- **Installation**: `pip install types-oauthlib`
9
- **Requires**: oauthlib library (`pip install oauthlib`)
10

11
## Core Imports
12

13
```python
14
import oauthlib
15
from oauthlib import oauth1, oauth2, openid, common
16

17
# Debug functions
18
from oauthlib import set_debug, get_debug
19
```
20

21
OAuth 1.0 specific imports:
22

23
```python
24
from oauthlib.oauth1 import Client, RequestValidator
25
from oauthlib.oauth1 import AccessTokenEndpoint, AuthorizationEndpoint, RequestTokenEndpoint
26
```
27

28
OAuth 2.0 specific imports:
29

30
```python
31
from oauthlib.oauth2 import WebApplicationClient, BackendApplicationClient
32
from oauthlib.oauth2 import AuthorizationEndpoint, TokenEndpoint, ResourceEndpoint
33
from oauthlib.oauth2 import RequestValidator, BearerToken
34
```
35

36
OpenID Connect specific imports:
37

38
```python
39
from oauthlib.openid import RequestValidator, Server, UserInfoEndpoint
40
```
41

42
## Basic Usage
43

44
### OAuth 2.0 Client Example
45

46
```python
47
from oauthlib.oauth2 import WebApplicationClient
48
from oauthlib.common import generate_token
49
import requests
50

51
# Create OAuth 2.0 client
52
client = WebApplicationClient('your-client-id')
53

54
# Prepare authorization request
55
authorization_url = 'https://auth.example.com/authorize'
56
url, headers, body = client.prepare_authorization_request(
57
    authorization_url,
58
    redirect_url='https://your-app.com/callback',
59
    scope=['read', 'write'],
60
    state=generate_token()
61
)
62

63
# User visits the authorization URL and gets redirected back with code
64
# Exchange authorization code for access token
65
token_url = 'https://auth.example.com/token'
66
url, headers, body = client.prepare_token_request(
67
    token_url,
68
    authorization_response=callback_url,
69
    redirect_url='https://your-app.com/callback'
70
)
71

72
# Make token request
73
token_response = requests.post(url, headers=headers, data=body)
74
client.parse_request_body_response(token_response.text)
75

76
# Use access token to make API requests
77
url, headers, body = client.add_token('https://api.example.com/data')
78
api_response = requests.get(url, headers=headers)
79
```
80

81
### OAuth 2.0 Server Example
82

83
```python
84
from oauthlib.oauth2 import WebApplicationServer, RequestValidator
85

86
class MyRequestValidator(RequestValidator):
87
    def validate_client_id(self, client_id, request, *args, **kwargs):
88
        # Validate the client_id
89
        return client_id in valid_clients
90
    
91
    def authenticate_client(self, request, *args, **kwargs):
92
        # Authenticate the client
93
        return request.client_id in authenticated_clients
94
    
95
    def save_authorization_code(self, client_id, code, request, *args, **kwargs):
96
        # Store authorization code
97
        store_code(client_id, code, request)
98

99
# Create OAuth 2.0 server
100
validator = MyRequestValidator()
101
server = WebApplicationServer(validator)
102

103
# Handle authorization request
104
headers, body, status = server.create_authorization_response(
105
    uri='https://your-server.com/authorize?response_type=code&client_id=client&redirect_uri=callback',
106
    http_method='GET',
107
    credentials={'user_id': 'user123'}
108
)
109
```
110

111
## Architecture
112

113
The oauthlib type stubs are organized into several key modules that mirror the OAuth specification hierarchy:
114

115
- **Common Module**: Shared utilities, request handling, and base types used across all OAuth implementations
116
- **OAuth 1.0 Module**: Complete RFC 5849 implementation with clients, endpoints, signature methods, and validation
117
- **OAuth 2.0 Module**: Complete RFC 6749 implementation with multiple client types, server endpoints, grant types, and token handling
118
- **Device Flow Extension**: RFC 8628 device authorization grant for input-constrained devices
119
- **OpenID Connect Module**: OpenID Connect extension providing identity layer on top of OAuth 2.0
120

121
This modular architecture enables developers to use specific OAuth flows while maintaining type safety and IDE support throughout the authentication process.
122

123
## Capabilities
124

125
### OAuth 1.0 Implementation
126

127
Complete OAuth 1.0 (RFC 5849) client and server implementation with signature methods, request/access token flows, and protected resource access. Supports HMAC-SHA1, RSA-SHA1, and PLAINTEXT signature methods.
128

129
```python { .api }
130
class Client:
131
    def __init__(
132
        self,
133
        client_key: str,
134
        client_secret: str | None = None,
135
        resource_owner_key=None,
136
        resource_owner_secret=None,
137
        callback_uri=None,
138
        signature_method: str = "HMAC-SHA1",
139
        signature_type: str = "AUTH_HEADER",
140
        rsa_key=None,
141
        verifier=None,
142
        realm=None,
143
        encoding: str = "utf-8",
144
        decoding=None,
145
        nonce=None,
146
        timestamp=None,
147
    ): ...
148
    
149
    def sign(
150
        self,
151
        uri: str,
152
        http_method: str = "GET",
153
        body: str | dict[str, str] | list[tuple[str, str]] | None = None,
154
        headers: dict[str, str] | None = None,
155
        realm=None,
156
    ): ...
157
```
158

159
[OAuth 1.0](./oauth1.md)
160

161
### OAuth 2.0 Clients
162

163
Multiple client implementations supporting all OAuth 2.0 grant types including authorization code, implicit, client credentials, and password flows. Includes PKCE support for enhanced security.
164

165
```python { .api }
166
class WebApplicationClient:
167
    def __init__(
168
        self,
169
        client_id: str,
170
        default_token_placement: str = "auth_header",
171
        token_type: str = "Bearer",
172
        access_token: str | None = None,
173
        refresh_token: str | None = None,
174
        **kwargs,
175
    ): ...
176
    
177
    def prepare_authorization_request(
178
        self,
179
        authorization_url: str,
180
        state: str | None = None,
181
        redirect_url: str | None = None,
182
        scope: str | list[str] | None = None,
183
        **kwargs,
184
    ) -> tuple[str, dict[str, str], str]: ...
185
    
186
    def prepare_token_request(
187
        self,
188
        token_url: str,
189
        authorization_response: str | None = None,
190
        redirect_url: str | None = None,
191
        state: str | None = None,
192
        body: str = "",
193
        **kwargs,
194
    ) -> tuple[str, dict[str, str], str]: ...
195
```
196

197
[OAuth 2.0 Clients](./oauth2-clients.md)
198

199
### OAuth 2.0 Servers
200

201
Complete server-side OAuth 2.0 implementation with authorization servers, resource servers, token endpoints, and request validation. Supports all standard grant types and extensions.
202

203
```python { .api }
204
class WebApplicationServer:
205
    def __init__(self, request_validator, token_expires_in=None, token_generator=None, refresh_token_generator=None): ...
206
    
207
    def create_authorization_response(
208
        self,
209
        uri: str,
210
        http_method: str = "GET",
211
        body: str | None = None,
212
        headers: dict[str, str] | None = None,
213
        scopes: list[str] | None = None,
214
        credentials: dict[str, str] | None = None,
215
    ) -> tuple[dict[str, str], str, int]: ...
216
    
217
    def create_token_response(
218
        self,
219
        uri: str,
220
        http_method: str = "POST",
221
        body: str | None = None,
222
        headers: dict[str, str] | None = None,
223
        credentials: dict[str, str] | None = None,
224
        **kwargs,
225
    ) -> tuple[dict[str, str], str, int]: ...
226
```
227

228
[OAuth 2.0 Servers](./oauth2-servers.md)
229

230
### Token Management
231

232
Token creation, validation, and formatting with support for Bearer tokens, MAC tokens, and JWT tokens. Includes token generators, validators, and utility functions for token handling.
233

234
```python { .api }
235
class BearerToken:
236
    def __init__(
237
        self,
238
        request_validator=None,
239
        token_generator=None,
240
        expires_in: int | None = None,
241
        refresh_token_generator=None,
242
    ): ...
243
    
244
    def create_token(self, request, refresh_token: bool = False, **kwargs) -> dict[str, str]: ...
245
    def validate_request(self, request) -> bool: ...
246

247
class OAuth2Token(dict):
248
    @property
249
    def scope_changed(self) -> bool: ...
250
    @property
251
    def scopes(self) -> list[str]: ...
252
    @property
253
    def missing_scopes(self) -> list[str]: ...
254
```
255

256
[Token Management](./token-management.md)
257

258
### Request Validation
259

260
Comprehensive request validation interfaces for both OAuth 1.0 and OAuth 2.0 flows. Provides extensible validation framework for custom authentication logic and security policies.
261

262
```python { .api }
263
class RequestValidator:
264
    def validate_client_id(self, client_id: str, request, *args, **kwargs) -> bool: ...
265
    def authenticate_client(self, request, *args, **kwargs) -> bool: ...
266
    def validate_redirect_uri(self, client_id: str, redirect_uri: str, request, *args, **kwargs) -> bool: ...
267
    def validate_scopes(self, client_id: str, scopes: list[str], client, request, *args, **kwargs) -> bool: ...
268
    def save_authorization_code(self, client_id: str, code: dict, request, *args, **kwargs) -> None: ...
269
    def save_token(self, token: dict, request, *args, **kwargs) -> None: ...
270
```
271

272
[Request Validation](./request-validation.md)
273

274
### Common Utilities
275

276
Shared utilities for parameter handling, token generation, URI validation, and cryptographic operations. Includes request/response handling and OAuth-specific data structures.
277

278
```python { .api }
279
class Request:
280
    def __init__(
281
        self,
282
        uri: str,
283
        http_method: str = "GET",
284
        body: str | dict[str, str] | list[tuple[str, str]] | None = None,
285
        headers: dict[str, str] | None = None,
286
        encoding: str = "utf-8",
287
    ): ...
288
    
289
    @property
290
    def uri_query_params(self) -> list[tuple[str, str]]: ...
291

292
def generate_token(length: int = 30, chars: str = ...) -> str: ...
293
def generate_nonce() -> str: ...
294
def generate_timestamp() -> str: ...
295
def safe_string_equals(a: str, b: str) -> bool: ...
296
```
297

298
[Common Utilities](./common-utilities.md)
299

300
### OpenID Connect
301

302
OpenID Connect identity layer implementation providing ID tokens, UserInfo endpoint, and authentication extensions to OAuth 2.0. Includes JWT token handling and claims processing.
303

304
```python { .api }
305
class RequestValidator:  # OpenID Connect extension
306
    def get_id_token(self, token: dict, token_handler, request) -> str: ...
307
    def validate_id_token(self, token: str, scopes: list[str], request) -> bool: ...
308
    def get_userinfo_claims(self, request) -> dict | str: ...
309
    def validate_silent_authorization(self, request) -> bool: ...
310

311
class Server:
312
    def create_userinfo_response(
313
        self,
314
        uri: str,
315
        http_method: str = "GET",
316
        body: str | None = None,
317
        headers: dict[str, str] | None = None,
318
        **kwargs,
319
    ) -> tuple[dict[str, str], str, int]: ...
320
```
321

322
[OpenID Connect](./openid-connect.md)
323

324
### Device Flow
325

326
OAuth 2.0 device authorization grant (RFC 8628) for input-constrained devices like smart TVs, game consoles, and IoT devices. Provides device and user codes for out-of-band authorization.
327

328
```python { .api }
329
class DeviceClient:
330
    def prepare_device_authorization_request(
331
        self,
332
        device_authorization_endpoint: str,
333
        scope: str | list[str] | None = None,
334
        **kwargs,
335
    ) -> tuple[str, dict[str, str], str]: ...
336

337
class DeviceAuthorizationEndpoint:
338
    def create_device_authorization_response(
339
        self,
340
        uri: str,
341
        http_method: str = "POST",
342
        body: str | None = None,
343
        headers: dict[str, str] | None = None,
344
        **kwargs,
345
    ) -> tuple[dict[str, str], str, int]: ...
346
```
347

348
[Device Flow](./device-flow.md)
349

350
### Error Handling
351

352
Comprehensive exception hierarchy for OAuth 1.0, OAuth 2.0, and OpenID Connect errors. Provides specific error types for different failure scenarios with proper HTTP status codes and error responses.
353

354
```python { .api }
355
class OAuth2Error(Exception):
356
    error: str | None
357
    status_code: int
358
    description: str
359
    def in_uri(self, uri: str) -> str: ...
360
    @property
361
    def json(self) -> str: ...
362

363
class InvalidClientError(OAuth2Error): ...
364
class InvalidGrantError(OAuth2Error): ...
365
class AccessDeniedError(OAuth2Error): ...
366
class InvalidScopeError(OAuth2Error): ...
367
```
368

369
[Error Handling](./error-handling.md)
370

371
## Types
372

373
```python { .api }
374
# Core module functions
375
def set_debug(debug_val: bool) -> None:
376
    """Set debug mode for the library."""
377

378
def get_debug() -> bool:
379
    """Get current debug mode status."""
380

381
# Module metadata
382
__author__: str
383
__version__: str
384

385
# HTTP method types
386
_HTTPMethod = Literal["CONNECT", "DELETE", "GET", "HEAD", "OPTIONS", "PATCH", "POST", "PUT", "TRACE"]
387

388
# Token placement options
389
_TokenPlacement = Literal["auth_header", "query", "body"]
390

391
# Case-insensitive dictionary for headers
392
class CaseInsensitiveDict(dict[str, Any]):
393
    def __init__(self, data: dict[str, Any]) -> None: ...
394
    def __contains__(self, k: str) -> bool: ...
395
    def __getitem__(self, k: str): ...
396
    def get(self, k: str, default=None): ...
397

398
# OAuth signature method constants
399
SIGNATURE_HMAC_SHA1: str
400
SIGNATURE_RSA_SHA1: str
401
SIGNATURE_PLAINTEXT: str
402
SIGNATURE_TYPE_AUTH_HEADER: str
403
SIGNATURE_TYPE_QUERY: str
404
SIGNATURE_TYPE_BODY: str
405
```