0
# Custom Token Types
1

2
Extended OAuth token classes that include provider-specific metadata and additional fields beyond the standard access token, refresh token, and expiration information. These tokens provide access to platform-specific data returned during the OAuth flow.
3

4
## Capabilities
5

6
### Salesforce Token
7

8
Salesforce-specific access token that includes the Salesforce organization instance URL for API calls.
9

10
```java { .api }
11
public class SalesforceToken extends OAuth2AccessToken {
12
    public SalesforceToken(String accessToken, String instanceUrl, String rawResponse);
13
    public SalesforceToken(String accessToken, String tokenType, Integer expiresIn,
14
                          String refreshToken, String scope, String instanceUrl, String rawResponse);
15
    
16
    // Standard OAuth2AccessToken methods
17
    public String getAccessToken();
18
    public String getTokenType();
19
    public Integer getExpiresIn();
20
    public String getRefreshToken();
21
    public String getScope();
22
    public String getRawResponse();
23
    
24
    // Salesforce-specific methods
25
    public String getInstanceUrl();    // Salesforce instance URL for API calls
26
}
27
```
28

29
**Usage Example:**
30
```java
31
OAuth20Service service = new ServiceBuilder("client_id")
32
    .apiSecret("client_secret")
33
    .callback("callback_url")
34
    .build(SalesforceApi.instance());
35

36
SalesforceToken token = (SalesforceToken) service.getAccessToken("authorization_code");
37

38
// Use Salesforce-specific information
39
String instanceUrl = token.getInstanceUrl(); // e.g., "https://mycompany.salesforce.com"
40

41
// Make API calls to the correct instance
42
OAuthRequest request = new OAuthRequest(Verb.GET, instanceUrl + "/services/data/v57.0/sobjects/Account");
43
service.signRequest(token.getAccessToken(), request);
44
```
45

46
### OpenID Connect Token
47

48
OpenID Connect access token that includes ID token and decoded claims for identity information.
49

50
```java { .api }
51
public class OpenIdOAuth2AccessToken extends OAuth2AccessToken {
52
    public OpenIdOAuth2AccessToken(String accessToken, String tokenType, Integer expiresIn,
53
                                  String refreshToken, String scope, String idToken,
54
                                  String rawResponse);
55
    
56
    // Standard OAuth2AccessToken methods
57
    public String getAccessToken();
58
    public String getTokenType();
59
    public Integer getExpiresIn();
60
    public String getRefreshToken();
61
    public String getScope();
62
    public String getRawResponse();
63
    
64
    // OpenID Connect specific methods
65
    public String getIdToken();                    // JWT ID token
66
    public JsonNode getIdTokenClaims();           // Decoded ID token claims
67
    public boolean isIdTokenExpired();            // Check if ID token is expired
68
}
69
```
70

71
**Usage Example:**
72
```java
73
OAuth20Service service = new ServiceBuilder("client_id")
74
    .apiSecret("client_secret")
75
    .callback("callback_url")
76
    .defaultScope("openid profile email")
77
    .build(GoogleApi20.instance());
78

79
OpenIdOAuth2AccessToken token = (OpenIdOAuth2AccessToken) service.getAccessToken("authorization_code");
80

81
// Access OpenID Connect information
82
String idToken = token.getIdToken(); // JWT token
83
JsonNode claims = token.getIdTokenClaims();
84

85
// Extract user information from claims
86
String email = claims.get("email").asText();
87
String name = claims.get("name").asText();
88
String picture = claims.get("picture").asText();
89
boolean emailVerified = claims.get("email_verified").asBoolean();
90
```
91

92
### Slack Token
93

94
Slack-specific OAuth 2.0 token that includes user access token for Slack API calls.
95

96
```java { .api }
97
public class SlackOAuth2AccessToken extends OAuth2AccessToken {
98
    public SlackOAuth2AccessToken(String accessToken, String tokenType, Integer expiresIn,
99
                                 String refreshToken, String scope, String userAccessToken, String rawResponse);
100
    
101
    // Standard OAuth2AccessToken methods
102
    public String getAccessToken();
103
    public String getTokenType();
104
    public Integer getExpiresIn();
105
    public String getRefreshToken();
106
    public String getScope();
107
    public String getRawResponse();
108
    
109
    // Slack-specific methods
110
    public String getUserAccessToken();    // User access token from authed_user.access_token
111
}
112
```
113

114
**Usage Example:**
115
```java
116
OAuth20Service service = new ServiceBuilder("client_id")
117
    .apiSecret("client_secret")
118
    .callback("callback_url")
119
    .defaultScope("channels:read users:read")
120
    .build(SlackApi.instance());
121

122
SlackOAuth2AccessToken token = (SlackOAuth2AccessToken) service.getAccessToken("authorization_code");
123

124
// Access Slack-specific information  
125
String userAccessToken = token.getUserAccessToken(); // User-specific access token
126

127
// Use bot token for bot API calls
128
OAuthRequest botRequest = new OAuthRequest(Verb.GET, "https://slack.com/api/auth.test");
129
service.signRequest(token.getAccessToken(), botRequest);
130

131
// Use user token for user API calls if available
132
if (!userAccessToken.isEmpty()) {
133
    OAuthRequest userRequest = new OAuthRequest(Verb.GET, "https://slack.com/api/users.info");
134
    userRequest.addHeader("Authorization", "Bearer " + userAccessToken);
135
}
136
```
137

138
### Fitbit Token
139

140
Fitbit-specific OAuth 2.0 token that includes user ID for Fitbit API calls.
141

142
```java { .api }
143
public class FitBitOAuth2AccessToken extends OAuth2AccessToken {
144
    public FitBitOAuth2AccessToken(String accessToken, String tokenType, Integer expiresIn,
145
                                  String refreshToken, String scope, String userId,
146
                                  String rawResponse);
147
    
148
    // Standard OAuth2AccessToken methods
149
    public String getAccessToken();
150
    public String getTokenType();
151
    public Integer getExpiresIn();
152
    public String getRefreshToken();
153
    public String getScope();
154
    public String getRawResponse();
155
    
156
    // Fitbit-specific methods
157
    public String getUserId();         // Fitbit user ID for API calls
158
}
159
```
160

161
**Usage Example:**
162
```java
163
OAuth20Service service = new ServiceBuilder("client_id")
164
    .apiSecret("client_secret")
165
    .callback("callback_url")
166
    .defaultScope("activity profile")
167
    .build(FitbitApi20.instance());
168

169
FitBitOAuth2AccessToken token = (FitBitOAuth2AccessToken) service.getAccessToken("authorization_code");
170

171
// Use Fitbit user ID in API calls
172
String userId = token.getUserId(); // e.g., "26FWFL"
173

174
OAuthRequest request = new OAuthRequest(Verb.GET, 
175
    "https://api.fitbit.com/1/user/" + userId + "/activities/date/today.json");
176
service.signRequest(token.getAccessToken(), request);
177
```
178

179
### Polar Token
180

181
Polar-specific OAuth 2.0 token that includes user ID and X-User-ID for Polar API calls.
182

183
```java { .api }
184
public class PolarOAuth2AccessToken extends OAuth2AccessToken {
185
    public PolarOAuth2AccessToken(String accessToken, String tokenType, Integer expiresIn,
186
                                 String refreshToken, String scope, Integer userId,
187
                                 Integer xUserId, String rawResponse);
188
    
189
    // Standard OAuth2AccessToken methods
190
    public String getAccessToken();
191
    public String getTokenType();
192
    public Integer getExpiresIn();
193
    public String getRefreshToken();
194
    public String getScope();
195
    public String getRawResponse();
196
    
197
    // Polar-specific methods
198
    public Integer getUserId();        // Polar user ID
199
    public Integer getXUserId();       // Polar X-User-ID for API headers
200
}
201
```
202

203
**Usage Example:**
204
```java
205
OAuth20Service service = new ServiceBuilder("client_id")
206
    .apiSecret("client_secret")
207
    .callback("callback_url")
208
    .build(PolarAPI.instance());
209

210
PolarOAuth2AccessToken token = (PolarOAuth2AccessToken) service.getAccessToken("authorization_code");
211

212
// Use Polar user information
213
Integer userId = token.getUserId();
214
Integer xUserId = token.getXUserId();
215

216
// Add X-User-ID header to requests
217
OAuthRequest request = new OAuthRequest(Verb.GET, "https://www.polaraccesslink.com/v3/users/" + userId);
218
request.addHeader("X-User-ID", xUserId.toString());
219
service.signRequest(token.getAccessToken(), request);
220
```
221

222
## Token Extraction
223

224
Custom tokens are automatically created by their corresponding token extractors when using the appropriate API:
225

226
```java { .api }
227
// Token extractors automatically return the correct token type
228
TokenExtractor<OAuth2AccessToken> extractor = api.getAccessTokenExtractor();
229
OAuth2AccessToken token = extractor.extract(response); // Returns specialized token type
230
```
231

232
## Type Safety
233

234
When using custom tokens, you can safely cast to the specific type:
235

236
```java
237
// Safe casting when using the corresponding API
238
SalesforceToken salesforceToken = (SalesforceToken) service.getAccessToken("code");
239
SlackOAuth2AccessToken slackToken = (SlackOAuth2AccessToken) service.getAccessToken("code");
240
OpenIdOAuth2AccessToken openIdToken = (OpenIdOAuth2AccessToken) service.getAccessToken("code");
241
```
242

243
### VKontakte Token
244

245
VKontakte-specific OAuth 2.0 token that includes user email for VKontakte API calls.
246

247
```java { .api }
248
public class VKOAuth2AccessToken extends OAuth2AccessToken {
249
    public VKOAuth2AccessToken(String accessToken, String email, String rawResponse);
250
    public VKOAuth2AccessToken(String accessToken, String tokenType, Integer expiresIn,
251
                              String refreshToken, String scope, String email, String rawResponse);
252
    
253
    // Standard OAuth2AccessToken methods
254
    public String getAccessToken(); 
255
    public String getTokenType();
256
    public Integer getExpiresIn();
257
    public String getRefreshToken();
258
    public String getScope();
259
    public String getRawResponse();
260
    
261
    // VKontakte-specific methods
262
    public String getEmail();         // User email from VKontakte response
263
}
264
```
265

266
**Usage Example:**
267
```java
268
OAuth20Service service = new ServiceBuilder("client_id")
269
    .apiSecret("client_secret")
270
    .callback("callback_url")
271
    .build(VkontakteApi.instance());
272

273
VKOAuth2AccessToken token = (VKOAuth2AccessToken) service.getAccessToken("authorization_code");
274

275
// Access VKontakte-specific information
276
String email = token.getEmail(); // User's email address
277

278
// Make API calls
279
OAuthRequest request = new OAuthRequest(Verb.GET, "https://api.vk.com/method/users.get");
280
service.signRequest(token.getAccessToken(), request);
281
```
282

283
## Complete Custom Token List
284

285
| Token Class | API | Additional Fields |
286
|-------------|-----|-------------------|
287
| `SalesforceToken` | `SalesforceApi` | `instanceUrl` |
288
| `OpenIdOAuth2AccessToken` | `GoogleApi20` (with OpenID scope) | `idToken`, `idTokenClaims` |
289
| `SlackOAuth2AccessToken` | `SlackApi` | `userAccessToken` |
290
| `FitBitOAuth2AccessToken` | `FitbitApi20` | `userId` |
291
| `PolarOAuth2AccessToken` | `PolarAPI` | `userId`, `xUserId` |
292
| `VKOAuth2AccessToken` | `VkontakteApi` | `email` |
293
294
## Common Usage Pattern
295

296
```java
297
// 1. Create service with appropriate API
298
OAuth20Service service = new ServiceBuilder("client_id")
299
    .apiSecret("client_secret")
300
    .callback("callback_url")
301
    .build(ProviderApi.instance());
302

303
// 2. Get specialized token (automatically typed)
304
SpecializedToken token = (SpecializedToken) service.getAccessToken("authorization_code");
305

306
// 3. Use provider-specific information
307
String providerId = token.getProviderSpecificId();
308
String providerUrl = token.getProviderSpecificUrl();
309

310
// 4. Make API calls using specialized information
311
OAuthRequest request = new OAuthRequest(Verb.GET, providerUrl + "/api/endpoint");
312
service.signRequest(token.getAccessToken(), request);
313
```