CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-github-scribejava--scribejava-apis

OAuth client library APIs for 50+ major OAuth 1.0a and 2.0 providers

—

Pending
Overview
Eval results
Files

custom-tokens.mddocs/

Custom Token Types

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.

Capabilities

Salesforce Token

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

public class SalesforceToken extends OAuth2AccessToken {
    public SalesforceToken(String accessToken, String instanceUrl, String rawResponse);
    public SalesforceToken(String accessToken, String tokenType, Integer expiresIn,
                          String refreshToken, String scope, String instanceUrl, String rawResponse);
    
    // Standard OAuth2AccessToken methods
    public String getAccessToken();
    public String getTokenType();
    public Integer getExpiresIn();
    public String getRefreshToken();
    public String getScope();
    public String getRawResponse();
    
    // Salesforce-specific methods
    public String getInstanceUrl();    // Salesforce instance URL for API calls
}

Usage Example:

OAuth20Service service = new ServiceBuilder("client_id")
    .apiSecret("client_secret")
    .callback("callback_url")
    .build(SalesforceApi.instance());

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

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

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

OpenID Connect Token

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

public class OpenIdOAuth2AccessToken extends OAuth2AccessToken {
    public OpenIdOAuth2AccessToken(String accessToken, String tokenType, Integer expiresIn,
                                  String refreshToken, String scope, String idToken,
                                  String rawResponse);
    
    // Standard OAuth2AccessToken methods
    public String getAccessToken();
    public String getTokenType();
    public Integer getExpiresIn();
    public String getRefreshToken();
    public String getScope();
    public String getRawResponse();
    
    // OpenID Connect specific methods
    public String getIdToken();                    // JWT ID token
    public JsonNode getIdTokenClaims();           // Decoded ID token claims
    public boolean isIdTokenExpired();            // Check if ID token is expired
}

Usage Example:

OAuth20Service service = new ServiceBuilder("client_id")
    .apiSecret("client_secret")
    .callback("callback_url")
    .defaultScope("openid profile email")
    .build(GoogleApi20.instance());

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

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

// Extract user information from claims
String email = claims.get("email").asText();
String name = claims.get("name").asText();
String picture = claims.get("picture").asText();
boolean emailVerified = claims.get("email_verified").asBoolean();

Slack Token

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

public class SlackOAuth2AccessToken extends OAuth2AccessToken {
    public SlackOAuth2AccessToken(String accessToken, String tokenType, Integer expiresIn,
                                 String refreshToken, String scope, String userAccessToken, String rawResponse);
    
    // Standard OAuth2AccessToken methods
    public String getAccessToken();
    public String getTokenType();
    public Integer getExpiresIn();
    public String getRefreshToken();
    public String getScope();
    public String getRawResponse();
    
    // Slack-specific methods
    public String getUserAccessToken();    // User access token from authed_user.access_token
}

Usage Example:

OAuth20Service service = new ServiceBuilder("client_id")
    .apiSecret("client_secret")
    .callback("callback_url")
    .defaultScope("channels:read users:read")
    .build(SlackApi.instance());

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

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

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

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

Fitbit Token

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

public class FitBitOAuth2AccessToken extends OAuth2AccessToken {
    public FitBitOAuth2AccessToken(String accessToken, String tokenType, Integer expiresIn,
                                  String refreshToken, String scope, String userId,
                                  String rawResponse);
    
    // Standard OAuth2AccessToken methods
    public String getAccessToken();
    public String getTokenType();
    public Integer getExpiresIn();
    public String getRefreshToken();
    public String getScope();
    public String getRawResponse();
    
    // Fitbit-specific methods
    public String getUserId();         // Fitbit user ID for API calls
}

Usage Example:

OAuth20Service service = new ServiceBuilder("client_id")
    .apiSecret("client_secret")
    .callback("callback_url")
    .defaultScope("activity profile")
    .build(FitbitApi20.instance());

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

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

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

Polar Token

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

public class PolarOAuth2AccessToken extends OAuth2AccessToken {
    public PolarOAuth2AccessToken(String accessToken, String tokenType, Integer expiresIn,
                                 String refreshToken, String scope, Integer userId,
                                 Integer xUserId, String rawResponse);
    
    // Standard OAuth2AccessToken methods
    public String getAccessToken();
    public String getTokenType();
    public Integer getExpiresIn();
    public String getRefreshToken();
    public String getScope();
    public String getRawResponse();
    
    // Polar-specific methods
    public Integer getUserId();        // Polar user ID
    public Integer getXUserId();       // Polar X-User-ID for API headers
}

Usage Example:

OAuth20Service service = new ServiceBuilder("client_id")
    .apiSecret("client_secret")
    .callback("callback_url")
    .build(PolarAPI.instance());

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

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

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

Token Extraction

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

// Token extractors automatically return the correct token type
TokenExtractor<OAuth2AccessToken> extractor = api.getAccessTokenExtractor();
OAuth2AccessToken token = extractor.extract(response); // Returns specialized token type

Type Safety

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

// Safe casting when using the corresponding API
SalesforceToken salesforceToken = (SalesforceToken) service.getAccessToken("code");
SlackOAuth2AccessToken slackToken = (SlackOAuth2AccessToken) service.getAccessToken("code");
OpenIdOAuth2AccessToken openIdToken = (OpenIdOAuth2AccessToken) service.getAccessToken("code");

VKontakte Token

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

public class VKOAuth2AccessToken extends OAuth2AccessToken {
    public VKOAuth2AccessToken(String accessToken, String email, String rawResponse);
    public VKOAuth2AccessToken(String accessToken, String tokenType, Integer expiresIn,
                              String refreshToken, String scope, String email, String rawResponse);
    
    // Standard OAuth2AccessToken methods
    public String getAccessToken(); 
    public String getTokenType();
    public Integer getExpiresIn();
    public String getRefreshToken();
    public String getScope();
    public String getRawResponse();
    
    // VKontakte-specific methods
    public String getEmail();         // User email from VKontakte response
}

Usage Example:

OAuth20Service service = new ServiceBuilder("client_id")
    .apiSecret("client_secret")
    .callback("callback_url")
    .build(VkontakteApi.instance());

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

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

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

Complete Custom Token List

Token ClassAPIAdditional Fields
SalesforceTokenSalesforceApiinstanceUrl
OpenIdOAuth2AccessTokenGoogleApi20 (with OpenID scope)idToken, idTokenClaims
SlackOAuth2AccessTokenSlackApiuserAccessToken
FitBitOAuth2AccessTokenFitbitApi20userId
PolarOAuth2AccessTokenPolarAPIuserId, xUserId
VKOAuth2AccessTokenVkontakteApiemail

Common Usage Pattern

// 1. Create service with appropriate API
OAuth20Service service = new ServiceBuilder("client_id")
    .apiSecret("client_secret")
    .callback("callback_url")
    .build(ProviderApi.instance());

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

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

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

Install with Tessl CLI

npx tessl i tessl/maven-com-github-scribejava--scribejava-apis

docs

custom-tokens.md

index.md

oauth1a-providers.md

oauth2-providers.md

specialized-services.md

token-extractors.md

tile.json