The Application Programming Interface (API) is secured using the industry-standard OAuth2 protocol. ScopeStack recommends using the Authorization Code Flow.

Swagger documentation for using our API can be found at the root of the API itself https://api.scopestack.io/

Authorization Code Flow

This flow is used to allow other applications to connect to the ScopeStack API and interact with your data on our platform.

Once Custom OAuth Callback is enabled for your account, you can access the OAUTH CALLBACK URL tab in your Account Settings.

Here you can enter the Callback URL for the application you are integrating. After clicking Save, you will be provided a Client ID and Client Secret that can be used with the application you are setting up.

Our application requires a standard OAuth v2 Authorization Flow to the following Endpoints:

Refresh Token Requests can be made as POST requests to: https://app.scopestack.io/oauth/token

If you need to make a test call on the API, we suggest the Account level call:

GET to URL: https://api.scopestack.io/v1/accounts/{your-account-slug}

For more information on OAuth2 and the authorization code flow, please see the Authorization Code Grant article at oauth.com.

Out of Band (OOB) Flow

This flow is used during the early stages of the development of integrations with ScopeStack or to demonstrate the basic functions of our API.

This flow begins with an HTTP GET request to https://app.scopestack.io/oauth/authorize with the following parameters:

  • redirect_uri: 'urn:ietf:wg:oauth:2.0:oob'

  • client_id: 'RgBzfGa7M8EWytl0hmrr1tvuKMS5dnbSf-CNklATrkg'

  • client_secret: 'Br-R1mDx8MgBBc5KROejTwz7UgL7gEU61Edd47mHOOE'

  • response_type: 'code'

The URL that is generated for that request is:

https://app.scopestack.io/oauth/authorize?client_id=RgBzfGa7M8EWytl0hmrr1tvuKMS5dnbSf-CNklATrkg&client_secret=Br-R1mDx8MgBBc5KROejTwz7UgL7gEU61Edd47mHOOE&redirect_uri=urn:ietf:wg:oauth:2.0:oob&response_type=code

To get the code you will exchange for your bearer token, you can copy that URL into your web browser and press enter. If you're not logged into ScopeStack, you will be asked to log in. You will be shown a value that looks like this:

The code that is received may then be exchanged for the authorization code by sending an HTTP POST to https://app.scopestack.io/oauth/token.json. The post should include the following parameters:

  • redirect_uri, client_id, client_secret (same as above)

  • code: the code returned to the GET request above

  • grant_type: 'authorization_code'

The URL that is generated for this request will be something like this:

https://app.scopestack.io/oauth/token.json?client_id=RgBzfGa7M8EWytl0hmrr1tvuKMS5dnbSf-CNklATrkg&client_secret=Br-R1mDx8MgBBc5KROejTwz7UgL7gEU61Edd47mHOOE&redirect_uri=urn:ietf:wg:oauth:2.0:oob&grant_type=authorization_code&code=THIS-IS-THE-CODE-FROM-THE-PREVIOUS-STEP

The response to this POST request will include the Authorization Code, the official time it was issued, the duration for which it is valid, and a refresh token. The authorization code must be used as an HTTP Authorization bearer token header for all access to the API.

Once the token has expired, authorization can be refreshed by following the Refresh Token Grant process as described at oauth.com.

Did this answer your question?