Skip to main content

Run a Script Engine script as a service account

Run a Script Engine script as a service account: store its client secret in Secrets and select it on the script.

Written by Sravya Challagundla

A Script Engine script can run as a service account instead of a person. Every record it changes is then recorded under the account's own name, with only the access you granted.

You create the service account, store its client secret in Secrets, select that secret on the script, and run the script.

Example: a policy team's script moves approved policies whose review date has passed back to Ready for Review. Its service account has Full access to the Policies table and nothing else.

Plan Availability

Enterprise and Signature.

Permissions

Workspace Administrators create service accounts, secrets and scripts in Workspace Administration.

Platform

Web

Related Reading


Why run a script as a service account?

A script on a person's API key has all of that person's access. Every change looks like the person made it, and the script stops when the person leaves.

A service account belongs to the workspace instead:

  • It uses no paid seat.

  • It reaches only the tables an Administrator grants.

  • It records every change under its own name.

Three features work together. Script Engine runs the code, Secrets keeps the credential out of the code, and the service account gives the script its identity.


What you need

  • The Administrator role on an Enterprise or Signature workspace.

  • A script in Script Engine, or the code you will paste into one.

  • The tables the script reads and writes. The service account gets access to those and nothing else.


Step 1: Create the service account

  1. In Workspace Administration, select Service Accounts, then New Service Account.

  2. In Details, enter a name and a description that say what the script does, and assign the owner.

  3. Under Notifications, choose who gets alerts about its credentials and run problems.

  4. In Authentication, select OAuth 2.0 and set the client secret expiration. 90 days is the recommended expiration.

  5. In Access, add the solution.

  6. Set the table the script changes to Full access, or Read only if the script only reads. Leave every other table at No access, the default.

  7. Save. SmartSuite shows the client ID and the client secret.

  8. Copy the client secret now. It is shown only once. The client ID stays visible on the account.

The full flow is in Service Accounts in SmartSuite.


Step 2: Store the client secret in Secrets

  1. In Workspace Administration, select Secrets, then New Secret.

  2. Enter a Secret Name in capitals with underscores, for example SERVICE_ACCOUNT_SECRET.

  3. Paste the client secret as the Value.

  4. Select Create Secret.

Warning: Never paste the client secret into the script's code. Keep it in Secrets, where every reveal is recorded.


Step 3: Select the secret on the script

  1. In Workspace Administration, select Script Engine and open the script.

  2. Select Choose secrets.

  3. Check the service account secret and select Done.

  4. Save the script.

At run time, the script reads the value from context.secrets under the name you gave it. It uses the value to sign in as the service account.


Step 4: Run the script and check the result

  1. Run the script manually the first time. The run log lists the records it updated.

  2. Open one of the changed records. Its activity history names the service account.

  3. On the service account, open the Log tab. It lists the API calls with the time, the resource and the IP address.

In the policy example, the run log lists three policies. Each shows Ready for Review in the view, and each activity history names the service account.

Note: The script can reach only what the service account can reach. A table left at No access cannot be read or written by the script.


Rotating the credential

  1. On the service account, generate a new client secret. It works alongside the old one.

  2. On the Secrets page, replace the Value of the secret with the new client secret.

  3. Revoke the old client secret on the service account.

Every script that uses the secret picks up the new value with no script edit.

Watch: Workspace: Service Accounts (4 min) walks through the policy example. The script run starts at 2:53.


Frequently asked questions

Does the script still need a personal API key?

No. It signs in with the service account's credential, which you store in Secrets and select on the script.

Where do I see what the script changed?

In three places: the script's run log, each changed record's activity history, and the service account's Log tab.

Can the script run on a schedule?

Yes. Give it an Hourly, Daily or Weekly schedule, or a custom expression, in Script Engine. Every run signs in as the service account.

What happens when the client secret expires?

Requests that use it are refused. From 7 days before the expiration, the owner and the members chosen under Notifications get a daily reminder.

How do I replace an expiring client secret?

Generate a new one on the service account, replace the Value on the Secrets page, then revoke the old one.

Need more help? Ask the SmartSuite Community, where builders, administrators and the SmartSuite team answer questions about building on SmartSuite. For your account, billing or data, select the chat button in the lower-right corner of SmartSuite to reach support.

Last verified 1 Nov 2026.

Did this answer your question?