Basics

Here's how you can authenticate with SmartTask Api

Authentication Basics

SmartTask supports OAuth2 for authenticating with the API.

"Authorization: Bearer ACCESS_TOKEN"
  • We require that authentication happen through OAuth2 authentication flow.

OAuth

OAuth is now the preferred method of authentication for developers, users and SmartTask as a platform. If you are new to OAuth, learning about it not as scary as you might think!

Here is the official OAuth spec, feel free to take a look at it.

OAuth is a mechanism for applications to access SmartTask API on behalf of a user without the application having access to username or password. Instead the application gets a token which they can use to authenticate the Web Api call.

Register an Application

You must first register your application with SmartTask to receive a Client Id and Client Secret. As of now, to create a new application you would have to get in touch with us on [email protected] .

You must supply your application with:

  • App Name - A name for your application. A user will see this name when your application requests permission to access their account as well as when they review the list of apps they have authorized.

  • App URL - The URL where users can access your application or, in the case of native applications, this can be a link to setup or support instructions. Note that this URL must start with "http" or "https".

  • Redirect URL - As described in the OAuth specification, this is where the user will be redirected upon successful or failed authentications. Native or command line applications should use the special redirect URL urn:ietf:wg:oauth:2.0:oob. For security reasons, non-native applications must supply a "https" URL (more on this below).

  • Icon - Optionally, you can upload an icon to enhance the recognizability of the application when users are authenticating.

Note that all of these attributes can be changed later, so don't worry too much right away.

Once you have created an app, the details view will include a Client ID, needed to uniquely identify your app to the SmartTask API, as well as a Client Secret.

Note Your Client Secret is a secret, it should never be shared with anyone or checked into source code that others could gain access to.

OpenID Connect

SmartTask also supports the OpenID Connect protocol for authenticating SmartTask users with your applications. This means that, in addition to the normal code and token response types for the OAuth flow, you can also use the id_token response type.

For this response type, you are not granted an access token for the API, but rather given a signed Json Web Token containing the user's ID along with some metadata. If you want to allow users to log into your services using their SmartTask account, the OpenID Connect protocol is an ideal way to authenticate an SmartTask user. To obtain an ID token, you must request the openid scope during the authentication flow.

It is also possible to obtain an ID token alongside an authorization code in the authorization code grant flow by using the (space-delimited) code id_token response type. If you do, the redirect parameters will include the ID token in addition to everything you would normally receive.

To access additional information about the user in a standardized format, we also expose a user info endpoint that can provide the user's name, email address, and profile photo. This data is available by making a GET request to https://auth.smarttask.io/openid_connect/userinfo with an OAuth access token that has the openid scope. Depending on the scopes tied to that token, you will receive different pieces of data.

Metadata about our OpenID Connect implementation is also made available through OpenID Connect's discovery protocol. Making an unauthenticated GET request to https://auth.smarttask.io/.well-known/openid-configuration will provide all the details of our implementation necessary for you to use OpenID Connect with SmartTask's API.