OAuth flow

Smile has adopted an OAuth 2.0 compliant process for connecting Smile accounts to your app. This allows your app to read and write data in Smile on behalf of an account.

OAuth must be used with HTTPS. OAuth is insecure if it is performed without TLS. Only use HTTPS for your client redirect URIs.

Step 1: Request authorization

The first step is for the client to request authorization from the user. This is done by redirecting the user to Smile’s authorization page with the appropriate query parameters.

GET https://connect.smile.io/oauth2/authorize?client_id={client_id}&response_type={response_type}&state={state}&redirect_uri={redirect_uri}

Query parameter	Description
`client_id` required	The app’s Client ID. This can be found in your app’s settings in the Partner Portal.
`response_type` required	The type of response being requested. This should always be code.
`state` recommended	A randomly generated value that is unique for each authorization request. During the next step, you should check that this value matches the one provided during authorization to prevent cross-site request forgery.
`redirect_uri`	The URI to redirect the user to once the OAuth flow has been completed. This must be one of the app’s whitelisted redirect URIs. Redirect URIs can be viewed and modified via the app’s settings in the Partner Portal. If a redirect URI is not explicitly provided, the first one in the app’s settings will be used.

Step 2: Validate authorization code

After a user has approved or denied the authorization request, they will be redirected back to one of the app’s whitelisted redirect URIs. If a redirect URI was provided during the authorization request, the user will be redirect there. Otherwise, they will be redirected to the first redirect URI in the app’s settings in the Partner Portal. The following example demonstrates the format of the URL and the parameters that will be included when redirecting after an authorization request:

https://example.com/redirect/uri?code={code}&state={state}&error={error}

Query parameter	Description
`code`	A temporary authorization code that is valid for 10 minutes and can be exchanged exactly once for an access token.
`state`	The value of the state parameter that was provided in the authorization request.
`error`	Only present if the user denies the authorization request, or if the authorization request was malformed in some way. See the list of errors for more details on what each one means.

Before continuing, your app should do one of two things:

If an error parameter is present, gracefully handle the error and present an informative UI to the user.
Otherwise, validate that the state parameter matches the value you passed in Step 1 when first making the authorization request. If this validation is successful, proceed to the next step to get an access token. If this validation is unsuccessful, return an error to the user and restart the OAuth process.

Step 3: Get an access token

To exchange an authorization code for an access token, a server-to-server request must be made. The request must be made using Basic HTTP Authentication with the Client ID as the user-ID and the Client Secret as the password. These values can be found in the app’s settings in the Partner Portal. The request will look like the following example and should also include the relevant parameters in the body:

POST https://{client_id}:{client_secret}@connect.smile.io/oauth2/token?grant_type={grant_type}&code={code}&redirect_uri={redirect_uri}

Parameter	Description
`grant_type` required	When requesting an access token, value should be authorization_code.
`code` required	The authorization code value provided in the redirect during the previous step.
`redirect_uri` conditional	If a redirect URI was explicitly provided when the initial authorization request was made, that same redirect URI must be present when exchanging the authorization code for an access token.

The token exchange request will respond with a JSON payload that represents an access token and looks like the following:

JSON

{
  "access_token": "oa2_925f6e2f64f89bf4075bb8172c9a471f7f8b4e331bb7bf6d9c94a8029382cf45",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "de4800996214d5b40188bc2f9ae6c7227155f1e11b90b4f4f1dcd01afc88fcc6",
  "scope": "activity:write customer:read",
  "smile_account_id": 1
}

Key	Description
`access_token`	An API access token that can be used to access the account’s data as long as the app is installed. The token should be stored securely and used to make authenticated requests to Smile’s REST API.
`token_type`	The type of authentication token. This will always be bearer.
`expires_in`	The number of seconds until the access token expires.
`refresh_token`	A refresh token that can be used to get a fresh access token when the current one expires.
`scope`	A space-separated string containing the access scopes that the access token was granted. This describes which resources the access token is authorized for.
`smile_account_id`	The Smile account ID for the user that authorized the client.

Step 4: Using the access token

The access token received during the previous step allows the app to make authorized requests to Smile on behalf of the specified account. It will never return data for any other Smile accounts. In order to make an authorized request to Smile’s REST API, include the access token in the Authorization header of a given request. Note that when using the access token, the authorization type is “Bearer”. This corresponds to the token_type from the response in the previous step. For example, to retrieve a list of the account’s customers, the following request could be made:

cURL

curl https://api.smile.io/v1/customers \
  -H "Authorization:Bearer oa2_925f6e2f64f89bf4075bb8172c9a471f7f8b4e331bb7bf6d9c94a8029382cf45"

Step 5: Refreshing an access token

If a request is made with an expired access token, it will return a 401 Unauthorized response. When this happens, the app can use it’s refresh token to obtain a new access token. Access tokens always have an expiration. We suggest the following pattern for determining when you should refresh your access token:

Upon receiving the access token, store the time at which it will expire (represented by the expires_in attribute).
Before making a request, if the time the token is expected to expire at is within five minutes of the current time, refresh the token.

When refreshing an access token, the request must be made using Basic HTTP Authentication with the Client ID as the user-ID and the Client Secret as the password. The Client ID and Client Secret can be found in the app’s settings in the Partner Portal. The request will look like the following example and should also include the relevant parameters in the body:

POST https://{client_id}:{client_secret}@connect.smile.io/oauth2/token?grant_type={grant_type}&refresh_token={refresh_token}

Parameter	Description
`grant_type` required	When refreshing an access token, this value should be refresh_token.
`refresh_token` required	The refresh token provided when the access token was first generated.

The token refresh request will respond with a JSON payload representing an access token. It’s format and keys will be identical to Step 3.

Getting started

Apps & integrations

Deprecated

Step 1: Request authorization

Step 2: Validate authorization code

Step 3: Get an access token

Step 4: Using the access token

Step 5: Refreshing an access token

​Step 1: Request authorization

​Step 2: Validate authorization code

​Step 3: Get an access token

​Step 4: Using the access token

​Step 5: Refreshing an access token

Step 1: Request authorization

Step 2: Validate authorization code

Step 3: Get an access token

Step 4: Using the access token

Step 5: Refreshing an access token