0
# ScribeJava APIs
1

2
ScribeJava APIs is a comprehensive OAuth client library module that provides ready-to-use implementations for over 50 major OAuth 1.0a and 2.0 providers including Google, Facebook, Twitter, GitHub, LinkedIn, Instagram, and many others. It offers a simple configuration approach with thread-safe operations and supports various HTTP clients while maintaining high performance and extensive compatibility from Java 7 onwards.
3

4
## Package Information
5

6
- **Package Name**: scribejava-apis
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Group ID**: com.github.scribejava
10
- **Artifact ID**: scribejava-apis
11
- **Installation**: `implementation 'com.github.scribejava:scribejava-apis:8.3.3'` (Gradle) or `<dependency><groupId>com.github.scribejava</groupId><artifactId>scribejava-apis</artifactId><version>8.3.3</version></dependency>` (Maven)
12

13
## Core Imports
14

15
```java
16
import com.github.scribejava.apis.GoogleApi20;
17
import com.github.scribejava.apis.FacebookApi;
18
import com.github.scribejava.apis.GitHubApi;
19
import com.github.scribejava.apis.TwitterApi;
20
import com.github.scribejava.core.builder.ServiceBuilder;
21
import com.github.scribejava.core.oauth.OAuth20Service;
22
import com.github.scribejava.core.oauth.OAuth10aService;
23
```
24

25
## Basic Usage
26

27
```java
28
import com.github.scribejava.apis.GoogleApi20;
29
import com.github.scribejava.core.builder.ServiceBuilder;
30
import com.github.scribejava.core.oauth.OAuth20Service;
31

32
// Create OAuth service for Google
33
OAuth20Service service = new ServiceBuilder("your_client_id")
34
    .apiSecret("your_client_secret")
35
    .callback("http://localhost:8080/callback")
36
    .build(GoogleApi20.instance());
37

38
// Get authorization URL
39
String authorizationUrl = service.getAuthorizationUrl();
40

41
// Exchange authorization code for access token
42
OAuth2AccessToken accessToken = service.getAccessToken("authorization_code");
43

44
// Use access token to make authenticated requests
45
OAuthRequest request = new OAuthRequest(Verb.GET, "https://www.googleapis.com/oauth2/v1/userinfo");
46
service.signRequest(accessToken.getAccessToken(), request);
47
Response response = service.execute(request);
48
```
49

50
## Architecture
51

52
ScribeJava APIs is built around several key components:
53

54
- **OAuth API Providers**: 63 implementation classes for specific OAuth providers, each extending either `DefaultApi20` (OAuth 2.0) or `DefaultApi10a` (OAuth 1.0a)
55
- **Singleton Pattern**: All API provider classes use the singleton pattern with `instance()` factory methods
56
- **Specialized Services**: Custom OAuth service implementations for providers requiring special handling (Facebook, Instagram, Mail.ru, etc.)
57
- **Token Extractors**: Custom token extractors for providers with non-standard token response formats
58
- **Custom Token Types**: Extended token classes that include provider-specific metadata (Salesforce, Slack, OpenID Connect, etc.)
59
- **URL Configuration**: Each provider defines authorization, token, and refresh endpoints specific to their OAuth implementation
60

61
## Capabilities
62

63
### OAuth 2.0 Provider APIs
64

65
Core OAuth 2.0 provider implementations supporting authorization code flow, client credentials, device authorization grant, and PKCE extensions. Covers 50+ major providers including social networks, cloud services, and enterprise identity providers.
66

67
```java { .api }
68
public abstract class DefaultApi20 {
69
    public static ApiClass instance();
70
    public String getAccessTokenEndpoint();
71
    protected String getAuthorizationBaseUrl();
72
    public TokenExtractor<OAuth2AccessToken> getAccessTokenExtractor();
73
    public String getRevokeTokenEndpoint();
74
    public String getRefreshTokenEndpoint();
75
    public ClientAuthentication getClientAuthentication();
76
    public String getDeviceAuthorizationEndpoint();
77
    public DeviceAuthorizationJsonExtractor getDeviceAuthorizationExtractor();
78
}
79
```
80

81
[OAuth 2.0 Providers](./oauth2-providers.md)
82

83
### OAuth 1.0a Provider APIs
84

85
OAuth 1.0a provider implementations supporting the three-legged authorization flow with request tokens and signature-based authentication. Includes Twitter, Yahoo, Flickr, and other legacy OAuth providers.
86

87
```java { .api }
88
public abstract class DefaultApi10a {
89
    public static ApiClass instance();
90
    public String getAccessTokenEndpoint();
91
    public String getRequestTokenEndpoint();
92
    public String getAuthorizationBaseUrl();
93
}
94
```
95

96
[OAuth 1.0a Providers](./oauth1a-providers.md)
97

98
### Specialized Services
99

100
Custom OAuth service implementations that extend the base OAuth functionality with provider-specific features like Facebook's app secret proof, Mail.ru's signature requirements, and Instagram's specialized token handling.
101

102
```java { .api }
103
public class FacebookService extends OAuth20Service {
104
    public void signRequest(String accessToken, OAuthRequest request);
105
}
106

107
public class MailruOAuthService extends OAuth20Service {
108
    public void signRequest(String accessToken, OAuthRequest request);
109
}
110
```
111

112
[Specialized Services](./specialized-services.md)
113

114
### Custom Token Types
115

116
Extended OAuth token classes that include provider-specific metadata and additional fields beyond the standard access token, refresh token, and expiration information.
117

118
```java { .api }
119
public class SalesforceToken extends OAuth2AccessToken {
120
    public String getInstanceUrl();
121
}
122

123
public class OpenIdOAuth2AccessToken extends OAuth2AccessToken {
124
    public String getIdToken();
125
    public JsonNode getIdTokenClaims();
126
}
127

128
public class VKOAuth2AccessToken extends OAuth2AccessToken {
129
    public String getEmail();
130
}
131
```
132

133
[Custom Token Types](./custom-tokens.md)
134

135
### Token Extractors
136

137
Custom token extractors for providers that use non-standard JSON response formats or require special error handling beyond the default OAuth 2.0 token response format.
138

139
```java { .api }
140
public abstract class OAuth2AccessTokenJsonExtractor implements TokenExtractor<OAuth2AccessToken> {
141
    public OAuth2AccessToken extract(Response response) throws IOException;
142
    public void generateError(Response response) throws IOException;
143
}
144
```
145

146
[Token Extractors](./token-extractors.md)
147

148
## Common Types
149

150
```java { .api }
151
// Core ScribeJava types from scribejava-core
152
import com.github.scribejava.core.model.OAuth2AccessToken;
153
import com.github.scribejava.core.model.OAuthRequest;
154
import com.github.scribejava.core.model.Response;
155
import com.github.scribejava.core.model.Verb;
156
import com.github.scribejava.core.oauth.OAuth20Service;
157
import com.github.scribejava.core.oauth.OAuth10aService;
158
import com.github.scribejava.core.builder.ServiceBuilder;
159
import com.github.scribejava.core.extractors.TokenExtractor;
160
import com.github.scribejava.core.oauth2.clientauthentication.ClientAuthentication;
161
```