Service Account Credentials

Service Account Credentials let you connect external tools to the ScopeStack API and MCP servers without requiring a user to sign in through the browser. They use the OAuth 2.0 Client Credentials flow, which is ideal for server-to-server integrations, automated workflows, and AI assistants.

Create a new user for your integration. Never change your own user, or a colleague’s, to Service. A person whose user is changed to Service can still sign in but can no longer use the application, and cannot change it back themselves. Follow the steps under Service Accounts below. If it has already happened, see If every page says the credentials were validated.

Why an integration should not authenticate as a person

When an integration signs in as one of your people, it inherits that person’s account access, and it keeps inheriting it as that access changes.

ScopeStack resolves which account a request belongs to from the user making the request, at the time of the request. That is not fixed to the credential. So if the person’s active account changes, every token they already hold begins reading and writing the new account instead. Nothing about the integration changed, no error is raised, and the writes still return valid record IDs and a success response.

The usual trigger is routine administration. Adding an existing user to a second account, a newly provisioned sandbox for example, both grants them membership and moves their active account. If an integration authenticates as that person, its records start landing in the second account from that moment. What you see is records that seem to vanish, links that return errors, and a sync that looks perfectly healthy from the outside.

Because a service account is not tied to a person, it does not follow anyone through a membership change. Create one for each integration.

Be clear on what this does and does not solve. It removes the likely trigger, which is a person’s login and account membership changing underneath the integration. A service account is still a user whose account assignment an administrator can change, so keep each one dedicated to its integration and leave its account alone.

One planning note: moving an existing integration onto client credentials is a change to the integration’s code, not a setting you toggle in ScopeStack. Scope it accordingly.

Service Accounts

A Service Account is a user with the User Type set to “Service.” Service accounts differ from regular users in a few ways:

• They can authenticate against the API and MCP servers using client credentials
• They cannot use the ScopeStack application. Signing in still succeeds, but every page returns a notice confirming the credentials are valid and directing the account to the API
• They do not count against seat-based pricing
• They use the same role-based access controls as any other user

To create a service account:

1. Go to Settings > Users & Groups > Users and click Add a User.
2. Name it for the integration it serves (for example, “Reporting integration”) and give it an email address of its own, such as a shared mailbox or alias. An email address can belong to only one ScopeStack user, so a person’s address is already taken by their own login.
3. Set the User Type to “Service.” A dialog titled “Change to Service Account” opens and says “A service account can access the ScopeStack API but cannot log in to the pages of the application. Do you want to continue?” Click Continue. The user type does not change until you do. Then assign roles and click Save. The roles you assign determine what the service account can read and write through the API.
4. Open the new user from the Users list and select the Client Credentials tab to create its credentials, as described below. The tab is not on the Add a User form. It appears once the user has been saved.

Check whose user you are editing before you change its type. On an existing user, the Client Credentials tab appears as soon as you select Service and click Continue in the “Change to Service Account” dialog, before you save. That makes it easy to open your own user while looking for the tab and switch it by mistake. If the form shows your own name and email, click Cancel in the dialog, or leave the form without saving, and use Add a User instead.

You can also convert a user from the Users list. Click the gear icon on the user’s row and choose Convert to Service User. A dialog titled “Convert to Service Account” asks the same question, and choosing Continue converts the user right away, without a separate save.

For more on user types and roles, see Users.

Account-wide OAuth2 callbacks are deprecated. If your account has an existing account-wide callback (Settings > Account > OAuth Callback URL), you can still edit its redirect URL, but the client secret is no longer displayed and new account-wide callbacks are no longer created. Service account credentials described on this page are the replacement, and give each integration its own scoped credentials.

Managing Client Credentials

Once a service account exists, users with the Manage privilege on Settings > Account can manage its client credentials.

Open the service account from Settings > Users & Groups > Users and select the Client Credentials tab. This tab only appears for service-type users.

The credentials table shows each credential’s name, redirect URI, and masked client ID and secret. Masked values display as •••••• followed by the last four characters.

Creating Credentials

1. Click New Credential
2. Enter a Name for the credential. Use something that identifies where or how the credential will be used (for example, “Datadog forwarder” or “Reporting automation”).
3. Optionally enter a Redirect URI. This is typically the hostname of the server that will call the API. While optional, providing it adds an extra layer of security.
4. Click Create

A dialog appears showing the full Client ID and Client Secret. Use the Copy buttons to copy each value.

Save these credentials immediately. You will not be able to view the full values again. If you lose them, you will need to rotate the secret to get a new one. The client ID cannot be recovered after this dialog is closed.

Click I’ve saved these to dismiss the dialog.

Using Credentials to Obtain an Access Token

Once you have a client ID and secret, request an access token from the ScopeStack token endpoint:

POST https://app.scopestack.io/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

If your client secret contains special characters (&, %, +, =, #), those characters must be URL-encoded in the request body. Most HTTP libraries handle this automatically. When using curl, use --data-urlencode for each field:

curl -X POST https://app.scopestack.io/oauth/token \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=YOUR_CLIENT_ID" \
  --data-urlencode "client_secret=YOUR_CLIENT_SECRET"

You can also send the credentials as HTTP Basic authentication, which avoids body encoding entirely:

POST https://app.scopestack.io/oauth/token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

The response includes a JWT access token. Include it in subsequent API requests as a Bearer token:

Authorization: Bearer YOUR_ACCESS_TOKEN

Access tokens expire after 24 hours. Request a new token when the current one expires.

Rotating the Client Secret

If your secret may have been compromised, or if your security policy requires periodic rotation, you can generate a new secret without creating a new credential.

1. In the Client Credentials tab, click the rotate icon at the end of the credential row
2. Review the confirmation. Rotating the secret immediately revokes all access tokens issued with the current secret. Any integration using the old secret will need to be updated.
3. Click Rotate Secret
4. Copy the new secret from the one-time reveal dialog. The client ID does not change.
5. Click I’ve saved these to dismiss

Update your integration with the new secret. The old secret stops working immediately.

Editing Credentials

Click the credential name in the table to edit it. You can update the Name and Redirect URI. The client ID and secret are not editable. Click Save to confirm.

Deleting Credentials

1. Select one or more credentials using the checkboxes
2. Click Delete
3. Review the confirmation. Deleting a credential immediately revokes all access tokens issued against it. Any integration using the credential will stop working. This cannot be undone.
4. Click Delete to confirm

If every page says the credentials were validated

If a person signs in and every page shows “You have successfully validated the credentials for …” followed by a note that the account may only be used to access the ScopeStack API, their user has been changed to the Service type. The browser is not the cause, so signing out, clearing the cache, or using a private window will not help. They also cannot fix it themselves, because Settings is behind the same notice.

Another administrator with Manage rights on Users fixes it:

1. Open Settings > Users & Groups > Users and select the affected user.
2. Set User Type back to what it was, usually Licensed.
3. Check the name, roles, and other fields. If the change was made while filling in details meant for a new user, those may have been overwritten too.
4. Click Save.

Changing the user back deletes any client credentials created on it while it was a service account. If an integration already depends on those credentials, set up a separate service account for it first.

If no one else on your account has Manage rights on Users, contact ScopeStack support.

Important Notes

Changing a service account’s user type destroys all its credentials. If you change a service account to Licensed, Sales, or View Only, all client credentials for that user are permanently deleted and all associated tokens are revoked. This happens immediately and cannot be reversed.

Multiple credentials per service account are supported. You might use separate credentials for different integrations or environments. Each credential has its own client ID and secret.

Access is controlled by the service account’s roles. The credentials themselves do not carry permissions. What the integration can do through the API is determined by the roles and privileges assigned to the service account user.

The token endpoint is discoverable. ScopeStack publishes OAuth metadata at /.well-known/oauth-authorization-server, which includes the token endpoint and supported grant types. MCP clients and other tools that support OAuth discovery can find the endpoint automatically.