# 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.