Building Integrations with the ScopeStack API

1. How ScopeStack Authentication Works

Before diving into implementation, it helps to understand how the pieces fit together.

Client Credentials Identify Your Application

When you request API access, ScopeStack issues you a Client ID and Client Secret. These identify your integration—think of them as your application's username and password.

Each client credential pair is registered to a specific callback URL. For Postman testing, this is typically something like https://oauth.pstmn.io/v1/callback (check your instance for the exact URL). For production integrations, it's your application's OAuth callback endpoint.

Important: Client credentials do not determine what data you can access or what actions you can perform. They only identify which application is making requests.

Users Determine Access

Every API request ultimately runs as a specific ScopeStack user. The user determines:

• Which account the request operates in (if a user belongs to multiple accounts)
• What permissions are available (based on the user's role)

This means the same client credentials can be used with different user accounts to access different ScopeStack accounts. The user you authenticate as controls everything.

Two Domains, Two Purposes

Domain	Use
app.scopestack.io	Authentication (getting tokens)
api.scopestack.io	API calls (using tokens)

2. Choosing an Authentication Flow

ScopeStack supports two OAuth 2.0 flows. Your choice depends on whether a human will be present during authentication.

Scenario	Flow	Why
Web app where users log in	Authorization Code	User can complete browser login
Interactive Postman testing	Authorization Code	You're at the keyboard
Workato / Zapier	Password Grant	No browser available
Backend service / cron job	Password Grant	Runs unattended
Custom scripts	Password Grant	Automated execution

3. Authorization Code Flow

Use this flow when a user can complete a browser-based login.

How It Works

1. Your application redirects the user to ScopeStack's authorization endpoint
2. The user logs into ScopeStack (including SSO/MFA if configured)
3. ScopeStack redirects back to your callback URL with an authorization code
4. Your application exchanges the code for an access token

Endpoints

• Authorization: https://app.scopestack.io/oauth/authorize
• Token Exchange: https://app.scopestack.io/oauth/token

4. Resource Owner Password Grant

Use this flow for automation—no browser, no redirect, just a direct token exchange.

⚠️ Postman Users: If you're testing this flow in Postman, do NOT use the OAuth 2.0 helper with "Password Credentials" selected. That sends a redirect_uri parameter that causes errors. Instead, make a direct POST request to the token endpoint. See the Quick Start guide for step-by-step instructions.

Token Request

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

Content-Type: application/x-www-form-urlencoded

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

Response

{

"access_token": "eyJ...",

"refresh_token": "abc123...",

"expires_in": 7200,

"token_type": "Bearer"

}

5. Setting Up Service Accounts

For production integrations, always use a dedicated service account rather than a personal user account. This ensures your integration keeps working when people leave the company.

Creating a Service Account

1. In ScopeStack, go to Settings → Users
2. Click Add User
3. Select Service Account as the account type
4. Enter an email address (this becomes the username)
5. Assign a role with appropriate permissions
6. Save and note the password

Initial Credential Validation

The first time you use a new service account, ScopeStack may prompt you to validate the credentials through your browser (including SSO/MFA). This is a one-time step. After you see "successfully validated the credentials," the account is ready for automated use with the password grant flow.

Best Practices

• Create a dedicated "Integration" or "Service Account" role with only the permissions your integration needs
• Use descriptive email addresses like workato@yourcompany.com or salesforce-sync@yourcompany.com
• Document which service account is used for which integration
• Rotate credentials periodically

6. Token Management

Token Expiration

Access tokens expire after the time specified in the expires_in response field (in seconds). Plan to refresh tokens before they expire.

Refreshing Tokens

Use the refresh token to get a new access token without re-authenticating:

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

Content-Type: application/x-www-form-urlencoded

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

Handling Token Errors

Your integration should handle 401 and 403 errors by attempting a token refresh. If the refresh fails, fall back to full re-authentication.

7. Making API Calls

Required Headers

Every API call must include:

Authorization: Bearer {access_token}

Accept: application/vnd.api+json

The Accept header is required—calls without it may fail.

Getting Account Context

After authenticating, call the /v1/me endpoint to get your account context:

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

This returns:

• account-slug: Used in API URLs (e.g., /{account-slug}/v1/clients)
• account-id: Used in relationship objects when creating/linking records

Store these values—you'll need them for most API operations.

8. Using the ScopeStack Workato Connector

ScopeStack provides a pre-built Workato connector that handles authentication, token refresh, and common operations automatically.

The connector uses the password grant flow internally. You provide your service account credentials, and the connector manages the rest.

Contact ScopeStack for access to the connector and pricing information.

9. API Reference

Full API documentation is available at https://api.scopestack.io (Swagger UI).

The API follows JSON:API conventions. Key patterns:

• GET /{account-slug}/v1/{resource} — List resources
• GET /{account-slug}/v1/{resource}/{id} — Get single resource
• POST /{account-slug}/v1/{resource} — Create resource
• PATCH /{account-slug}/v1/{resource}/{id} — Update resource
• DELETE /{account-slug}/v1/{resource}/{id} — Delete resource

Questions? Contact ScopeStack support via chat or email.