diff --git a/connection-guides/faq-authentication.mdx b/connection-guides/faq-authentication.mdx new file mode 100644 index 0000000..eba3ef3 --- /dev/null +++ b/connection-guides/faq-authentication.mdx @@ -0,0 +1,91 @@ +--- +title: 'FAQ: API authentication methods' +description: 'Answers to common questions about the authentication methods used to connect integrations in StackOne Hub.' +--- + +## What authentication methods does StackOne Hub support? + +StackOne Hub supports several authentication methods depending on the integration: + +- **API key** — A static token generated in the third-party platform and entered in the connection form. +- **OAuth 2.0 (Authorization Code)** — You authorize StackOne via the provider's OAuth consent screen. No credentials are stored. +- **OAuth 2.0 (Client Credentials)** — Machine-to-machine flow using a client ID and client secret you generate in the third-party platform. +- **Basic credentials** — A username and password (or service user credentials) used by some enterprise systems. +- **Service user** — A dedicated system/integration user created in the provider's platform with limited, scoped permissions. + +The authentication method for each connector is shown in its connection guide. + +## What is the difference between API key and OAuth authentication? + +With **API key** authentication, you generate a token directly in the third-party system and paste it into the StackOne connection form. The token is static and remains valid until you revoke it. + +With **OAuth** authentication, you grant StackOne access through the provider's authorization flow. StackOne receives an access token and (in most cases) a refresh token, so it can maintain access without storing your credentials. + +OAuth is generally preferred because you can revoke access from the provider's side at any time, and credentials are never directly shared. + +## Do I need admin access to connect an integration? + +Most integrations require admin or elevated privileges to generate API credentials or complete OAuth authorization. This is because: + +- API key generation is usually restricted to administrators. +- OAuth flows may require permission to authorize third-party access on behalf of the organization. +- Some integrations require creating a dedicated service/integration user with specific permission scopes. + +Check the connection guide for the specific integration to confirm what level of access is needed before starting. + +## What permissions or scopes are required? + +Required scopes vary by integration. Each connection guide lists the exact scopes you need to enable. As a general rule: + +- Only grant the scopes listed — StackOne requests the minimum permissions needed. +- If you grant fewer scopes than required, some API calls may fail or return incomplete data. +- Scopes can usually be updated later by regenerating credentials or re-authorizing. + +## What happens if I rotate or revoke my API key? + +If you rotate or revoke your API key in the third-party system, the existing connection in StackOne Hub will stop working. You will need to: + +1. Generate a new API key in the third-party system. +2. Update the connection in StackOne Hub with the new credentials. + +For OAuth connections, revoking access from the provider's side (e.g., disconnecting the app in your account settings) will also break the connection. + +## Can I use a service user instead of my personal account? + +Yes, and for most enterprise integrations this is the recommended approach. Using a dedicated service or integration user: + +- Keeps your personal credentials separate from the integration. +- Ensures the connection remains active if your personal account is deactivated. +- Allows you to apply least-privilege permissions scoped only to what the integration needs. + +Many connection guides (for example, Hibob Service User and Workday ATS) specifically instruct you to create a service user. + +## Is it safe to enter my credentials in StackOne Hub? + +StackOne is designed with privacy and security as core principles: + +- Credentials are used to establish connections and are not stored beyond what is needed for authentication. +- StackOne proxies API requests in real-time and does not store personal data by default. +- The platform is SOC 2 Type II certified and GDPR compliant. + +For more details, visit [trust.stackone.com](https://trust.stackone.com) or contact [security@stackone.com](mailto:security@stackone.com). + +## What should I do if my connection fails due to authentication errors? + + + + Double-check that you copied the correct API key, client ID, or client secret — make sure there are no extra spaces or characters. + + + Ensure all required scopes listed in the connection guide are enabled and saved in the third-party system. + + + Verify that the account used to generate credentials has the required admin or integration permissions. + + + If the error persists, try generating a new API key or refreshing OAuth tokens and reconnecting. + + + If you are still unable to connect, reach out to [integrations@stackone.com](mailto:integrations@stackone.com) with the name of the integration and the error message you are seeing. + + diff --git a/docs.json b/docs.json index 4fe630d..fae1ad1 100644 --- a/docs.json +++ b/docs.json @@ -17,6 +17,7 @@ "pages": [ "integrations", "integration-configuration-concepts", + "connection-guides/faq-authentication", "about" ] },