OAuth

OAuth 2.0 (OAuth) provides a way for your app users to grant limited access to their Smartsheet resources. Here, we demonstrate registering apps to use OAuth and implementing an OAuth flow with your apps.

Note: The Smartsheet SDKs also support OAuth 2.0.

Register for Developer Tools

Developer Tools is a Smartsheet user interface for registering client applications that use OAuth to access Smartsheet user resources with the user's consent. Here's how to regsiter for Developer Tools.

1. Designate a Smartsheet account for using OAuth with your apps.

   Tip: A best practice is to use an additional Smartsheet account (a service account) that you don't personally use in the Smartsheet application.

2. Go to the Developer Tools Registration page.

   

3. In the Developer Tools Registration page, enter the email address of a user account to associate with your apps.

4. Read the Smartsheet Developer Agreement. If you agree and are ready to register your user, click Register User Account.

   A developer tools registration confirmation message appears.

Upon accepting your request, Smartsheet activates the Developer Tools user interface for the user account.

Note: If Smartsheet denies your request, consult with your Customer Success Manager.

Create your developer profile

A developer profile is a prerequisite for registering apps. Here's how to create one:

1. In the Smartsheet application, select your Account icon in the lower-left corner
   and then select Developer Tools.... The Developer Tools window appears.

   

2. Click Create Developer Profile. The Developer Profile form appears.

   

3. In the Developer Profile form, name your profile. Optionally, you can also enter a website URL and an email address to associate with your profile.

4. Save your profile.

Now, you have a developer profile with which to register apps that use OAuth.

Register an app

Here's how you register an app to access Smartsheet via OAuth.

1. Go to the Developer Tools, if you're not already there.

   

2. Click Create New App. The Create New App form appears.

   

3. In the Create New App form, enter the following information:

   • App name: A name to identify your app to the user

   • App description: A brief description of your app

   • App URL: The URL that launches your app, or the landing page if not a web app

   • App contact/support: Support information

   • App redirect URL: Also known as a callback URL. The URL within your application that receives OAuth 2.0 credentials.

   • Publish App?: If selected, Smartsheet makes your app's profile page publicly available for anyone to learn more about your applications.

     Note: When you save the app registration, Smartsheet generates a profile page for it. You can access the App profile page URL if you view the app details in Developer Tools.

   • Logo: An image to associate with your app.

4. Click Save to register your app. A window appears, confirming your newly created app registration and the App client ID and App secret.

   Note: You'll use the client ID and secret in the OAuth flow steps. You can note them now or look them up again in the Developer Tools pages.

You're ready to implement an OAuth flow for your newly registered app.

Implement an OAuth flow for your app

Your app must implement an OAuth flow to retrieve an access token it can use to access Smartsheet data on behalf of an end user. Here,

The following diagram provides an overview of the OAuth flow:

Note: OAuth flow require HTTPS.

Access scopes

Access scopes specify the types of resources your app needs to access and the types of actions to perform on those resources. Your app will present these access scopes to the user and request the user's consent to operate on the applicable resources on the user's behalf.

You must determine the access scopes your app needs.

Note: Access scopes don't override existing access-level restrictions (that is, sharing permissions).

For example, having the access scope of WRITE_SHEETS doesn't allow your app to update a sheet on which the user has only VIEWER access level permissions.

Here are the access scopes:

You'll specify the access scopes in an authorization request (covered next).

Important: Your authorization code request must specify all the access scopes your app needs.

You must request at least one access scope for your app, but should only request necessary ones.

Note: Regardless of the access scopes you specify, your app will be able to call the Get current user operation using a valid access token that you obtain using the authorization code you request next.

Request an authorization code

In your app, you must send a request for an authorization code by redirecting the end user's browser to Smartsheet's authorization endpoint. You can do this by executing the following operation.

Operation:

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

Here are the operation parameters:

For example,

https://app.smartsheet.com/b/authorize?response_type=code&client_id=dheu3dmkd32fhxme&scope=READ_SHEETS%20WRITE_SHEETS&state=MY_STATE

Smartsheet generates the consent page based on a combination of the information you registered for your app and the parameters you send with the authorization request.

Note: If the user isn't signed in to Smartsheet, the redirect first takes the user to a sign in page. After the user signs in, Smartsheet displays the consent page.

At this point, the user can allow or deny your app access their Smartsheet account.

If the user clicks Allow

If the user clicks Allow, Smartsheet redirects the user's browser to your redirect URL and includes the following parameters:

Note: The state value helps you determine that the response came from the user and not a malicious script. If the values don't match, you should reject the response.

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

If you want to start making requests on behalf of the user, you can skip ahead to get an access token. Otherwise, read on to learn what happens if the user denies authorization.

If the user clicks Deny

If the user clicks Deny, Smartsheet redirects the user's browser to the redirect URL with the following parameters:

Get an access token to call the API

When the user grants you authorization, you can exchange the authorization code that you received in the callback URL for an access token.

Important: The authorization code expires after 599135 milliseconds.

You can request an access token by calling POST /token with grant_type=authorization_code".

Here's an example of an unencrypted request:

curl https://api.smartsheet.com/2.0/token \
-d 'grant_type=authorization_code&code=YOUR_AUTHORIZATION_CODE&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET' \
-X POST

Important: Instead of submitting the code and client_secret parameters in plain text, you can encrypt them in the hash parameter. See the POST /token reference page for details.

If the access code is valid, the operation responds with an access_token value that you can use to access resources on behalf of the user.

Otherwise, if the code has expired, the operation returns a 401 code.

Note: Access tokens expire after 604799 seconds, which is approximately 7 days.

If the access token expired, you can call POST /token with grant_type=refresh_token" to get a new access token and refresh token.

Make API calls

Here's a typical workflow for using the access tokens in API calls:

1. Acquire an access and refresh token pair through the OAuth flow (POST /token + grant_type=authorization_code).

2. Execute requests to the API using the access token.

   In time, the access token expires and API requests fail with authorization errors.

3. Acquire a NEW access and refresh token pair via the refresh token (POST /token + grant_type=refresh_token + refresh_token=YOUR_REFRESH_TOKEN, replacing YOUR_REFRESH_TOKEN with the refresh token received in step 1).

   Go back to step 2.

You're operating on the Smartsheet resources on behalf of the user.

Note: For operation details, see the POST /token reference page.

OAuth error types

For reference, here are some OAuth-related error types: