Server to server service

Updated on 22-February-2017 at 11:28 AM

Business Catalyst End of life announcement - find out more details.

Note: Before going forward, please make sure you have followed the Enroll and Create New App steps described in the Register your app section.

Redirect URI

For this type of service, it is mandatory to provide an https redirect uri when registering your app which will act as your OAuth callback.

This is where BC will send the authorization code once authorized by Partner. If something wrong happens you will be notified to this URI with specific query parameters.

Note: It is strongly recommended to have a certificate signed by an authorized Authority (e.g VeriSign) on your site.

Implementation details

Details that you will need to initiate the service authorization sequence are:

  • Client ID - this is available by going to Partner Portal -> My Apps -> [Your App Id ] 
  • Version - the app's version you'll be using.
  • Redirect URI - the secure link of the page that will act as your oAuth callback.
  • Client secret - this is available by going to Partner Portal -> My Apps -> [Your app's name]
  • BC Authorize Endpoint - "/api/oauth/authorize"
  • BC Token Endpoint - "/api/oauth/token" (based on use case)

Once you have created your BC app and have all the necessary details you can go ahead and write your own code on your personal site or just go ahead and test our Node.js sample.

You can build any type of Service, Desktop or Mobile App in any language to get data from your BC site using API calls.

At the moment BusinessCatalyst provides an external service with two similar but distinct workflows. They are based on two OAuth grant types name code and implicit, described in detail in IETFs - The OAuth 2.0 Authorization Framework.

Authorization Code Grant Workflow

  • allow trusted applications to obtain an OAuth2 authorization code
  • used to obtain both access tokens and refresh tokens
  • is optimized for confidential clients
  • the client makes separate requests for authorization and for an access token
  • it uses both the authorize and token endpoint
  • useful for web based services apps that may need to renew authorization

Tip: This grant type is completely described in RFC6749 authorization code grant.

Step 1. Initiate service authorization request sequence

GET on <secure_url>/api/oauth/authorize

Parameters
  • response_type (required) tells the endpoint which grant type handler to use, in this case must equal code
  • client_id (required) - ID obtained from Partner Portal when registering an app
  • version (required) - version of the application
  • redirect_uri (required) - will be checked to match the one registered in the Partner Portal application page
  • state (required)this parameter must be used by the 3rd party to avoid XSS attacks, will be appended to received redirect uri, and can have any value

Step 1.1 Authenticate partner

If partner is not logged in, this window should appear:

Step 1.2 Ask partner consent for running the service

This windows should appear to select the sites you want authorized.

Step 1.3 Redirect to service

GET on <redirect_uri>

Parameters
  • response_type (required) tells the endpoint which grant type handler to use, in this case must equal code
  • client_id (required) - ID obtained from Partner Portal when registering an app
  • version (required) - version of the application
  • redirect_uri (required) - will be checked to match the one registered in the Partner Portal application page
  • state (required)this parameter must be used by the 3rd party to avoid XSS attacks, will be appended to received redirect uri, and can have any value
  • code (required) - the authorization_code

Step 2 Obtain access or refresh token

POST on <secure_url>/api/oauth/token
with Content-Type: application/x-www-formurlencoded

Parameters

  • client_id (required) - ID obtained from Partner Portal when registering an app
  • grant_type (required) - must equal authorization_code
  • redirect_uri (required) - will be checked to match the one registered in the Partner Portal application page
  • client_secret (required) - secret string obtained from Partner Portal when registering an app
  • code (required) - the authorization_code

Note: Keep in mind the access token expires in 4 hours and the refresh token expires in 7 days.

Step 2.1 Access token response

 

Step 3. Obtain a new access or refresh token (optional)

POST on <secure_url>/api/oauth/token with Content-Type: application/x-www-formurlencoded

Parameters:
  • grant_type (required) - must equal refresh_token
  • client_id (required) - ID obtained from Partner Portal when registering an app
  • redirect_uri (required) - will be checked to match the one registered in the Partner Portal application page
  • client_secret (required) - secret string obtained from Partner Portal when registering an app
  • refresh_token (required) - the refresh_token

Step 3.1 New access token response

Implicit (Token) Grant Workflow

  • is the equivalent of implicit OAuth2 flow
  • is used for generating an access token from Admin Console installed applications
  • does not include client authentication, and relies on the presence of the resource owner and the registration of the redirection URI
  • unlike the authorization code grant type, the client receives the access token as the result of the authorization request.
  • useful for web based services with no need for a refresh token
  • it uses only the authorize endpoint

Tip: This grant type is completely described in RFC6749 implicit grant.

Step 1. Initiate service authorization request sequence

GET on <secure_url>/api/oauth/authorize

Parameters
  • response_type (required) tells the endpoint which grant type handler to use, in this case must equal token
  • client_id (required) - ID obtained from Partner Portal when registering an app
  • redirect_uri (required) - will be checked to match the one registered in the Partner Portal application page
  • source (optional) - determines if the implicit grant was initiated from admin console or an external source.
    • admin = Admin console source.
    • external = External server source.
  • consent (optional) - determines the type of consent used by this authorization sequence.
    • no value specified = explicit consent screen.
    • implicit = no consent screen will be displayed but it requires user intervention.
  • site (optional) - only required if consent is set to implicit, should have the escaped user site url
  • state (optional) - only required if source is external

Step 1.1 Authenticate partner

If partner is not logged in, this window should appear:

Step 1.2 Ask partner consent for running the service

This windows should appear to select the sites you want authorized.

Step 1.3 Generate access token

Step 2. Response

GET on <https service uri>

After the last step, the user agent is redirected to the application with the access token in fragment and the following parameters that we already described: access_token, expires_in, token_type, site, state

The app developers should use the provided Javascript scripts to extract the access token and use it inside Admin Console applications.

Tip: More details on how to authorize your API calls.

GUI recommendations

  1. BC Partner can be redirected to BC /authorize using a popup window. It is mandatory to show the url of this popup so that Partner can see he is in a trusted and secure context (https).
  2. It is recommended to use 530px x 510px resolution when opening the popup window.
  3. It is recommended to make the popup window non resizeable.
  4. It is recommended to use https for market place redirect_uri.

If you are not logged into BC, this screen will appear first.

Then a partner consent window will appear where you can select what sites you want authorized.

Below you can find a code snippet which shows the recommended string for opening the popup window from javascript:

Error details

External services redirect uri must be implemented so that it correctly handles various errors which might occur in order to correctly inform BC Partner about authorization process. Here are the errors for the two endpoints:

/authorize

Any errors which occur during authorization by BC Partner are sent back to external service redirect_uri as query parameters:

  • error -> Holds a short code defining the error type which occurred
    • access_denied -> BC Partner cancelled the authorization.
    • invalid_request -> External service redirected BC Partner browser to authorize without passing all required query parameters.
    • unsupported_grant_type -> Response_type requested by external service is not supported by BC OAuth Authorization.
    • unknown -> A server error occured.
  • error_description -> Friendly error description meant to help external service find out what went wrong.
/token

Any error which occurs when exchanging the authorization_code for an access / refresh token tuple is sent back as an object with the following attributes:

  • error -> Holds a short code defining the error type which occurred.
    • unknown (http status code 500)-> A server error occured.
    • invalid_request (http status code 400) -> Some query parameters or missing or invalid.
    • invalid_client (http status code 400) -> Provided client_id is not valid.
    • invalid_grant (http status code 400) -> The external service requested a grant type which is not allowed,
    • unsupported_grant_type (http status code 400) ->The external service requested a grant type which is not supported by BC Authorization server.
  • error_description -> Friendly error description meant to help external service find out what went wrong.
  • error_uri -> At the moment this will be null. It is provided for extension and also to be compliant with RFC6749.

Be aware most of the times if an error occurs during exchange request the authorization code token is automatically invalidated and it can not be used to retry. In order to recover from this error, external service must ask BC Partner to initiate the authorization process again.

Runnable samples

This sample provides a third party server which showcase how to host bc-api-discovery outside BC and use it against sites from other partners. You can use it as a starting point for writing new bc services which ask partners consent to run on their partner portals.

BC External Service Sample