API access, tokens, and StretchDev

In-app access vs. external access

Inside your workspace, apps reach the backend through the workspace gateway, which authenticates you from your signed session cookie (see How the workspace gateway works). That's perfect for the browser, but it doesn't help a script, a server, or a third-party tool that has no workspace session.

For those, you need external API access — credentials your own code can present to the StretchSuite backend (api.stretchsuite.ca/api/v1) to act on behalf of your organization. This article explains the model and where the developer surface, StretchDev, comes in.

Core principles

Regardless of how you connect, three rules always hold:

1. Every request is organization-scoped. Credentials are tied to a specific organization, and the backend only returns that org's data. There is no way to reach another tenant's data.
2. Credentials carry a role/permission level. What a token can do depends on the permissions granted to it — read-only vs. read-write, and which surfaces it may touch.
3. Secrets stay server-side. API credentials belong in your backend or a secrets manager — never in browser code, a public repo, or a mobile app bundle where they can be extracted.

Getting programmatic access

The general path to external access looks like this:

1. Confirm your access tier supports developer/API features. Developer capabilities are typically at higher tiers (StretchDev is an Agency-level surface).
2. Open StretchDev in your workspace (it requires a signed workspace session and a selected organization to load org-scoped data).
3. Create an API credential / token scoped to your organization and the permissions you need. Give it the least privilege required.
4. Store the token securely on your server. Treat it like a password.
5. Call the backend from your code, presenting the token, and target the client surfaces for the app you're integrating (for example, orders, contacts, products).
6. Rotate the token periodically and revoke it immediately if it may have leaked.

Availability of self-service token creation depends on your plan and rollout. If you don't see it, contact support to arrange scoped API access for your organization.

Where StretchDev fits

StretchDev is the developer-facing surface in the workspace. It's oriented around technical work — for example, org-scoped repositories and code/security scan data — and it's the natural home for developer tooling and API management. Like every app, it loads only your selected organization's data through the gateway, and it's gated to the appropriate access tier.

A realistic example

A business wants its own back-office system to create a StretchShop order whenever a booking is paid elsewhere:

1. On an Agency plan, a developer opens StretchDev and creates a read-write API token scoped to the organization, limited to the commerce surface.
2. They store the token in their server's secret manager — never in the browser.
3. Their booking system calls the StretchShop client API with the token to create the order.
4. StretchSuite records the order under the correct organization; it appears in the Shop Orders tab.
5. To close the loop the other way, they subscribe to relevant events via webhooks so their system learns about new store orders too (see Webhooks and real-time sync).
6. Quarterly, they rotate the token.

Security best practices

• Least privilege. Scope tokens to the minimum apps and permissions. A read-only reporting integration should never hold a write token.
• One token per integration. Separate tokens make it easy to revoke a single compromised integration without breaking others.
• Never expose tokens client-side. If a token would be visible in browser dev tools or a mobile app, it's the wrong design — proxy through your own server instead.
• Rotate and revoke. Rotate on a schedule and revoke instantly on staff changes or suspected leaks.
• Log and monitor. Watch for unexpected usage that could indicate a leaked credential.

Troubleshooting

401 / unauthorized — the token is missing, wrong, expired, or revoked. Confirm you're sending it correctly and that it's still active.

403 / forbidden on a specific action — the token lacks the permission or role for that surface. Re-scope it with the needed permission.

Data belongs to the wrong org / is empty — the token is scoped to a different organization than you expect; create/use the token for the correct org.

Feature not available — API/token self-service may be gated to a higher tier; check your access level or contact support.

FAQ

Can I use my login cookie to call the API from a script? No — the browser gateway path requires a real workspace session and is meant for in-app use. Use a proper API token for automation.

Do tokens expire? Treat them as long-lived secrets that you rotate deliberately; revoke any that might be exposed.

Is there rate limiting? Assume yes and design your integration to back off and retry gracefully.