0
# Requests-OAuthlib
1

2
A first-class OAuth library that integrates OAuth 1.0a and OAuth 2.0 authentication support seamlessly with the Requests HTTP library. It provides session-based OAuth clients and authentication classes that handle token management, signature generation, and protocol-specific requirements automatically.
3

4
## Package Information
5

6
- **Package Name**: requests-oauthlib
7
- **Language**: Python
8
- **Installation**: `pip install requests-oauthlib`
9

10
## Core Imports
11

12
```python
13
from requests_oauthlib import OAuth1Session, OAuth2Session, OAuth1, OAuth2, __version__
14
```
15

16
For OAuth 1.0 constants:
17

18
```python
19
from oauthlib.oauth1 import SIGNATURE_HMAC, SIGNATURE_RSA, SIGNATURE_PLAIN
20
from oauthlib.oauth1 import SIGNATURE_TYPE_AUTH_HEADER, SIGNATURE_TYPE_QUERY, SIGNATURE_TYPE_BODY
21
```
22

23
For provider-specific compliance fixes:
24

25
```python
26
from requests_oauthlib.compliance_fixes import facebook_compliance_fix, slack_compliance_fix
27
```
28

29
## Basic Usage
30

31
### OAuth 1.0a Session Example
32

33
```python
34
from requests_oauthlib import OAuth1Session
35

36
# Create OAuth 1 session
37
oauth = OAuth1Session(
38
    'client_key',
39
    client_secret='client_secret',
40
    callback_uri='https://example.com/callback'
41
)
42

43
# Fetch request token
44
request_token_url = 'https://api.provider.com/oauth/request_token'
45
token = oauth.fetch_request_token(request_token_url)
46

47
# Get authorization URL
48
authorization_url = 'https://api.provider.com/oauth/authorize'
49
auth_url = oauth.authorization_url(authorization_url)
50
print(f'Please go to {auth_url} and authorize access.')
51

52
# After user authorization, fetch access token
53
access_token_url = 'https://api.provider.com/oauth/access_token'
54
access_token = oauth.fetch_access_token(access_token_url)
55

56
# Make authenticated requests
57
response = oauth.get('https://api.provider.com/protected_resource')
58
```
59

60
### OAuth 2.0 Session Example
61

62
```python
63
from requests_oauthlib import OAuth2Session
64

65
# Create OAuth 2 session
66
oauth = OAuth2Session(
67
    'client_id',
68
    redirect_uri='https://example.com/callback',
69
    scope=['read', 'write']
70
)
71

72
# Get authorization URL
73
authorization_url = 'https://api.provider.com/oauth/authorize'
74
auth_url, state = oauth.authorization_url(authorization_url)
75
print(f'Please go to {auth_url} and authorize access.')
76

77
# Fetch access token using authorization code
78
token_url = 'https://api.provider.com/oauth/token'
79
token = oauth.fetch_token(
80
    token_url,
81
    authorization_response='https://example.com/callback?code=AUTH_CODE&state=STATE'
82
)
83

84
# Make authenticated requests
85
response = oauth.get('https://api.provider.com/protected_resource')
86
```
87

88
## Architecture
89

90
The library follows a dual-layer architecture:
91

92
- **Authentication Classes** (`OAuth1`, `OAuth2`): Low-level authentication handlers that implement the `requests.auth.AuthBase` interface for signing individual requests
93
- **Session Classes** (`OAuth1Session`, `OAuth2Session`): High-level workflow managers that extend `requests.Session` with OAuth-specific methods for token management and the complete authentication flow
94
- **Compliance Fixes**: Provider-specific modifications to handle non-standard OAuth implementations
95

96
This design enables both simple authentication of existing requests and full OAuth workflow management through convenient session-based interfaces.
97

98
## Capabilities
99

100
### OAuth 1.0a Authentication
101

102
Comprehensive OAuth 1.0a support including request signing, token workflows, and session management with support for HMAC-SHA1, RSA-SHA1, and PLAINTEXT signature methods.
103

104
```python { .api }
105
class OAuth1(requests.auth.AuthBase):
106
    def __init__(
107
        self,
108
        client_key: str,
109
        client_secret: str = None,
110
        resource_owner_key: str = None,
111
        resource_owner_secret: str = None,
112
        callback_uri: str = None,
113
        signature_method: str = SIGNATURE_HMAC,
114
        signature_type: str = SIGNATURE_TYPE_AUTH_HEADER,
115
        rsa_key: str = None,
116
        verifier: str = None,
117
        decoding: str = "utf-8",
118
        client_class = None,
119
        force_include_body: bool = False,
120
        **kwargs
121
    ): ...
122

123
class OAuth1Session(requests.Session):
124
    def __init__(
125
        self,
126
        client_key: str,
127
        client_secret: str = None,
128
        resource_owner_key: str = None,
129
        resource_owner_secret: str = None,
130
        callback_uri: str = None,
131
        signature_method: str = SIGNATURE_HMAC,
132
        signature_type: str = SIGNATURE_TYPE_AUTH_HEADER,
133
        rsa_key: str = None,
134
        verifier: str = None,
135
        client_class = None,
136
        force_include_body: bool = False,
137
        **kwargs
138
    ): ...
139
```
140

141
[OAuth 1.0a Implementation](./oauth1.md)
142

143
### OAuth 2.0 Authentication
144

145
Full OAuth 2.0 support with automatic token refresh, PKCE extension, compliance hooks, and support for all standard grant types including Authorization Code, Implicit, Resource Owner Password, and Client Credentials.
146

147
```python { .api }
148
class OAuth2(requests.auth.AuthBase):
149
    def __init__(
150
        self,
151
        client_id: str = None,
152
        client = None,
153
        token: dict = None
154
    ): ...
155

156
class OAuth2Session(requests.Session):
157
    def __init__(
158
        self,
159
        client_id: str = None,
160
        client = None,
161
        auto_refresh_url: str = None,
162
        auto_refresh_kwargs: dict = None,
163
        scope: list = None,
164
        redirect_uri: str = None,
165
        token: dict = None,
166
        state = None,
167
        token_updater = None,
168
        pkce: str = None,
169
        **kwargs
170
    ): ...
171
```
172

173
[OAuth 2.0 Implementation](./oauth2.md)
174

175
### Provider Compliance Fixes
176

177
Pre-built compliance fixes for popular OAuth providers that implement non-standard OAuth behaviors, enabling seamless integration with services like Facebook, Slack, Instagram, and others.
178

179
```python { .api }
180
def facebook_compliance_fix(session: OAuth2Session) -> OAuth2Session: ...
181
def slack_compliance_fix(session: OAuth2Session) -> OAuth2Session: ...
182
def instagram_compliance_fix(session: OAuth2Session) -> OAuth2Session: ...
183
def mailchimp_compliance_fix(session: OAuth2Session) -> OAuth2Session: ...
184
def fitbit_compliance_fix(session: OAuth2Session) -> OAuth2Session: ...
185
def weibo_compliance_fix(session: OAuth2Session) -> OAuth2Session: ...
186
def plentymarkets_compliance_fix(session: OAuth2Session) -> OAuth2Session: ...
187
def ebay_compliance_fix(session: OAuth2Session) -> OAuth2Session: ...
188
```
189

190
[Compliance Fixes](./compliance-fixes.md)
191

192
## Types
193

194
```python { .api }
195
class TokenRequestDenied(ValueError):
196
    def __init__(self, message: str, response): ...
197
    @property
198
    def status_code(self) -> int: ...
199

200
class TokenMissing(ValueError):
201
    def __init__(self, message: str, response): ...
202

203
class VerifierMissing(ValueError): ...
204

205
class TokenUpdated(Warning):
206
    def __init__(self, token: dict): ...
207

208
# Package version constant
209
__version__: str = "2.0.0"
210
```
211

212
## Constants
213

214
```python { .api }
215
# OAuth 1.0 Signature Methods
216
SIGNATURE_HMAC: str = "HMAC-SHA1"
217
SIGNATURE_RSA: str = "RSA-SHA1"  
218
SIGNATURE_PLAIN: str = "PLAINTEXT"
219

220
# OAuth 1.0 Signature Types
221
SIGNATURE_TYPE_AUTH_HEADER: str = "AUTH_HEADER"
222
SIGNATURE_TYPE_QUERY: str = "QUERY"
223
SIGNATURE_TYPE_BODY: str = "BODY"
224
```