API Reference
Guides

Authentication & Authorization

Suggest Edits

Step 1: Requesting User Consent

The first step in the OAuth flow is to obtain the User's consent. The requesting application should redirect the FUB User to the following URL to obtain consent:

GET https://app.followupboss.com/oauth/authorize
    ?response_type=auth_code
    &client_id=<your_client_id>
    &redirect_uri=<your_redirect_uri>
    &state=<opaque_state_value>
ParameterDescription
response_type <string>This parameter tells the authorization server which grant to use. Currently, it only supports response_type=auth_code for the Authorization Code Grant Flow.
client_id <string>The unique ID, issued by FUB, representing your OAuth Client App.
redirect_uri <string>This is the redirect URL specified when creating your OAuth Client App. After completing the authorization process, FUB will redirect the User to this URL. Be sure to URL encode the value of this parameter.
state <string>This is an opaque value provided by the requesting system to prevent CSRF attacks and to maintain the state between requests and callbacks.

Step 2: Receiving Authorization Grant

After obtaining consent, FUB will redirect the User back to the provided redirect_uri with the following query parameters:

GET https://<your_redirect_uri>
    ?response=<approved|denied>
    &code=<auth_code>
    &state=<state_value_from_request>
ParameterDescription
response <string>The value for this parameter will be approved if the FUB User consented and denied if they denied consent.
code <string>This is the authorization code (auth_code) that will be used by your OAuth Client App to redeem User tokens.
Note: This parameter is omitted when consent is denied.
state <string>The value for this parameter will be the same as the state value provided when requesting the User's consent.

🚧

Consent denied workflow

FUB does not provide any formal recommendations for handling consent denials. The user experience and messaging when a User denies consent is the responsibility of the system acting on behalf of the OAuth Client App.

Step 3: Exchanging auth_code for tokens

Perform the following request to exchange the auth_code for tokens:

GET https://app.followupboss.com/oauth/token
    ?grant_type=auth_code
    &code=<auth_code>
    &redirect_uri=<your_redirect_uri>
    &state=<opaque_state_value>

Your request must be Authenticated with HTTP Basic Authentication over HTTPS. Construct the authentication string by base64 encoding your OAuth Client App's Client ID and Secret.

Authentication: Basic base64("<client_id>:<client_secret>")
ParameterDescription
grant_type <string>This parameter tells the authorization server the type of grant you are trying to redeem.
Supported values:
- auth_code (for this Use Case)
- refresh_token
code <string>This is the authorization code (auth_code) that was provided in the previous response.
redirect_uri <string>This is the redirect URL specified when creating your OAuth Client App. We only use this value as an additional verification factor. Be sure to URL encode the value of this parameter.
state <string>This is an opaque value provided by the requesting system to prevent CSRF attacks and to maintain the state between requests and callbacks.

A successful response will include the Access & Refresh tokens representing the FUB User. The Token Exchange Response section details the response payload structure for successful and failed responses.

Step 4: Making Authenticated API Requests

🎉 Your OAuth Client App is ready to perform authenticated API Requests against the FUB API.

To perform authenticated requests, your request must be Authenticated with HTTP Bearer/Token Authentication over HTTPS.

Authentication: Bearer <valid_access_token>

For a complete list of available endpoints, refer to the Follow Up Boss API Reference

Step 5: Refreshing an Access Token

Access Tokens are short-lived tokens (See Token Lifetimes to learn more). Perform the following request to obtain a new Access Token:

GET https://app.followupboss.com/oauth/token
    ?grant_type=refresh_token
    &refresh_token=<refresh_token>

Your request must be Authenticated with HTTP Basic Authentication over HTTPS. Construct the authentication string by base64 encoding your OAuth Client App's Client ID and Secret.

Authentication: Basic base64("<client_id>:<client_secret>")
ParameterDescription
grant_type <string>This parameter tells the authorization server the type of grant you are trying to redeem.
Supported values:
- auth_code
- refresh_token (for this Use Case)
refresh_token <string>This is the FUB User's refresh token, which will be used to generate a new access token.

A successful response will include the Access & Refresh tokens representing the FUB User. The Token Exchange Response section details the response payload structure for successful and failed responses.

Updated about 1 month ago

What’s Next

Learn more about tokens & response types, or get started using the FUB API