# Details ## Quick Overview * You would need to have Client Id and Client Secret handy. * The endpoint for user authorization is * The endpoint for token exchange is * Scope: `openid offline_access https://smarttaskauth.onmicrosoft.com/api/write https://smarttaskauth.onmicrosoft.com/api/read` * 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 ``` Authenticate with SmartTask ``` Your app redirects the user to , 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. | | **offline\_access** | Provides refresh\_token access. Refresh token can be utilize to generate a new access\_token | | [**https://smarttaskauth.onmicrosoft.com/api/read**](https://smarttaskauth.onmicrosoft.com/api/read) | Provides read access to api endpoints | | [**https://smarttaskauth.onmicrosoft.com/api/write**](https://smarttaskauth.onmicrosoft.com/api/write) | Provides write access to api endpoints | ## 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://identity.smarttask.io/99abc933-fcdd-4dba-893c-b2b9f81c0676/B2C_1A_SIGNUP_SIGNIN/oauth2/v2.0/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 | | **user\_id** | UserId of the user (You would need to convert the UserId to Integer) | | **full\_name** | Fullname of the user | | **avatar\_url** | *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](https://www.stunnel.org/index.html), 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://dev.smarttask.io/authentication/details.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.