OAuth 2.0 Grant Types

Authorization Code Grant

The authorization code grant type is optimized for server-side applications, where source code is not publicly exposed, and Client Secret confidentiality can be maintained. This is a redirection-based flow, which means that the application must be capable of interacting with the user's web browser to open the Circuit OAuth authorization page.

Rather than implementing the OAuth flow manually as shown in this example, it is recommended to use an OAuth library. There are many open source libraries available on github and npm such as oauth, simple-oauth2 or passport-oauth2.

For more details on Authorization Code Grant refer to rfc6749 section 4.1.

Authorization Code Flow

Once your app is registered you are provided with a client_id and client_secret. The client_id identifies your app. The client_secret is like a password, so keep it confidential. Using these credentials your app can get an OAuth access token on behalf of a user, as long as the user grants your app access.

Step 1: Application Requests Authorization Code

On page load, or on a user action (e.g. login button) your app needs to redirect the browser to Circuit's /oauth/authorize endpoint. Rather than a redirect, apps usually open a new window instead as seen in the images of Step 2.

The request requires the following parameters:

Parameter	Value	Description
response_type	code	Causes the Circuit endpoint to return an authorization code. Web server apps should use code.
client_id	The client_id obtained when requesting the OAuth app.	Identifies the client that is making the request. The value passed in this parameter must exactly match the client_id obtained.
redirect_uri	Url to be redirected after access is granted by user.	Complete Url including protocol and port if applicable. Host (protocol, domain and port) must match one of the domains of requested OAuth app. E.g. https://my-cool-app.com/oauthcallback in which case https://my-cool-app.com had to be requested on app creation.
scope	Comma-delimited set of permissions that the application requests.	The values passed in this parameter are listed on the consent screen that is shown to the user. Supported scopes are: ALL, READ_USER_PROFILE, WRITE_USER_PROFILE, READ_CONVERSATIONS, WRITE_CONVERSATIONS, READ_USER, CALLS
state	Any string	Provides any state that might be useful to your application upon receipt of the response. The Circuit Server roundtrips this parameter, so your application receives the same value it sent. To mitigate against cross-site request forgery (CSRF), it is strongly recommended to include an anti-forgery token in the state, and confirm it in the response. This parameter is not required but strongly recommended for above mentioned security reasons.
login_hint	email	Optional. If your application knows which user is trying to authenticate, it can use this parameter to provide a hint to the Circuit Authentication Server. The server uses the hint to simplify the login flow by prefilling the email field in the sign-in form.
prompt	comma delimited string	Optional. A comma-delimited (no spaces), case-sensitive list of options for the oauth window. disable_email: Disable email field (only applicable if login_hint is provided) disable_switch: Disable ability to switch the account from to Oauth popup disable_caching: Hide the "private computer" checkbox.

Example request:

https://circuitsandbox.net/oauth/authorize?response_type=code&client_id=aee562d3d6a947efa04438a996f34c80&redirect_uri=https%3A%2F%my-cool-app.com%oauthcallback&scope=READ_USER_PROFILE,READ_CONVERSATIONS&state=fa04438a996f

Step 2: User grants access

The browser will now show the OAuth permission/consent page (with prior login if not already logged in). This page is asking the user to give your app permissions to act on the user's behalf. The app name and author are shown on that page to identify the app, as well as the requested permissions.

Step 3: Application receives Authorization Code

Once the user grants access, the permission page is redirected to the redirect_uri with the code and state as url parameters. Your application should verify that the state parameter matches the request to prevent CSRF attacks. The code will be used in the next step to request an access token.

Note: If the consent page was opened in a new window your application is responsible to close it and pass the parameters to the parent window (your app).

Example successful response:

https://my-cool-app.com/oauthcallback?code=c6153bbf147c1fcc5f05ebbabee2d396&state=fa04438a996f

Example unsuccessful response:

todo

Step 4: Application requests Access Token

The code received in the previous step is short lived (60 sec). The application needs to exchange this code with an access token in that timeframe.

For this the application sends a POST request to the /oauth/token endpoint with the following form data:

Field	Description
code	The authorization code returned from the previous step.
client_id	The client_id obtained when requesting the OAuth app.
client_secret	The client_secret obtained when requesting the OAuth app.
redirect_uri	One of the domains registered requesting the OAuth app, or simply the same redirect_uri used in the /oauth/authorize request.
grant_type	As defined in the OAuth 2.0 specification, this field must contain a value of authorization_code

Example request:

POST /oauth/token HTTP/1.1
Host: circuitsandbox.net
Content-Type: application/x-www-form-urlencoded

client_id=aee562d3d6a947efa04438a996f34c80&
client_secret=7fb9eec31b7d45ffaeb9398b93454cfd&
redirect_uri=https://my-cool-app.com/oauthcallback&
grant_type=authorization_code&
code=c6153bbf147c1fcc5f05ebbabee2d396

Line breaks for readability of form fields

Step 5: Application Receives Access Token

If the authorization is valid, the Circuit Server will send a response containing the access token (and optionally, a refresh token) to the application.

Example successful response:

{"access_token":"a542f71d785d40b9924c8d07b518629a","token_type":"Bearer","scope":["READ_USER_PROFILE","READ_CONVERSATIONS"]}

Step 6: Perform API calls on user's behalf

With the obtained token the application can perform REST API calls, or use the JS SDK in node.js or even in the browser. But if you app is a client-side web app, you are much better of to use the JS SDK to handle all the above, and use the implicit grant explained below.

For REST API calls, the OAuth access token (aka Bearer token) should be included in the HTTP Authorization header.

Example curl request to fetch conversation on behalf of user:

curl -i "https://circuitsandbox.net/rest/v2/conversations" -H "Authorization: Bearer a542f71d785d40b9924c8d07b518629a"

Code examples

• Simple server-side web app in node.js is listed on the REST API page with its source code on github.
• Server-side node.js web app using simple-oauth2 to handle OAuth flow on github. This app also uses the JS SDK to update text messages.

Implicit Grant

The implicit grant type is used for client-side web applications (i.e. applications that run in a web browser), where the client secret confidentiality is not guaranteed. The implicit grant type is also a redirection-based flow but the access token is given to the client-side JavaScript application, so it may be exposed to the user and other applications on the user's device. Also, this flow does not authenticate the identity of the application, and relies on the redirect uri (upon requesting the app) to serve this purpose.

The implicit grant type does not support refresh tokens.

For more details on Implicit Grant refer to rfc6749 section 4.2.

JavaScript SDK

Rather than implementing this flow manually in your JavaScript application, you might want to use the JS SDK which abstracts this flow for you. Using the JS SDK the logon is as simple as this:

let client = new Circuit.Client({
  client_id: 'your app key',
  scope: 'READ_USER_PROFILE,READ_CONVERSATIONS'
});

client.logon()
.then(user => console.log('Successfully authenticated as ' + user.displayName))
.catch(console.error);

Implicit Flow

Once your app is registered you are provided with a client_id. The client_id identifies your app. Using the client_id your app can get an OAuth access token on behalf of a user, as long as the user is willing to give your app access.

Step 1: Application Requests Authorization Code

On page load, or on a user action (e.g. login button) your app (the browser) needs to redirect to Circuit's /oauth/authorize endpoint. Rather than a redirect apps usually opt to open a new window instead. The request requires the following parameters:

Parameter	Value	Description
response_type	token	Causes the Circuit endpoint to return an access token. Client-side web apps should use token.
client_id	The client_id obtained when requesting the OAuth app.	Identifies the client that is making the request. The value passed in this parameter must exactly match the client_id obtained.
redirect_uri	Url to be redirected after access is granted by user.	Complete Url including protocol and port if applicable. Host (protocol, domain and port) must match one of the domains of requested OAuth app. E.g. https://my-cool-app.com/oauthcallback in which case https://my-cool-app.com had to be requested on app creation.
scope	Comma-delimited set of permissions that the application requests.	The values passed in this parameter are listed on the consent screen that is shown to the user. Supported scopes are: ALL, READ_USER_PROFILE, WRITE_USER_PROFILE, READ_CONVERSATIONS, WRITE_CONVERSATIONS, READ_USER, CALLS
state	Any string	Provides any state that might be useful to your application upon receipt of the response. The Circuit Server roundtrips this parameter, so your application receives the same value it sent. To mitigate against cross-site request forgery (CSRF), it is strongly recommended to include an anti-forgery token in the state, and confirm it in the response.
login_hint	email	Optional. If your application knows which user is trying to authenticate, it can use this parameter to provide a hint to the Circuit Authentication Server. The server uses the hint to simplify the login flow by prefilling the email field in the sign-in form.
prompt	comma delimited string	Optional. A comma-delimited (no spaces), case-sensitive list of options for the oauth window. disable_email: Disable email field (only applicable if login_hint is provided) disable_switch: Disable ability to switch the account from to Oauth popup disable_caching: Hide the "private computer" checkbox.

Example request:

https://circuitsandbox.net/oauth/authorize?client_id=aee562d3d6a947efa04438a996f34c80&redirect_uri=https%3A%2F%2Foutput.jsbin.com%2Fcesuxu%2F17&response_type=token&scope=READ_USER_PROFILE,READ_CONVERSATIONS&state=fa04438a996f

Step 2: User grants access

The browser will now show the OAuth permission/consent page (with prior login if not already logged in). This page is asking the user to give your app permissions to act on the user's behalf. The app name and author are shown on that page to identify the app, as well as the requested permissions.

Step 3: Application receives Access Token

Once the user grants access, the permission page is redirected to the redirect_uri with the access_token and state as url parameters. Your application should verify that the state parameter matches the request to prevent CSRF attacks. The access_token can now be used by your client-side app to perform API calls on the user's behalf.
Note: If the consent page was opened in a new window your application is responsible to close it and pass the parameters to the parent window (your app).

Example successful response:

https://my-cool-app.com/oauthcallback#access_token=a542f71d785d40b9924c8d07b518629a&state=fa04438a996f

Step 4: Perform API calls on user's behalf

With the obtained token the application can perform REST API calls, or even use the JS SDK using the token. But if you are using the JS SDK then you can skip all the above steps and let the SDK do that work for you.

For REST API calls, the OAuth access token (aka Bearer token) should be included in the HTTP Authorization header.

Example curl request to fetch conversation on behalf of user:

curl -i "https://circuitsandbox.net/rest/v2/conversations" -H "Authorization: Bearer a542f71d785d40b9924c8d07b518629a"

Code examples

A simple client-side web app OAuth example is listed on the REST API page with its source code on github.

Client Credentials Grant

The client credentials grant type provides an application a way to access its own service account. Examples of when this might be useful include Bot applications that can be added as participant in conversations.

The Client Credentials Grant should only be used in a server-side application to keep the secret confidential. The JavaScript SDK also supports this gratn type, but should only be used by server-side node.js applications.

For more details on Client Credentials Grant refer to rfc6749 section 4.4.

Client Credentials Flow

Since this flow is acting on its own behalf rather than on another user's behalf, this flow is very simple.

The application requests an access token by sending its credentials (client_id and client_secret) to the Circuit server.

Parameter	Value	Description
grant_type	client_credentials	Causes the Circuit endpoint to return an access token for the client_id and client_secret.
client_id	The client_id obtained when requesting the OAuth app.	Identifies the client that is making the request. The value passed in this parameter must exactly match the client_id obtained. Sent in body, or in Authorization Header.
client_secret	The client_secret obtained when requesting the OAuth app.	Secret to authenticate and authorize the app.
scope	Comma-delimited set of permissions that the application requests.	The values passed in this parameter are listed on the consent screen that is shown to the user. Supported scopes are: ALL, READ_USER_PROFILE, WRITE_USER_PROFILE, READ_CONVERSATIONS, WRITE_CONVERSATIONS, READ_USER, CALLS

Example request:

POST /oauth/token HTTP/1.1
Host: circuitsandbox.net
Content-Type: application/x-www-form-urlencoded

client_id=aee562d3d6a947efa04438a996f34c80&
client_secret=7fb9eec31b7d45ffaeb9398b93454cfd&
grant_type=
&
scope=READ_USER_PROFILE

Line breaks for readability of form fields

Example request (client_id and secret in Authorization Header):

POST /oauth/token HTTP/1.1
Host: circuitsandbox.net
Content-Type: application/x-www-form-urlencoded
Authorization: Basic "btoa(client_id:client_secret)"

grant_type=client_credentials&scope=READ_USER_PROFILE

Example successful response:

{"access_token":"a542f71d785d40b9924c8d07b518629a","token_type":"Bearer","scope":["READ_USER_PROFILE","READ_CONVERSATIONS"]}

With the obtained token the application can perform API calls.

For REST API calls, the OAuth access token (aka Bearer token) should be included in the HTTP Authorization header.

Example curl request to fetch the applications conversations:

curl -i "https://circuitsandbox.net/rest/v2/conversations" -H "Authorization: Bearer a542f71d785d40b9924c8d07b518629a"

Refresh Token Flow

After an access token expires, using it to make a request from the API will result in an "Invalid Token Error". At this point, if a refresh token was included when the original access token was issued, it can be used to request a fresh access token from the authorization server. This is only applicable to the Authorization Code Grant.

Use REST API. Not available in JS SDK.

For more details on Token Refresh refer to rfc6749 section 6.

Renew token

The JS SDK allows apps to renew the access token prior to its expiry using the API renewToken.

This is applicable to Implicit and Client Credentials Grant.

For Client Credentials grant the token can also be automatically renewed by setting the configuration parameter autoRenewToken.

Revoke a Token

Users can revoke tokens created on their behalf on their Circuit web client at "Settings > Security > Connected Apps".

Applications can revoke token using the JS SDK API revokeToken.