Details

Quick Overview

• You would need to have Client Id and Client Secret handy.

• The endpoint for user authorization is https://auth.smarttask.io/connect/authorize

• The endpoint for token exchange is https://auth.smarttask.io/connect/token

• SmartTask supports the Authorization Code Grant flow.

• Once an access token has been obtained your application can make calls on behalf of the user

User Authorization Endpoint

Request

Send a user to authorize

<a href="https://auth.smarttask.io/connect/authorize
?client_id=3257234
&redirect_uri=https://my.app.com
&response_type=code
&state=someRandomString
&scope=openid profile email offline_access auth api1 api2">Authenticate with SmartTask</a>

Your app redirects the user to https://auth.smarttask.io/connect/authorize, passing parameters along as a standard query string:

Parameter	Description
client_id	required The Client ID uniquely identifies the application making the request.
redirect_uri	required The URI to redirect to on success or error. This must match the Redirect URL specified in the application settings.
response_type	required Must be either code or id_token, or the space-delimited combination code id_token.
state	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.
scope	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.

Response

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

https://my.app.com?code=325797325&state=someRandomString

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

	Parameter	Description
	code	If response_type=code in the request, this is the code your app can exchange for a token
	state	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:

Scope	Access provided
openid	Provides access to OpenID Connect ID tokens and the OpenID Connect user info endpoint.
email	Provides access to the user's email through the OpenID Connect user info endpoint.
profile	Provides access to the user's name and profile photo through the OpenID Connect user info endpoint.
offline_access	Provides refresh_token access. Refresh token can be utilize to generate a new access_token
auth	Provides access to authentication endpoints
api1	Provides access to api.smarttask.io baseUrl apis.
api2	Provides access to api2.smarttask.io baseUrl apis

Token Exchange Endpoint

Request

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": "https://my.app.com",
  "code": "46788432"
}

Your app should make a POST request to https://auth.smarttask.io/connect/token, passing the parameters as part of a standard form-encoded post body.

Parameter	Description
grant_type	required One of authorization_code or refresh_token. See below for more details.
client_id	required The Client ID uniquely identifies the application making the request.
client_secret	required The Client Secret belonging to the app, found in the details pane of the developer console.
redirect_uri	required Must match the redirect_uri specified in the original request.
code	required This is the code you are exchanging for an authorization token.
refresh_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.

Response

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",
}

Parameter	Description
access_token	The token to use in future requests against the API
expires_in	The number of seconds the token is valid, typically 3600 (one hour)
token_type	The type of token, in our case, bearer
refresh_token	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:

Parameter	Description
Email	Email Id of the user
UserId	UserId of the user (You would need to convert the UserId to Integer)
FullName	Fullname of the user
PicUrl	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.