OAuth Support

External applications can access the Slingr App API through OAuth requests. We refer to these applications as OAuth Apps.

Follow the steps below to acquire and refresh the Access Token.

In the Slingr app #

1) Enabling OAuth support in builder and creating scopes #

Navigate to Security -> OAuth and enable OAuth support. This action will activate a form for OAuth Scopes. OAuth tokens security is now managed through OAuth scope groups, rather than user groups.

Remember to save your changes after making modifications.

2) Registering the OAuth app in the Slingr app #

Once OAuth is enabled, head to the Runtime section. In the secondary menu, locate OAuth Apps.

Proceed to create an OAuth App with the following fields:

In the OAuth app #

1) Prompt the user to log in and authorize the OAuth App. #

Prompt the user to log in and authorize the OAuth App by opening the Authorize URL in a new window. The URL should include the response_type and client_id parameters.

https://<appName>.slingrs.io/<env>/runtime/authorize?response_type=code&client_id=<client_id>

In this URL:

• appName refers to the app’s name.
• env is the environment name (e.g., dev or prod).
• client_id should be the client id specified in the OAuth App.

If an OAuth Authorization exists for the user and the OAuth App, a form requesting the user’s authorization for the OAuth App will be displayed. If the OAuth authorization is revoked from the Slingr App, the authorization form will reappear.

After the user’s authorization, a callback URL containing the authorization_code will be invoked from the Authorize page.

https://<oAuthAppAuthorizationCallbackUrl>?code=<authorization_code>

In this URL:

• oAuthAppAuthorizationCallbackUrl stands for the callback URL set in the OAuth App.
• authorization_code corresponds to the authorization code required for requesting the access token.

It’s expected that the endpoint executed by the callback URL will store the authorization code provided by the code parameter and subsequently close the authorization window.

2) Acquiring an Access Token with the Authorization Code #

To obtain an access token, initiate a POST request to the slingr app’s OAuth token endpoint.

POST https://<appName>.slingrs.io/<env>/runtime/api/oauth/token?grant_type=authorization_code&client_id=<client_id>&code=<authorization_code>

In this URL:

• appName is the app’s name.
• env refers to the environment name (e.g., dev or prod).
• client_id corresponds to the client id established in the OAuth App.
• authorization_code should be replaced with the code obtained in step 1.

If you encounter an expired authorization code while attempting to retrieve an access token, you will receive the following information:

{
    "access_token": "5HMxY4eBEK2xvmkATMCzSdJ0wTxMlSlF",
    "refresh_token": "ZqUeuPwAezCZWpDQqjCW",
    "token_type": "bearer",
    "expires_in": 28800,
    "scope": "scope1 scope2 scope3"
}

3) Put the access token in an authorization header in your requests #

Example: To retrieve a list of companies, execute a GET request while including the Authorization header with the Bearer token, which is the access token you obtained. Below is a sample request:

GET https://<appName>.slingrs.io/<env>/runtime/api/data/companies
> Authorization: Bearer <access_token>

In this request:

• appName stands for the app’s name.
• env represents the environment name, such as dev or prod.
• access_token should be replaced with the actual access token obtained in step 2. Upon successful authentication, this request will retrieve the desired list of companies from the API.

More info about using the REST API

4) Refresh the token #

Utilize the refresh token acquired in step 2 to initiate a request for a new access token. This enables you to obtain a new access token without requiring user involvement (as in step 1).

POST https://<appName>.slingrs.io/<env>/runtime/api/oauth/token?grant_type=refresh_token&client_id=<client_id>&code=<refresh_token>

In this URL:

• appName is the name of the app.
• env is the environment name (e.g., dev or prod).
• client_id corresponds to the client id established in the OAuth App.
• refresh_token is the refresh token obtained in step 2.

This process will yield a new access token, allowing you to seamlessly continue API interactions.

{
    "access_token": "oqChNyTJhKvTrHWawj61jTgsZTGrgVGT",
    "refresh_token": "gJYDedgagcZalmptnhBg",
    "token_type": "bearer",
    "expires_in": 28800,
    "scope": "scope1 scope2 scope3"
}

General Error Codes #

Below are descriptions for various general errors. More specific error descriptions for each method can be found in their respective sections.