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/

Using either method, if you need to make a test call on the API, we suggest the "me" call:

GET to URL: https://api.scopestack.io/v1/me

Authorization Code Flow

This flow allows 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:

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

To enable the flow, you will need

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 it for your bearer token. Copy that URL into your web browser and press enter. You will be asked to log in if you're not logged into ScopeStack. 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?