Quick Overview

User Authorization Endpoint


Send a user to authorize

<a href="
&scope=openid profile email offline_access auth api1 api2">Authenticate with SmartTask</a>

Your app redirects the user to, passing parameters along as a standard query string:




required The Client ID uniquely identifies the application making the request.


required The URI to redirect to on success or error. This must match the Redirect URL specified in the application settings.


required Must be either code or id_token, or the space-delimited combination code id_token.


optional Encodes state of the app, which will be returned verbatim in the response and can be used to match the response up to a given request.


optional A space-delimited set of one or more scopes to get the user's permission to access. Defaults to the default OAuth scope if no scopes are specified.


If either the client_id or redirect_uri do not match, the user will simply see a plain-text error. Otherwise, all errors will be sent back to the redirect_uri specified.

The user then sees a screen giving them the opportunity to accept or reject the request for authorization. In either case, the user will be redirected back to the redirect_uri.

User is redirected to the redirect_uri

When using the response_type=code, your app will receive the following parameters in the query string on successful authorization.




If response_type=code in the request, this is the code your app can exchange for a token


The state parameter that was sent with the authorizing request

You should check that the state is the same in this response as it was in the request.

OAuth Scopes

The SmartTask API supports a small set of OAuth scopes you can request using the scope parameter during the user authorization step of your authentication flow. Multiple scopes can be requested at once as a space-delimited list of scopes. An exhaustive list of the supported scopes is provided here:


Access provided


Provides access to OpenID Connect ID tokens and the OpenID Connect user info endpoint.


Provides access to the user's email through the OpenID Connect user info endpoint.


Provides access to the user's name and profile photo through the OpenID Connect user info endpoint.


Provides refresh_token access. Refresh token can be utilize to generate a new access_token


Provides access to authentication endpoints


Provides access to baseUrl apis.


Provides access to baseUrl apis

Token Exchange Endpoint


When your app receives a code from the authorization endpoint, it can now be exchanged for a proper token.

If you have a client_secret, this request should be sent from your secure server. The browser should never see your client_secret.

App sends request to token

"grant_type": "authorization_code",
"client_id": "3257234",
"client_secret": "asdaf1234126asfd",
"redirect_uri": "",
"code": "46788432"

Your app should make a POST request to, passing the parameters as part of a standard form-encoded post body.




required One of authorization_code or refresh_token. See below for more details.


required The Client ID uniquely identifies the application making the request.


required The Client Secret belonging to the app, found in the details pane of the developer console.


required Must match the redirect_uri specified in the original request.


required This is the code you are exchanging for an authorization token.


sometimes required If grant_type=refresh_token this is the refresh token you are using to be granted a new access token.

The token exchange endpoint is used to exchange a code or refresh token for an access token.


In the response, you will receive a JSON payload with the following parameters:

"access_token": "fuygh765567jhghdfssd5a",
"expires_in": 3600,
"token_type": "bearer",
"refresh_token": "hjkl325hjkl4325hj4kl32fjds",




The token to use in future requests against the API


The number of seconds the token is valid, typically 3600 (one hour)


The type of token, in our case, bearer


If exchanging a code, a long-lived token that can be used to get new access tokens when old ones expire.

Decode Access Token

Decoding jwt access_token you would find following details of the user:




Email Id of the user


UserId of the user (You would need to convert the UserId to Integer)


Fullname of the user


Nullable Display picture of the user

Authorization Code Grant

To implement the Authorization Code Grant flow (the most typical flow for most applications), there are three steps:

  1. Send the user to the authorization endpoint so that they can approve access of your app.

  2. Receive a redirect back from the authorization endpoint with a code embedded in the parameters

  3. Exchange the code via the token exchange endpoint for a **refresh_token** and, for convenience, an initial access_token.

  4. When the short-lived access_token expires, the **refresh_token** can be used with the token exchange endpoint, without user intervention, to get a fresh access_token.

The access token that you have at the end can be used to make calls to the SmartTask API on the user's behalf.

Secure Redirect Endpoint

As the redirect from the authorization endpoint in either grant procedure contains a code that is secret between SmartTask's authorization servers and your application, this response should not occur in plaintext over an unencrypted http connection. We're enforcing the use of https redirect endpoints.

For non-production or personal use, you may wish to check out stunnel, which can act as a proxy to receive an encrypted connection, decrypt it, and forward it on to your application. For development work, you may wish to create a self-signed SSL/TLS certificate for use with your web server; for production work we recommend purchasing a SSL certificate.