API Applications

Overview

Use this guide to create an OAuth application your users can use to access the Stack Internal API. This guide assumes you know basic API concepts, such as tenants (workspaces), HTTP requests, redirects, and JSON.

How authentication works

Stack Internal uses token-based authentication. After a user signs in, your app receives an access token. Your app sends that token with each API request like this:

Authorization: Bearer [access_token]

The access token identifies the user. Stack Internal then recalls the user's data to know:

• Which workspace the user belongs to.
• Which permissions the user has.
• Which app is making the request.

The site then uses that information to decide whether the request is allowed.

Before you start

Before you create and authorize an OAuth app, make sure you have:

• A Stack Internal user account with admin access.
• The redirect URL your app will use after sign-in.
• The scopes (permissions) your app needs.

Use the smallest set of scopes that lets your app work.

Create an OAuth application

An OAuth application represents your app in Stack Internal. You need one before your app can send users through the login flow.

You'll create and manage your OAuth applications in the Stack Internal control center. To access your site's OAuth application controls, click Control Center in the left-hand menu, then OAuth Applications under the "Developer tools" heading. You can also manage OAuth applications with the Identity API. See the "Identity API" section below.

To register a new OAuth app, click + Register application. Then, fill in the following fields:

Application name

Give the app a clear, human-readable label so admins can identify it later. This is a required field.

Redirect URL

Enter the OAuth callback URL that will receive the authorization response. This is the URL Stack Internal sends the user back to after sign-in. This is a required field.

For optimum security, observe these best practices:

• Use HTTPS.
• Use the exact path your app handles.
• Register separate OAuth applications for development, staging, and production.
• Do not use a wildcard redirect URL.
• Do not reuse another app's redirect URL.

Redirect URL example
https://app.example.com/stack-internal/callback

App scopes

App scopes control what operations this application can perform on behalf of the user. You should choose only the scopes your app needs. If you don't select any App Scopes, your API app will only be able to access a limited set of read-only endpoints. For more information on available scopes, see the "Scopes" section at the end of this article.

Save the application

After you've selected your app's scopes, click Save application. You'll see your new app in the "OAuth Applications" list. Make a note of your app's Client ID. Anyone using the new app to access the API will start the login process with its Client ID.

Identity API

Though most admins will manage OAuth applications with the Stack Internal control center, you can perform the same functions with the Identity API using the following endpoints:

GET /v1/tenants/oauth-applications

POST   /v1/tenants//oauth-applications
GET    /v1/tenants/oauth-applications/{applicationId}
PUT    /v1/tenants/oauth-applications/{applicationId}
DELETE /v1/tenants/oauth-applications/{applicationId}
GET    /v1/tenants/oauth-applications/scope-options

Use the OAuth Application

With the new OAuth app's Client ID, your users can now set up API access by following the instructions in the Stack Internal API article.

Troubleshooting

Existing workspace user required

A user must already exist and be active in the Stack Internal workspace before an OAuth access token can be used with the Stack Internal API. API access doesn't create new users. If the user hasn't signed in to Stack Internal before, or has been deactivated, the OAuth sign-in may complete but API requests will be rejected until the user is created or reactivated in Stack Internal.

Common errors

Error	What it usually means	What to check
400 Bad Request during authorize	The request is missing a PKCE value, has an invalid redirect URI, or uses the wrong environment.	Check redirect_uri, code_challenge, and code_challenge_method.
400 Bad Request during token exchange	The code expired, the verifier does not match, or the redirect URI changed.	Use the same redirect_uri and the original code_verifier.
401 Unauthorized	The token is missing, expired, malformed, or not trusted by the service.	Get a new token and send it in the Authorization header.
403 Forbidden	The token is valid, but the user or app is not allowed to do the action.	Check workspace (tenant), role, and scopes.
CORS error during token exchange	The app is not using an allowed origin for that environment.	Check the app host and environment configuration.
404 Not Found	The resource does not exist or is not visible to the caller.	Check the resource ID and workspace access.

Security checklist

Before you launch an integration:

• Register the OAuth application in the correct workspace (tenant).
• Use HTTPS redirect URIs.
• Use Authorization Code with PKCE.
• Request only the scopes your app needs.
• Send tokens only in the Authorization header.
• Do not log tokens, secrets, or customer content.
• Handle 401 by getting a new token.
• Handle 403 by showing a clear access message to the user.
• Test with users from the workspace you plan to support.

Scopes

The table below lists available API scopes.

Scope	Name	Description
auth:manage	SSO management	Configure and manage SSO in the Stack Internal Control Center.
connectors:manage	Connector enablement	Enable and configure connectors for a workspace.
content:ingest	Content creation	Add content to the workspace.
content:delete	Content deletion	Trigger deletion of ingested content in their workspace.
ingestion:manage	Ingestion management	Create, enable, or disable workspace ingestion configuration, and operate ingestion admin surfaces.
mcp:manage	MCP management	Enable/disable MCP access for the workspace.
nodes:read	Knowledge node access	Read and search Knowledge Node content and metadata.
oauth-apps:manage	OAuth app management	Manage OAuth applications for WorkOS Connect or internal integrations.
reporting:read	Reporting API access	Access reporting API endpoints and reporting datasets.
smes:manage	SME management	Perform SME management actions
user:profile:read	Profile read	Read the signed-in user's profile.
users:manage	Users management	Perform user management actions
workspace:manage	Workspace management	Manage workspace lifecycle and configuration.