Skip to Content
HelpIntegrationsService Account Credentials

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.

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 log into the ScopeStack application
  • 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 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.

For more on user types and roles, see Users.

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 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.

Last updated on
Building IntegrationsAPI Auth Troubleshooting