OAuth Support

External applications can access to the Slingr App API via OAuth requests. Those applications we will call as OAuth Apps.

Follow the next steps to obtain and refresh the Access Token.

In the Slingr App

1) Enable OAuth support in Builder and create scopes

Go to Security -> OAuth and enable OAuth support. After that, a form for OAuth Scopes is enabled. Instead of user groups, oauth tokens security is managed by oauth scope groups.

Don’t forget to push changes.

2) Registering the OAuth App in the Slingr App

Once OAuth is enabled, Go to Runtime and in the secondary menu, you will find the OAuth Apps.

Create an OAuth App with the following fields.

In the OAuth App

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

Open the Authorize URL (with response_type and client_id parameters) in a new window and expect the user to log in and authorize the OAuth App.

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

where appName is the name of the app, env is the name of the environment, like dev and prod and client_id is the client id set in the OAuth App.

A form prompting the user to authorize the OAuth App will be shown if there exist an OAuth Authorization for the user and the OAuth App. OAuth authorizations can be revoked from the Slingr App, in that case the authorization form will be appear again.

After that, a callback URL with the authorization_code will be called from the Authorize page.

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

where oAuthAppAuthorizationCallbackUrl is the callback URL set in the OAuth App and authorization_code is the authorization code you will need to request the access token.

It is expected that the endpoint executed by the callback URL, store the authorization code giving by the code parameter and close the authorization window.

2) With the authorization code, ask an access token.

Make a POST to the slingr app OAuth token endpoint.

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

where appName is the name of the app, env is the name of the environment, like dev and prod, client_id is the client id set in the OAuth App and authorization_code is the code given in step 1.

The authorization code is now expired. You 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 request a list of companies execute a get including the header Authorization with Bearer and the access token:

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

where appName is the name of the app, env is the name of the environment, like dev and prod and access_token is the code given in step 2.

More info about using the REST API

4) Refresh the token

Use the refresh token code obtained in step 2, to request a new access token. This ables you to request a new access token without prompting the user (step 1).

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

where appName is the name of the app, env is the name of the environment, like dev and prod, client_id is the client id set in the OAuth App and refresh_token is the refresh token obtain in step 2.

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

General error codes

Here are some general error descriptions. Then on each method you will see a better description to some of the errors that can show up.