Details

Quick Overview

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.