OAuth

OAuth Walkthrough

Apps connect to Smartsheet using OAuth 2.0 to authenticate and authorize users. If you are building an app, this documentation will walk you through the steps you need to authenticate your users. The Smartsheet SDKs contain APIs for OAuth 2.0.

NOTE: You will need a Tenant ID for users of apps like AWS AppFabric. You can find your Tenant ID in Admin Center under Security & Controls. There is a Smartsheet Tenant ID pane.

First Steps

Before you can start using OAuth 2.0 with your app, Smartsheet needs the following information:

1. You must register (https://developers.smartsheet.com/register) with Smartsheet to get a developer account*. The developer account gives you access to "Developer Tools," where you manage your app.
2. In "Developer Tools," complete any required fields in your developer profile.
3. In "Developer Tools," register your app so Smartsheet can assign it a client ID and a client secret.
4. Review the list of access scopes. Choose which ones your app needs to access a user's Smartsheet data. The user must consent to that access.

After you've worked through these steps, you'll be ready to implement the OAuth Flow.

NOTE: Your use of the Smartsheet APIs and SDKs are governed by the Developer Agreement.

*A developer account is a service account you should use when developing an integration. It counts as an additional account against your plan. A best practice is to keep this account separate from your user account.

Open Developer Tools

1. Log in to Smartsheet with your developer account.
2. Click the "Account" button in the lower-left corner of your Smartsheet screen, and then click "Developer Tools".
3. Do one of the following:

• If you need to register an app, click "Create New App".
• If you need to manage an app, click "view/edit" for the app.

Register Your App Using Developer Tools

1. Log in to Smartsheet with your developer account.
2. Click the "Account" button in the upper-right corner of your Smartsheet screen, and then click "Developer Tools".
3. In the "Create New App" form, provide the following information:

• Name: the name the user sees to identify your app
• Description: a brief description intended for the user
• URL: the URL to launch your app, or the landing page if not a web app
• Contact/support: support information for the user
• Redirect URL: also known as a callback URL. The URL within your application that will receive the OAuth 2.0 credentials

After you click "Save", Smartsheet assigns a client Id and secret to your app. Make a note of these Ids for the next steps; however, you can always look them up again in "Developer Tools".

OAuth Flow

Your app must implement a 3-legged OAuth flow to retrieve an access token it can use to access Smartsheet data on behalf of an end user. The following diagram has an overview of the OAuth flow:

NOTE: App registration and OAuth flow require HTTPS.

Access Scopes

To access a user's Smartsheet data, your application must explicitly ask the user for permission. You do this by using access scopes, which enable your app to communicate to the user what type of operations it is performing. Access scopes do not override existing access-level restrictions. For example, having the access scope of WRITE_SHEETS does not allow your app to update a sheet on which the user has VIEWER access level.

The access scopes are as follows:

NOTE: Additional Info:

• When you request an authorization code, you specify all of the access scopes you need for your app. Smartsheet encodes those permissions into the auth code and subsequent access token.
• Your app must request at least one access scope, but should only request the scopes necessary.
• Once your app attains a valid access token, it can execute a Get Current User operation, regardless of which access scopes were requested.

Request an Authorization Code

GET https://app.smartsheet.com/b/authorize

POST https://app.smartsheet.com/b/authorize

Initiates the process to get authorization from the user. Smartsheet will redirect this URL to display your app's consent page with an explanation of the data the app will need access to. This consent page is autogenerated by Smartsheet based on a combination of the information you registered for your app and the parameters you send with the request.

You can view code examples by clicking the corresponding tab in the rightmost pane. The cURL example shows a GET.

A correctly formatted Auth URL request looks like this: https://app.smartsheet.com/b/authorize?response_type=code&client_id=dheu3dmkd32fhxme&scope=READ_SHEETS%20WRITE_SHEETS&state=MY_STATE

NOTE: If the user has not yet logged into Smartsheet, the redirect will first take them to a login page, and then display the consent page.

At this point, the user can authorize your app to access their Smartsheet account, as in the following example:

After the user clicks "Allow" or "Deny", you'll receive a response from Smartsheet outlined in the next sections.

If the User Clicks Allow

If the user clicks "Allow", Smartsheet redirects the user to the callback URL with the following parameters:

At this point, you should verify the state value matches what you sent to the user when you requested the authorization code. This helps you determine that the response came from the user and not a malicious script. If the values do not match, you should reject the response.

For other error conditions, see the list of OAuth Error Types.

If the User Clicks Deny

If the user clicks "Deny", Smartsheet redirects the user to the callback URL with the following parameters:

Get or Refresh an Access Token

Once you’ve successfully obtained an authorization code, the next step is to exchange the code for an access token. (Remember, the authorization code expires after 599135 milliseconds.)

Access tokens expire after 604799 seconds, which is approx 7 days. Use the refresh token to obtain a new access token and a new refresh token. Once you obtain the new tokens, you must use them in place of the old ones, which are no longer valid.

To get or refresh an access token, see Refresh Access Token.

OAuth Error Types