API Authentication Guide

This guide explains how ScopeStack API authentication works before you dive into specific OAuth flows. Understanding these concepts will help you avoid common integration issues and set up your connection correctly the first time.

1. How Authentication Works

Client Credentials vs User Context

ScopeStack uses OAuth 2.0, but there is an important distinction that is often misunderstood: client credentials do not grant access on their own.

Client ID and Client Secret identify your integrating application within ScopeStack.
They are not tied to a specific company account (such as Dev vs Prod).
They do not determine what actions can be performed in the API.

All API access is ultimately authorized in the context of a ScopeStack user. The client credentials simply identify which application is making the request.

Permissions Are Always User-Based

Every access token issued by ScopeStack resolves to a specific user, and all permissions are inherited from that user's role within a company account. This means:

The authenticated user determines which account you are accessing.
The user's role determines whether you can read data, create records, or update existing objects.
It is possible to successfully retrieve data (GET requests) while receiving 403 Forbidden errors on create or update operations if the user lacks edit permissions.

Key point: Client credentials alone cannot override or bypass user-level permissions.

Client Credentials and Callback URLs

ScopeStack issues a single Client ID and Client Secret pair per integration. Each client credential pair is registered against a single callback (redirect) URL. Contact ScopeStack support with your callback URL to request a Client ID and Secret Pair.

If your integration requires a different callback URL (for example, moving from development to production), contact ScopeStack support to request an additional callback URL or replace the registered callback URL.

2. Accounts and Environments

If your organization has multiple ScopeStack accounts (for example, a Dev account and a Prod account):

These accounts may exist within the same ScopeStack application instance.
The same Client ID and Client Secret can be used across those accounts.
The account context is selected implicitly based on the authenticated user, not the client credentials.

To operate against multiple accounts, you must authenticate as a user who belongs to the target account and has the appropriate permissions. You do not need separate client credentials for each environment.

3. Required Headers and Endpoints

Endpoint Domains

ScopeStack uses two different domains for authentication and API calls:

Purpose	Domain
Authentication	app.scopestack.io
API Calls	api.scopestack.io
Swagger Docs	api.scopestack.io

Required Headers

All API calls require the following headers:

Authorization: Bearer {access_token}

Accept: application/vnd.api+json

The Accept header is required. API calls without this header may fail or return unexpected results.

4. Authentication Flows

ScopeStack supports multiple OAuth 2.0 flows. Regardless of which flow you use, the outcome is the same: a user authenticates, an access token is issued, and API permissions are enforced based on that user's role.

Authorization Code Flow

Best for: Interactive applications where a user logs in through a browser.

This flow redirects users to ScopeStack to log in, then returns them to your application with an authorization code that you exchange for an access token. See the main API documentation for endpoint details.

Out-of-Band (OOB) Flow

Best for: Development, testing, and demonstrating API functionality.

The OOB flow uses shared demo credentials that are published in the documentation. These credentials allow anyone to test the authentication flow, but they do not grant access to any data. You must still log in as a valid ScopeStack user, and your access is determined by that user's permissions.

The demo client credentials in the OOB documentation are intentionally public. They only identify the demo application—all actual access is controlled by the user account you log in with.

Resource Owner Password Grant

Best for: Automation tools, server-to-server integrations, and platforms like Workato.

This flow allows you to authenticate directly with a username and password, without requiring a browser redirect. This is the recommended approach for service account authentication in production integrations.

Token Request

POST https://app.scopestack.io/oauth/token

With the following parameters (form-encoded):

Parameter	Value
grant_type	password
client_id	Your application's Client ID
client_secret	Your application's Client Secret
username	Service account email address
password	Service account password

Response

A successful response includes an access token, refresh token, and expiration time:

{

"access_token": "eyJ...",

"refresh_token": "abc123...",

"expires_in": 7200,

"token_type": "Bearer"

}

5. Validating Your Connection

After authenticating, we strongly recommend making a test call to confirm your connection is working and that you are operating in the correct account context:

GET https://api.scopestack.io/v1/me

This endpoint returns information about the authenticated user, including:

account-id: The unique identifier for the account. Used in relationship objects when creating or updating records.
account-slug: A short identifier for the account. Used in API URLs (e.g., /{account-slug}/v1/clients).

This is the fastest way to validate that authentication and account context are correct before attempting other operations.

6. Setting Up Service Users

For production integrations, we recommend using dedicated service users rather than personal user accounts. This improves security, auditability, and ensures integrations continue working when team members leave.

To create a service user:

Navigate to the Users panel in your ScopeStack account.
Create a new user and select Service Account as the account type.
Assign the service user a role. The role determines what permissions the integration will have.
Use the service account credentials when configuring your integration.

Best practices:

Consider creating a dedicated role (e.g., "Service Account" or "Integration User") for easy permission management.
Assign only the permissions required for the integration's specific use case.
Avoid using personal user accounts for long-lived integrations.

7. Troubleshooting 403 Errors

A 403 Forbidden error means you are authenticated but do not have permission to perform the requested action. Unfortunately, the error response does not specify which permission is missing, so you will need to check the following:

403 Troubleshooting Checklist

✓	Check
☐	User role lacks write permissions. The authenticated user's role may allow read access but not create/update access for this resource type. Verify the role's permissions in ScopeStack.
☐	Wrong account context. The user may be authenticated but belong to a different account than expected (e.g., authenticated as a Dev user but trying to modify Prod data). Call /v1/me to verify which account you are operating in.
☐	Token expired. Access tokens have a limited lifespan. If the token has expired, you may receive a 401 or 403 error depending on timing. Use your refresh token to obtain a new access token.
☐	Resource belongs to a different account. If you are trying to modify a resource that exists but belongs to an account the user cannot access, you will receive a 403 error.
☐	User was removed or deactivated. If the user account was deactivated after the token was issued, subsequent API calls will fail. You will need to re-authenticate with an active user.

8. Token Lifecycle

Token Expiration

Access tokens expire after a period of time (indicated by the expires_in value in the token response). When a token expires, API calls will return a 401 or 403 error.

Refreshing Tokens

To obtain a new access token without requiring the user to log in again, use the refresh token:

POST https://app.scopestack.io/oauth/token

With parameters:

Parameter	Value
grant_type	refresh_token
client_id	Your application's Client ID
client_secret	Your application's Client Secret
refresh_token	The refresh token from your original token response

What Happens When a User Is Deleted

If a user account is deleted or deactivated while an integration is using that user's credentials, all API calls using tokens issued to that user will fail. You will need to re-authenticate with a different, active user account.

This is a key reason to use dedicated service accounts for integrations rather than personal user accounts. When an employee leaves, deactivating their personal account will not break integrations that use a separate service account.

9. Integration Options

ScopeStack Integration Engine

ScopeStack provides a custom-built Workato connector that handles authentication, token refresh, and common operations automatically. If you are using Workato, we recommend using our integration service rather than building a custom connection.

Contact ScopeStack for more information and pricing details.

Building Your Own Integration

If you are building a custom integration using Postman, a custom application, or another automation platform, use the Swagger documentation at api.scopestack.io for the complete API reference and contact our support team to be issued a Client ID and Secret.

Key implementation notes:

Store the refresh token securely and use it to obtain new access tokens when needed.
Handle 401 and 403 responses by refreshing the token and retrying the request.
After authentication, call /v1/me to retrieve the account slug and account ID, which are needed for subsequent API calls.
The account slug appears in most API URLs (e.g., /{account-slug}/v1/clients).
The account ID is used in relationship objects when creating or linking records.

Questions? Contact ScopeStack support via chat or email for assistance with API integration.