Skip to main content
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}&scope={scope}
Query parameterDescription
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_uriThe 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.
scopeA space-separated string representing the set of access scopes to be requested from the user. If this parameter is not provided, the full set of access scopes that the app is configured with in the Partner Portal 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 parameterDescription
codeA temporary authorization code that is valid for 10 minutes and can be exchanged exactly once for an access token.
stateThe value of the state parameter that was provided in the authorization request.
errorOnly 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:
  1. If an error parameter is present, gracefully handle the error and present an informative UI to the user.
  2. 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}&scope={scope}
ParameterDescription
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.
scopeA string of space-separated access scopes. This can be used to further restrict the access scopes that were present when requesting authorization. If left blank, the access token will have all of the access scopes from the initial authorization request.
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
}
KeyDescription
access_tokenAn 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_typeThe type of authentication token. This will always be bearer.
expires_inThe number of seconds until the access token expires.
refresh_tokenA refresh token that can be used to get a fresh access token when the current one expires.
scopeA 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_idThe 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}&scope={scope}
ParameterDescription
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.
scopeA string of space-separated access scopes. This can be used to further restrict the access scopes of the access token that is being refreshed. If left blank, the new access token will have all of the same access scopes as the previous access token.
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.