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.

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, go to Settings > Users & Groups > Users and create a new user. Set the User Type to “Service.” Assign roles and privileges as you would for any other user. The roles you assign determine what the service account can read and write through the API.

Create a new user for this. Do not change an existing person’s user type to Service. A person converted to Service keeps a working login but loses the application: every page returns the service-account notice instead of loading. Because they cannot reach Settings, they cannot undo it themselves. Another administrator with Manage rights on Users has to change the type back. If no one else on the account has those rights, contact ScopeStack support.

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

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.