A Script Engine script can run as a service account instead of a person, so every record it changes is 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.
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 that runs on a person's API key carries that person's full access, every change it makes looks like that person made it, and it stops working when the person leaves. A service account belongs to the workspace instead: it uses no paid seat, reaches only the tables an Administrator grants it, and records every change under its own name.
Three features work together. Script Engine runs your code, Secrets keeps the credential out of the code, and the service account gives the script an identity with only the access it needs.
What do I need before I start?
The Administrator role on a workspace on the Enterprise or Signature plan.
A script in Script Engine, or the code you will paste into one (Managing Scripts in Script Engine).
The table or tables the script reads and writes. The service account gets access to those and nothing else.
How do I run a script as a service account?
The flow has three parts: the service account, the secret and the script. Each step names where you are before what you do.
Create the service account. In Workspace Administration, select Service Accounts, then New Service Account. In Details, give it a name and a description that say what the script does, assign the owner, and under Notifications choose who receives alerts about its credentials and run problems. The full flow is in Service Accounts in SmartSuite.
Choose OAuth 2.0. In Authentication, select OAuth 2.0 and set the client secret expiration; 90 days is the recommended expiration.
Grant access to the script's tables only. In Access, add the solution, then set the table the script changes to Full access (or Read only when the script only reads). Every other table stays at No access, the default.
Save and copy the client secret. On save, SmartSuite shows the client ID and the client secret. Copy the secret now; it is shown only this once. The client ID stays visible on the account.
Store the secret in Secrets. In Workspace Administration, select Secrets, then New Secret. Enter a Secret Name in uppercase with underscores, for example SERVICE_ACCOUNT_SECRET, paste the client secret as the Value and select Create Secret. Never paste the secret into the script's code (Secrets Management).
Select the secret on the script. In Workspace Administration, select Script Engine, open the script, select Choose secrets, check the service account secret, select Done and save the script. At run time the script reads the value from context.secrets under the name you gave it and uses it to sign in as the service account.
Run the script. Run it manually the first time. The script performs its changes signed in as the service account, and the run log lists the records it updated.
Check the result. Open one of the changed records: its activity history shows that the service account made the change. On the service account, the Log tab lists the API calls with the time, the resource and the IP address.
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, whoever created the script.
Tip: To rotate the credential, generate a new client secret on the service account (it works alongside the old one), replace the Value of the secret on the Secrets page, then revoke the old secret. Every script that references the secret picks up the new value without a script edit.
Example: move overdue policies back to review
A policy management solution holds the company's policies, and standards such as ISO 27001 and SOC 2 require every policy to be reviewed on a schedule. Approved policies whose review date has passed are highlighted in the view.
The script finds approved policies whose review date has passed and sets their status back to Ready for Review. Its service account has Full access to the Policies table and nothing else, and its client secret is stored in Secrets and selected on the script. After a manual run, the run log lists the three records it updated and the three policies show the new status in the view. Each record's activity history names the service account, and the account's Log tab shows the API calls.
Watch: Workspace: Service Accounts (4 min) walks through this example; the script run starts at 2:53.
Frequently asked questions
Does the script still need a personal API key?
Does the script still need a personal API key?
The script does not need a personal API key. It signs in with the service account's credential, which you store in Secrets and select on the script, and the service account uses no paid seat.
Where do I see what the script changed?
Where do I see what the script changed?
Three places show it. The script's run log lists the records it updated, each changed record's activity history names the service account, and the account's Log tab lists the API calls with time, resource and IP address.
Can the script run on a schedule?
Can the script run on a schedule?
A script can run on a schedule. Give it an Hourly, Daily or Weekly schedule, or a custom expression, in Script Engine; every run uses the secret selected on the script, so every run signs in as the service account.
What happens when the client secret expires?
What happens when the client secret expires?
Requests that use an expired client secret are refused. Starting 7 days before the expiration, the account's owner and the members chosen under Notifications receive a reminder every day. Generate a new client secret, replace the Value of the secret on the Secrets page, then revoke the old one.
Last verified 30 Oct 2026.