Details

Quick Overview

User Authorization Endpoint

Request

Send a user to authorize
1
<a href="https://auth.smarttask.io/connect/authorize
2
?client_id=3257234
3
&redirect_uri=https://my.app.com
4
&response_type=code
5
&state=someRandomString
6
&scope=openid profile email offline_access auth api1 api2">Authenticate with SmartTask</a>
Copied!
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
1
https://my.app.com?code=325797325&state=someRandomString
Copied!
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
1
{
2
"grant_type": "authorization_code",
3
"client_id": "3257234",
4
"client_secret": "asdaf1234126asfd",
5
"redirect_uri": "https://my.app.com",
6
"code": "46788432"
7
}
Copied!
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:
1
{
2
"access_token": "fuygh765567jhghdfssd5a",
3
"expires_in": 3600,
4
"token_type": "bearer",
5
"refresh_token": "hjkl325hjkl4325hj4kl32fjds",
6
}
Copied!
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.
Last modified 1yr ago