# Authentication & Security
Source: https://docs.stackone.com/a2a/auth-security

Learn about A2A authentication methods, required headers, and security best practices for StackOne A2A agents.

## Authentication

StackOne A2A agents use the same authentication as the regular StackOne API, ensuring consistent security across all integration methods.

### Required Headers

All A2A requests require these headers:

```bash theme={null}
Authorization: Basic <BASE64_ENCODED_STACKONE_API_KEY>
x-account-id: <ACCOUNT_ID>
Content-Type: application/json
```

<AccordionGroup>
  <Accordion title="How to get your StackOne API key and Account ID" icon="key">
    **Get API Key:**

    1. Go to <a href="https://app.stackone.com/api_keys">**Configuration → API Keys**</a> in the dashboard
    2. Create or copy existing API key

    **Get Account ID:**

    1. Go to <a href="https://app.stackone.com/accounts">**Accounts**</a> in the dashboard
    2. Select your linked account
    3. Copy the account ID (numeric format like `47187425466113776871` or short alphanumeric ID)

    You can also retrieve account IDs programmatically via the [List Accounts API endpoint](/platform/api-reference/accounts/list-accounts).

    See [API Keys Guide](/guides/api-keys) for detailed instructions.
  </Accordion>
</AccordionGroup>

<Warning>
  Unlike some other StackOne endpoints, A2A does **not** support query parameters for authentication. You must use headers for both the API key and account ID.
</Warning>

### API Key

**How to create the Basic Auth token:**

1. Take your StackOne API key (e.g., `v1.us1.AAblXDxi8h_OO1AZG_Hyg4V3w65x9...`)
2. Append a colon: `v1.us1.YYplXCxi8h_OO9HZG_Kyg4V3w65x9...:`
3. Base64 encode the result

<CodeGroup>
  ```bash Terminal theme={null}
  echo -n "<stackone_api_key>:" | base64
  ```

  ```javascript JavaScript theme={null}
  btoa("<stackone_api_key>:");
  ```

  ```python Python theme={null}
  import base64
  token = base64.b64encode(b"<stackone_api_key>").decode('ascii')
  ```
</CodeGroup>

### Account ID

The account ID must be passed via the `x-account-id` header.

**Account ID Format:**

* Numeric string (e.g., `47187425466113776871`)
* Short alphanumeric ID (e.g., `abc123xyz`)

## Security Best Practices

### Store API Keys Securely

Use environment variables and never commit API keys to version control.

## Troubleshooting Authentication

Common authentication issues include:

* 401 Unauthorized errors - Check your API key is valid
* 403 Forbidden errors - Verify account permissions
* Missing header issues - Ensure all required headers are present
* Base64 encoding problems - Verify the encoding includes the colon
* Account ID validation - Confirm the account ID exists and is accessible

## Testing Authentication

Verify your authentication setup by fetching the Agent Card:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://a2a.stackone.com/.well-known/agent-card.json \
    -H 'Authorization: Basic <YOUR_BASE64_TOKEN>' \
    -H 'x-account-id: <YOUR_ACCOUNT_ID>'
  ```
</CodeGroup>

A response with agent details based on your account's configured integrations and enabled actions confirms your authentication is configured correctly.

## Next Steps

Once authentication is configured:

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/a2a/quickstart">
    Get started with the A2A UI and cURL
  </Card>

  <Card title="SDK Guides" icon="code" href="/a2a/sdk-guides/python">
    Use the official A2A SDKs to build your own tools
  </Card>

  <Card title="Agent Guides" icon="robot" href="/a2a/framework-guides/adk">
    Build agents in frameworks with A2A integrations
  </Card>
</CardGroup>


# Agent Development Kit (ADK)
Source: https://docs.stackone.com/a2a/framework-guides/adk

Build agents in Google's ADK that communicate with StackOne's A2A agents using RemoteA2aAgent.

## Overview

The [Agent Development Kit (ADK)](https://google.github.io/adk-docs/) is Google's open-source framework for building AI agents. ADK has built-in support for the A2A protocol, allowing your agents to communicate with remote A2A agents like StackOne's.

Use ADK to build agents that:

* Consume StackOne's A2A agents as remote sub-agents
* Orchestrate multi-agent systems with local and remote agents
* Access StackOne platform actions without managing tool definitions

## Installation

Install ADK with A2A support using `pip`:

```bash theme={null}
pip install google-adk[a2a]
```

## Quick Start

This example creates an orchestrator agent that delegates HR tasks to a StackOne A2A agent.

```python theme={null}
import base64
import httpx
from google.adk.agents.llm_agent import Agent
from google.adk.agents.remote_a2a_agent import RemoteA2aAgent

# StackOne A2A configuration
STACKONE_API_KEY = "<stackone_api_key>"
STACKONE_ACCOUNT_ID = "<account_id>"
BASE64_API_KEY = base64.b64encode(f"{STACKONE_API_KEY}:".encode()).decode()

# Create an HTTP client with StackOne authentication headers
http_client = httpx.AsyncClient(
    headers={
        "Authorization": f"Basic {BASE64_API_KEY}",
        "x-account-id": STACKONE_ACCOUNT_ID
    }
)

# Create a remote A2A agent pointing to StackOne
stackone_agent = RemoteA2aAgent(
    name="stackone_hr_agent",
    description="Agent that handles HR operations via StackOne integrations.",
    agent_card="https://a2a.stackone.com/.well-known/agent-card.json",
    httpx_client=http_client
)

# Create the orchestrator agent with StackOne as a sub-agent
root_agent = Agent(
    model="gemini-2.0-flash",
    name="hr_assistant",
    instruction="""
        You are an HR assistant that helps with employee management tasks.
        Delegate HR operations to the stackone_hr_agent.

        When the user asks about employees, time off, or other HR data,
        use the stackone_hr_agent to fetch or update the information.
    """,
    sub_agents=[stackone_agent],
)
```

See [Authentication Guide](/a2a/auth-security) for details on obtaining your API key and account ID.

## Architecture

ADK's `RemoteA2aAgent` allows your local agent to delegate tasks to remote A2A agents:

```mermaid theme={null}
flowchart LR
    User[User] --> RootAgent[Root Agent<br/>Local ADK]
    RootAgent -->|A2A Protocol| StackOneA2A[StackOne A2A Agent]
    StackOneA2A --> Providers[(Connected SaaS<br/>HiBob, Workday, etc.)]
    RootAgent --> LocalTools[Local Tools<br/>Optional]

    style StackOneA2A fill:#10b981,stroke:#059669,color:#fff
```

## Complete Example

Here's a complete example with a local tool and a remote StackOne agent:

```python theme={null}
import base64
import httpx
from google.adk.agents.llm_agent import Agent
from google.adk.agents.remote_a2a_agent import RemoteA2aAgent
from google.genai import types

# Configuration
STACKONE_API_KEY = "<stackone_api_key>"
STACKONE_ACCOUNT_ID = "<account_id>"
BASE64_API_KEY = base64.b64encode(f"{STACKONE_API_KEY}:".encode()).decode()

# Local tool example
def get_current_date() -> str:
    """Get the current date."""
    from datetime import datetime
    return datetime.now().strftime("%Y-%m-%d")

# Create an HTTP client with StackOne authentication headers
http_client = httpx.AsyncClient(
    headers={
        "Authorization": f"Basic {BASE64_API_KEY}",
        "x-account-id": STACKONE_ACCOUNT_ID
    }
)

# Remote StackOne A2A agent
stackone_agent = RemoteA2aAgent(
    name="stackone_hr_agent",
    description="""
        Agent that handles HR operations via StackOne integrations.
        Can list employees, get employee details, manage time off requests,
        and perform other HR operations depending on the connected integration.
    """,
    agent_card="https://a2a.stackone.com/.well-known/agent-card.json",
    httpx_client=http_client
)

# Root orchestrator agent
root_agent = Agent(
    model="gemini-2.0-flash",
    name="hr_assistant",
    instruction="""
        You are an HR assistant that helps with employee management tasks.

        You have access to:
        1. get_current_date - Get today's date
        2. stackone_hr_agent - Delegate HR operations (employees, time off, etc.)

        When users ask about HR data, delegate to stackone_hr_agent.
        Always confirm actions before making changes.
    """,
    global_instruction="You are HRBot, ready to help with HR tasks.",
    sub_agents=[stackone_agent],
    tools=[get_current_date],
    generate_content_config=types.GenerateContentConfig(
        temperature=0.7,
    ),
)
```

## Running the Agent

Use ADK's built-in web server to interact with your agent:

```bash theme={null}
adk web path/to/your/agent/folder
```

Then open `http://localhost:8000` in your browser to chat with your agent.

### Example Interactions

**Listing Employees:**

```text theme={null}
User: List all employees
Bot: I'll get that information for you from the HR system.
     [Delegates to stackone_hr_agent]
     Here are the employees:
     1. John Doe - Software Engineer
     2. Jane Smith - Product Manager
     ...
```

**Getting Employee Details:**

```text theme={null}
User: Get details for employee ID emp_123
Bot: [Delegates to stackone_hr_agent]
     Here are the details for emp_123:
     - Name: John Doe
     - Department: Engineering
     - Start Date: 2023-01-15
     ...
```

## Multiple StackOne Accounts

Connect to multiple StackOne accounts by creating separate HTTP clients and `RemoteA2aAgent` instances for each:

```python theme={null}
import base64
import httpx
from google.adk.agents.llm_agent import Agent
from google.adk.agents.remote_a2a_agent import RemoteA2aAgent

STACKONE_API_KEY = "<stackone_api_key>"
BASE64_API_KEY = base64.b64encode(f"{STACKONE_API_KEY}:".encode()).decode()

# HTTP client for HiBob account
hibob_http_client = httpx.AsyncClient(
    headers={
        "Authorization": f"Basic {BASE64_API_KEY}",
        "x-account-id": "<hibob_account_id>"
    }
)

# HTTP client for BambooHR account
bamboo_http_client = httpx.AsyncClient(
    headers={
        "Authorization": f"Basic {BASE64_API_KEY}",
        "x-account-id": "<bamboohr_account_id>"
    }
)

# Agent for HiBob integration
hibob_agent = RemoteA2aAgent(
    name="hibob_agent",
    description="Agent for HiBob HR operations",
    agent_card="https://a2a.stackone.com/.well-known/agent-card.json",
    httpx_client=hibob_http_client
)

# Agent for BambooHR integration
bamboo_agent = RemoteA2aAgent(
    name="bamboo_agent",
    description="Agent for BambooHR operations",
    agent_card="https://a2a.stackone.com/.well-known/agent-card.json",
    httpx_client=bamboo_http_client
)

# Orchestrator with both agents
root_agent = Agent(
    model="gemini-2.0-flash",
    name="multi_hr_assistant",
    instruction="""
        You have access to multiple HR systems:
        - hibob_agent: For HiBob HR operations
        - bamboo_agent: For BambooHR operations

        Route requests to the appropriate system based on user context.
    """,
    sub_agents=[hibob_agent, bamboo_agent],
)
```

## Best Practices

<AccordionGroup>
  <Accordion title="Clear Agent Descriptions" icon="file-lines">
    Provide detailed descriptions for your `RemoteA2aAgent` instances. The orchestrator uses these descriptions to decide when to delegate tasks.

    ```python theme={null}
    # Good: Specific description
    stackone_agent = RemoteA2aAgent(
        name="stackone_hr_agent",
        description="Handles employee management: listing employees, getting employee details, updating employee information, and managing time off requests.",
        ...
    )

    # Bad: Vague description
    stackone_agent = RemoteA2aAgent(
        name="stackone_agent",
        description="HR agent",
        ...
    )
    ```
  </Accordion>

  <Accordion title="Explicit Delegation Instructions" icon="diagram-project">
    Include clear delegation instructions in your orchestrator's system prompt:

    ```python theme={null}
    root_agent = Agent(
        instruction="""
            When the user asks about:
            - Employee data -> delegate to stackone_hr_agent
            - Time off requests -> delegate to stackone_hr_agent
            - Local operations -> use local tools

            Always confirm before making changes to HR systems.
        """,
        ...
    )
    ```
  </Accordion>

  <Accordion title="Error Handling" icon="triangle-exclamation">
    ADK handles A2A communication errors, but you should instruct your agent on how to respond:

    ```python theme={null}
    root_agent = Agent(
        instruction="""
            If the HR agent returns an error or is unavailable:
            1. Apologize to the user
            2. Explain the issue briefly
            3. Suggest trying again later or contacting support
        """,
        ...
    )
    ```
  </Accordion>

  <Accordion title="Resource Cleanup" icon="broom">
    When your application shuts down, clean up the HTTP client and agent resources:

    ```python theme={null}
    # Clean up when done
    await stackone_agent.cleanup()
    await http_client.aclose()
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Python SDK" icon="python" href="/a2a/sdk-guides/python">
    Build custom A2A tools with the Python SDK
  </Card>

  <Card title="JavaScript SDK" icon="js" href="/a2a/sdk-guides/javascript">
    Use the A2A JavaScript SDK
  </Card>

  <Card title="Authentication" icon="shield" href="/a2a/auth-security">
    Learn about authentication and security
  </Card>

  <Card title="Quickstart" icon="rocket" href="/a2a/quickstart">
    Learn A2A basics with cURL
  </Card>
</CardGroup>


# AG2
Source: https://docs.stackone.com/a2a/framework-guides/ag2

Build agents in AG2 that communicate with StackOne's A2A agents using A2aRemoteAgent.

## Overview

[AG2](https://docs.ag2.ai/) (formerly AutoGen) is an open-source framework for building AI agents. AG2 has built-in support for the A2A protocol through `A2aRemoteAgent`, allowing your agents to communicate with remote A2A agents like StackOne's.

Use AG2 to build agents that:

* Consume StackOne's A2A agents as remote agents
* Orchestrate multi-agent conversations with local and remote agents
* Access StackOne platform actions without managing tool definitions

<Warning>
  `A2aRemoteAgent` supports only asynchronous methods - this is a limitation of the A2A client.
</Warning>

## Installation

Install AG2 with A2A support using `pip`:

```bash theme={null}
pip install ag2[a2a]
```

## Quick Start

This example creates a local agent that delegates HR tasks to a StackOne A2A agent.

```python theme={null}
import asyncio
import base64
from autogen import ConversableAgent, LLMConfig
from autogen.a2a import A2aRemoteAgent, HttpxClientFactory

# StackOne A2A configuration
STACKONE_API_KEY = "<stackone_api_key>"
STACKONE_ACCOUNT_ID = "<account_id>"
BASE64_API_KEY = base64.b64encode(f"{STACKONE_API_KEY}:".encode()).decode()

# Create HTTP client with StackOne authentication headers
http_client = HttpxClientFactory(
    headers={
        "Authorization": f"Basic {BASE64_API_KEY}",
        "x-account-id": STACKONE_ACCOUNT_ID
    }
)

# Create a remote A2A agent pointing to StackOne
stackone_agent = A2aRemoteAgent(
    url="https://a2a.stackone.com",
    name="stackone_hr_agent",
    client=http_client
)

# Create a local agent to orchestrate conversations
llm_config = LLMConfig({"model": "gpt-4o-mini"})

orchestrator = ConversableAgent(
    name="hr_assistant",
    system_message="""
        You are an HR assistant that helps with employee management tasks.
        Delegate HR operations to the stackone_hr_agent.

        When the user asks about employees, time off, or other HR data,
        use the stackone_hr_agent to fetch or update the information.
    """,
    llm_config=llm_config,
)

# Start a conversation
async def main():
    await orchestrator.a_initiate_chat(
        recipient=stackone_agent,
        message={"role": "user", "content": "List the first 5 employees"}
    )

asyncio.run(main())
```

See [Authentication Guide](/a2a/auth-security) for details on obtaining your API key and account ID.

## Architecture

AG2's `A2aRemoteAgent` allows your local agent to communicate with remote A2A agents:

```mermaid theme={null}
flowchart LR
    User[User] --> LocalAgent[Local Agent<br/>AG2]
    LocalAgent -->|A2A Protocol| StackOneA2A[StackOne A2A Agent]
    StackOneA2A --> Providers[(Connected SaaS<br/>HiBob, Workday, etc.)]
    LocalAgent --> LocalTools[Local Tools<br/>Optional]

    style StackOneA2A fill:#10b981,stroke:#059669,color:#fff
```

## Complete Example

Here's a complete example with a local tool and a remote StackOne agent:

```python theme={null}
import asyncio
import base64
from datetime import datetime
from autogen import ConversableAgent, LLMConfig
from autogen.a2a import A2aRemoteAgent, HttpxClientFactory

# Configuration
STACKONE_API_KEY = "<stackone_api_key>"
STACKONE_ACCOUNT_ID = "<account_id>"
BASE64_API_KEY = base64.b64encode(f"{STACKONE_API_KEY}:".encode()).decode()

# Local tool example
def get_current_date() -> str:
    """Get the current date."""
    return datetime.now().strftime("%Y-%m-%d")

# Create HTTP client with StackOne authentication headers
http_client = HttpxClientFactory(
    headers={
        "Authorization": f"Basic {BASE64_API_KEY}",
        "x-account-id": STACKONE_ACCOUNT_ID
    }
)

# Remote StackOne A2A agent
stackone_agent = A2aRemoteAgent(
    url="https://a2a.stackone.com",
    name="stackone_hr_agent",
    client=http_client
)

# Configure local agent with LLM
llm_config = LLMConfig({"model": "gpt-4o-mini"})

# Root orchestrator agent
orchestrator = ConversableAgent(
    name="hr_assistant",
    system_message="""
        You are an HR assistant that helps with employee management tasks.

        You have access to:
        1. get_current_date - Get today's date
        2. stackone_hr_agent - Delegate HR operations (employees, time off, etc.)

        When users ask about HR data, delegate to stackone_hr_agent.
        Always confirm actions before making changes.
    """,
    llm_config=llm_config,
)

# Register local tool
orchestrator.register_for_llm(name="get_current_date", description="Get the current date")(get_current_date)

async def main():
    # Start conversation with StackOne agent
    await orchestrator.a_initiate_chat(
        recipient=stackone_agent,
        message={"role": "user", "content": "List all employees"}
    )

    # Print the conversation history
    messages = orchestrator.chat_messages[stackone_agent.name]
    for message in messages:
        print(f"{message['name']}: {message['content']}")

asyncio.run(main())
```

## Creating from AgentCard

If you already have an `AgentCard` (e.g., fetched from a discovery service), create an `A2aRemoteAgent` directly from it:

```python theme={null}
from a2a.types import AgentCard, AgentCapabilities
from autogen.a2a import A2aRemoteAgent

# Create or fetch an AgentCard
card = AgentCard(
    name="stackone_hr_agent",
    url="https://a2a.stackone.com",
    description="Agent that handles HR operations via StackOne integrations",
    version="0.1.0",
    default_input_modes=["text"],
    default_output_modes=["text"],
    capabilities=AgentCapabilities(streaming=True),
    skills=[],
    supports_authenticated_extended_card=False,
)

# Create the remote agent from the card
stackone_agent = A2aRemoteAgent.from_card(card)
```

## Human in the Loop Support

`A2aRemoteAgent` automatically handles Human in the Loop (HITL) interactions when the remote agent requests human input. This happens transparently - the client loops until the agent completes its task or the conversation terminates.

```python theme={null}
from autogen.a2a import A2aRemoteAgent

# Connect to a remote agent that may request human input
stackone_agent = A2aRemoteAgent(
    url="https://a2a.stackone.com",
    name="approval_agent",
    client=http_client
)

# The client automatically handles any human input requests
await orchestrator.a_initiate_chat(
    recipient=stackone_agent,
    message={"role": "user", "content": "Should I approve this budget proposal?"}
)
# If the remote agent requests input, the user will be prompted automatically
```

## Multiple StackOne Accounts

Connect to multiple StackOne accounts by creating separate HTTP clients and `A2aRemoteAgent` instances:

```python theme={null}
import base64
from autogen import ConversableAgent, LLMConfig
from autogen.a2a import A2aRemoteAgent, HttpxClientFactory

STACKONE_API_KEY = "<stackone_api_key>"
BASE64_API_KEY = base64.b64encode(f"{STACKONE_API_KEY}:".encode()).decode()

# HTTP client for HiBob account
hibob_http_client = HttpxClientFactory(
    headers={
        "Authorization": f"Basic {BASE64_API_KEY}",
        "x-account-id": "<hibob_account_id>"
    }
)

# HTTP client for BambooHR account
bamboo_http_client = HttpxClientFactory(
    headers={
        "Authorization": f"Basic {BASE64_API_KEY}",
        "x-account-id": "<bamboohr_account_id>"
    }
)

# Agent for HiBob integration
hibob_agent = A2aRemoteAgent(
    url="https://a2a.stackone.com",
    name="hibob_agent",
    client=hibob_http_client
)

# Agent for BambooHR integration
bamboo_agent = A2aRemoteAgent(
    url="https://a2a.stackone.com",
    name="bamboo_agent",
    client=bamboo_http_client
)

# Orchestrator with access to both agents
llm_config = LLMConfig({"model": "gpt-4o-mini"})

orchestrator = ConversableAgent(
    name="multi_hr_assistant",
    system_message="""
        You have access to multiple HR systems:
        - hibob_agent: For HiBob HR operations
        - bamboo_agent: For BambooHR operations

        Route requests to the appropriate system based on user context.
    """,
    llm_config=llm_config,
)
```

## Advanced Configuration

### Custom HTTP Client

Set custom options on the HTTP client such as headers and timeout:

```python theme={null}
from autogen.a2a import A2aRemoteAgent, HttpxClientFactory

# Create custom HTTP client factory
http_client = HttpxClientFactory(
    timeout=30.0,
    headers={
        "User-Agent": "MyApp/1.0",
        "Authorization": f"Basic {BASE64_API_KEY}",
        "x-account-id": STACKONE_ACCOUNT_ID
    }
)

stackone_agent = A2aRemoteAgent(
    url="https://a2a.stackone.com",
    name="stackone_hr_agent",
    client=http_client
)
```

### Client Configuration

Pass additional client configuration using `ClientConfig`:

```python theme={null}
from a2a.client import ClientConfig
from autogen.a2a import A2aRemoteAgent

stackone_agent = A2aRemoteAgent(
    url="https://a2a.stackone.com",
    name="stackone_hr_agent",
    client=http_client,
    client_config=ClientConfig(streaming=True),
)
```

### Testing with MockClient

Mock remote agent replies for testing:

```python theme={null}
from autogen.a2a import A2aRemoteAgent, MockClient

stackone_agent = A2aRemoteAgent(
    url="https://a2a.stackone.com",
    name="stackone_hr_agent",
    client=MockClient(response_message="Mock response for testing"),
)
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use Async Methods" icon="bolt">
    `A2aRemoteAgent` only supports asynchronous methods. Always use `a_initiate_chat` and other async methods:

    ```python theme={null}
    # Correct: Use async methods
    await orchestrator.a_initiate_chat(
        recipient=stackone_agent,
        message={"role": "user", "content": "List employees"}
    )

    # Incorrect: Sync methods won't work
    # orchestrator.initiate_chat(...)  # This will fail
    ```
  </Accordion>

  <Accordion title="Clear System Messages" icon="file-lines">
    Provide detailed system messages for your orchestrator agent. Include clear instructions about when to delegate to remote agents:

    ```python theme={null}
    orchestrator = ConversableAgent(
        name="hr_assistant",
        system_message="""
            You are an HR assistant. When users ask about:
            - Employee data -> delegate to stackone_hr_agent
            - Time off requests -> delegate to stackone_hr_agent
            - Local operations -> use local tools

            Always confirm before making changes to HR systems.
        """,
        llm_config=llm_config,
    )
    ```
  </Accordion>

  <Accordion title="Error Handling" icon="triangle-exclamation">
    Wrap A2A calls in try-except blocks to handle network or protocol errors:

    ```python theme={null}
    async def safe_hr_query(message: str):
        try:
            await orchestrator.a_initiate_chat(
                recipient=stackone_agent,
                message={"role": "user", "content": message}
            )
        except Exception as e:
            print(f"Error communicating with HR agent: {e}")
            # Handle fallback logic
    ```
  </Accordion>

  <Accordion title="Message Format" icon="message">
    Always provide messages in the correct format with `role` and `content`:

    ```python theme={null}
    # Correct format
    await orchestrator.a_initiate_chat(
        recipient=stackone_agent,
        message={"role": "user", "content": "List employees"}
    )

    # Also valid: just content string
    await orchestrator.a_initiate_chat(
        recipient=stackone_agent,
        message="List employees"
    )
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Python SDK" icon="python" href="/a2a/sdk-guides/python">
    Build custom A2A tools with the Python SDK
  </Card>

  <Card title="JavaScript SDK" icon="js" href="/a2a/sdk-guides/javascript">
    Use the A2A JavaScript SDK
  </Card>

  <Card title="Authentication" icon="shield" href="/a2a/auth-security">
    Learn about authentication and security
  </Card>

  <Card title="Quickstart" icon="rocket" href="/a2a/quickstart">
    Learn A2A basics with cURL
  </Card>
</CardGroup>


# BeeAI Framework
Source: https://docs.stackone.com/a2a/framework-guides/beeai

Build agents in BeeAI Framework that communicate with StackOne's A2A agents using A2AAgent.

## Overview

The [BeeAI Framework](https://framework.beeai.dev/) is an open-source framework for building AI agents, developed under the Linux Foundation. BeeAI has built-in support for the A2A protocol through `A2AAgent`, allowing your agents to communicate with remote A2A agents like StackOne's.

Use BeeAI Framework to build agents that:

* Consume StackOne's A2A agents as remote agents
* Orchestrate multi-agent systems with local and remote agents
* Access StackOne platform actions without managing tool definitions

<Note>
  **Python only**: BeeAI Framework's `A2AAgent` supports custom authentication headers required for StackOne in Python. For TypeScript, use the [A2A JavaScript SDK](/a2a/sdk-guides/javascript) directly.
</Note>

## Installation

Install BeeAI Framework with A2A support:

```bash theme={null}
pip install beeai-framework[a2a]
```

## Quick Start

This example creates an `A2AAgent` that connects to a StackOne A2A agent.

```python theme={null}
import asyncio
import base64
from beeai_framework.adapters.a2a.agents import A2AAgent, A2AAgentParameters, HttpxAsyncClientParameters
from beeai_framework.memory.unconstrained_memory import UnconstrainedMemory

# StackOne A2A configuration
STACKONE_API_KEY = "<stackone_api_key>"
STACKONE_ACCOUNT_ID = "<account_id>"
BASE64_API_KEY = base64.b64encode(f"{STACKONE_API_KEY}:".encode()).decode()

async def main():
    # Create A2A agent with StackOne authentication
    agent = A2AAgent(
        url="https://a2a.stackone.com",
        memory=UnconstrainedMemory(),
        parameters=A2AAgentParameters(
            httpx_async_client=HttpxAsyncClientParameters(
                headers={
                    "Authorization": f"Basic {BASE64_API_KEY}",
                    "x-account-id": STACKONE_ACCOUNT_ID
                }
            )
        )
    )

    # Send a message and get the response
    response = await agent.run("List the first 5 employees")
    print(f"Agent response: {response.last_message.text}")

asyncio.run(main())
```

See [Authentication Guide](/a2a/auth-security) for details on obtaining your API key and account ID.

## Architecture

BeeAI's `A2AAgent` allows your application to communicate with remote A2A agents:

```mermaid theme={null}
flowchart LR
    App[Your Application] --> A2AAgent[A2AAgent<br/>BeeAI Framework]
    A2AAgent -->|A2A Protocol| StackOneA2A[StackOne A2A Agent]
    StackOneA2A --> Providers[(Connected SaaS<br/>HiBob, Workday, etc.)]

    style StackOneA2A fill:#10b981,stroke:#059669,color:#fff
```

## Complete Example with Event Handling

Here's a complete example that handles events and debug information:

```python theme={null}
import asyncio
import base64
from beeai_framework.adapters.a2a.agents import A2AAgent, A2AAgentUpdateEvent, A2AAgentParameters, HttpxAsyncClientParameters
from beeai_framework.emitter import EventMeta
from beeai_framework.memory.unconstrained_memory import UnconstrainedMemory
from beeai_framework.errors import FrameworkError

# Configuration
STACKONE_API_KEY = "<stackone_api_key>"
STACKONE_ACCOUNT_ID = "<account_id>"
BASE64_API_KEY = base64.b64encode(f"{STACKONE_API_KEY}:".encode()).decode()

async def main():
    # Create A2A agent with StackOne authentication
    agent = A2AAgent(
        url="https://a2a.stackone.com",
        memory=UnconstrainedMemory(),
        parameters=A2AAgentParameters(
            httpx_async_client=HttpxAsyncClientParameters(
                headers={
                    "Authorization": f"Basic {BASE64_API_KEY}",
                    "x-account-id": STACKONE_ACCOUNT_ID
                }
            )
        )
    )

    # Define event handler for progress updates
    def handle_update(data: A2AAgentUpdateEvent, event: EventMeta) -> None:
        value = data.value
        debug_info = value[1] if isinstance(value, tuple) else value
        print(f"Agent progress: {debug_info}")

    # Run the agent with event handling
    try:
        response = await agent.run("List the first 5 employees").on("update", handle_update)
        print(f"\nAgent response: {response.last_message.text}")
    except FrameworkError as e:
        print(f"Error: {e.explain()}")

asyncio.run(main())
```

## Interactive Chat Loop

Create an interactive chat session with the StackOne agent:

```python theme={null}
import asyncio
import base64
from beeai_framework.adapters.a2a.agents import A2AAgent, A2AAgentParameters, HttpxAsyncClientParameters
from beeai_framework.memory.unconstrained_memory import UnconstrainedMemory

STACKONE_API_KEY = "<stackone_api_key>"
STACKONE_ACCOUNT_ID = "<account_id>"
BASE64_API_KEY = base64.b64encode(f"{STACKONE_API_KEY}:".encode()).decode()

async def main():
    agent = A2AAgent(
        url="https://a2a.stackone.com",
        memory=UnconstrainedMemory(),
        parameters=A2AAgentParameters(
            httpx_async_client=HttpxAsyncClientParameters(
                headers={
                    "Authorization": f"Basic {BASE64_API_KEY}",
                    "x-account-id": STACKONE_ACCOUNT_ID
                }
            )
        )
    )

    print("Connected to StackOne A2A Agent. Type 'quit' to exit.\n")

    while True:
        user_input = input("You: ").strip()
        if user_input.lower() == "quit":
            break

        response = await agent.run(user_input)
        print(f"Agent: {response.last_message.text}\n")

asyncio.run(main())
```

## Multiple StackOne Accounts

Connect to multiple StackOne accounts by creating separate `A2AAgent` instances:

```python theme={null}
import base64
from beeai_framework.adapters.a2a.agents import A2AAgent, A2AAgentParameters, HttpxAsyncClientParameters
from beeai_framework.memory.unconstrained_memory import UnconstrainedMemory

STACKONE_API_KEY = "<stackone_api_key>"
BASE64_API_KEY = base64.b64encode(f"{STACKONE_API_KEY}:".encode()).decode()

# Agent for HiBob integration
hibob_agent = A2AAgent(
    url="https://a2a.stackone.com",
    memory=UnconstrainedMemory(),
    parameters=A2AAgentParameters(
        httpx_async_client=HttpxAsyncClientParameters(
            headers={
                "Authorization": f"Basic {BASE64_API_KEY}",
                "x-account-id": "<hibob_account_id>"
            }
        )
    )
)

# Agent for BambooHR integration
bamboo_agent = A2AAgent(
    url="https://a2a.stackone.com",
    memory=UnconstrainedMemory(),
    parameters=A2AAgentParameters(
        httpx_async_client=HttpxAsyncClientParameters(
            headers={
                "Authorization": f"Basic {BASE64_API_KEY}",
                "x-account-id": "<bamboohr_account_id>"
            }
        )
    )
)

async def query_multiple_systems():
    # Query HiBob
    hibob_response = await hibob_agent.run("List all employees")
    print(f"HiBob: {hibob_response.last_message.text}")

    # Query BambooHR
    bamboo_response = await bamboo_agent.run("List all employees")
    print(f"BambooHR: {bamboo_response.last_message.text}")
```

## Memory Management

BeeAI Framework provides memory implementations for conversation history:

```python theme={null}
from beeai_framework.adapters.a2a.agents import A2AAgent, A2AAgentParameters, HttpxAsyncClientParameters
from beeai_framework.memory.unconstrained_memory import UnconstrainedMemory

# UnconstrainedMemory: Keeps all messages (default choice)
agent = A2AAgent(
    url="https://a2a.stackone.com",
    memory=UnconstrainedMemory(),
    parameters=A2AAgentParameters(
        httpx_async_client=HttpxAsyncClientParameters(
            headers={
                "Authorization": f"Basic {BASE64_API_KEY}",
                "x-account-id": STACKONE_ACCOUNT_ID
            }
        )
    )
)

# Clear memory to start a new conversation
async def start_new_conversation():
    agent.memory = UnconstrainedMemory()  # Memory must be empty before setting
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use Appropriate Memory" icon="brain">
    Choose the right memory implementation for your use case:

    ```python theme={null}
    from beeai_framework.memory.unconstrained_memory import UnconstrainedMemory

    agent = A2AAgent(
        url="https://a2a.stackone.com",
        memory=UnconstrainedMemory(),
        # ...
    )
    ```

    Use `UnconstrainedMemory` for typical interactions. Memory must be empty when assigned to an agent.
  </Accordion>

  <Accordion title="Handle Events for Debugging" icon="bug">
    Subscribe to update events for debugging and progress tracking:

    ```python theme={null}
    def handle_update(data: A2AAgentUpdateEvent, event: EventMeta) -> None:
        print(f"Debug: {data.value}")

    response = await agent.run("Query").on("update", handle_update)
    ```

    This is especially useful for understanding agent behavior during development.
  </Accordion>

  <Accordion title="Error Handling" icon="triangle-exclamation">
    Wrap agent calls in try-except blocks to handle errors gracefully:

    ```python theme={null}
    from beeai_framework.errors import FrameworkError
    from beeai_framework.agents import AgentError

    try:
        response = await agent.run("List employees")
    except AgentError as e:
        print(f"Agent error: {e}")
        # Handle agent-specific errors
    except FrameworkError as e:
        print(f"Framework error: {e.explain()}")
        # Handle framework errors
    ```
  </Accordion>

  <Accordion title="Context Management" icon="arrows-rotate">
    Use context IDs and task IDs to manage multi-turn conversations:

    ```python theme={null}
    # Start a new conversation
    response = await agent.run(
        "List employees",
        clear_context=True  # Clears previous context
    )

    # Continue an existing conversation (uses stored context)
    follow_up = await agent.run("Tell me more about the first employee")
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Python SDK" icon="python" href="/a2a/sdk-guides/python">
    Build custom A2A tools with the Python SDK
  </Card>

  <Card title="JavaScript SDK" icon="js" href="/a2a/sdk-guides/javascript">
    Use the A2A JavaScript SDK
  </Card>

  <Card title="Authentication" icon="shield" href="/a2a/auth-security">
    Learn about authentication and security
  </Card>

  <Card title="Quickstart" icon="rocket" href="/a2a/quickstart">
    Learn A2A basics with cURL
  </Card>
</CardGroup>


# StackOne A2A Agents
Source: https://docs.stackone.com/a2a/introduction

Connect to agents built for StackOne platform actions in code or multi-agent systems via the Agent2Agent (A2A) Protocol.

<Warning>
  **Open Beta Feature**: StackOne A2A agents are currently in open beta. While fully functional, the API and features may evolve based on user feedback.
</Warning>

**[Agent2Agent (A2A)](https://a2a-protocol.org/latest/)** is an open protocol that standardizes agent communication, i.e. sending and receiving messages in any format (text, audio, images, files, etc.), discovery, collaboration, authentication, etc.
Essentially, if MCP provides a standard interface for agents to use tools, A2A provides a standard interface for users and agents to use agents.

StackOne provides **production-ready A2A agents** for each linked account, giving you and your AI agents direct access to agents built for StackOne platform actions. See the complete list at [stackone.com/integrations](https://www.stackone.com/integrations).

<Tip>
  **Not sure if A2A is right for you?** Check out our [Agent Protocols Guide](/guides/calling-stackone-actions) to understand when to use A2A vs MCP vs AI Toolset (SDK).
</Tip>

<Accordion title="A2A 101: Understanding the Protocol" icon="graduation-cap">
  **What is A2A?** The Agent2Agent (A2A) Protocol is an open standard originally developed by Google and now maintained by the Linux Foundation. It defines how AI agents discover each other, authenticate, and exchange messages - regardless of what framework they were built with or who built them. Think of it as a common language that lets any agent talk to any other agent.

  **Why does A2A exist?** Without a standard protocol, connecting agents requires custom integrations for every pair of agents. A2A solves this by providing a single, universal interface. Your agent built with LangGraph can collaborate with an agent built with CrewAI, ADK, or any other framework - all using the same protocol.

  **How does it work?** A2A uses familiar web standards: HTTP for transport, JSON-RPC 2.0 for message format, and standard authentication methods. Agents publish an **Agent Card** (a JSON document describing their capabilities and skills) at a well-known URL. Clients fetch this card to discover what an agent can do, then send **Messages** to request work. The agent processes the request and returns either a direct response or a **Task** for longer-running operations.

  **A2A vs MCP**: These protocols are complementary, not competing. MCP (Model Context Protocol) standardizes how agents connect to **tools** - stateless functions like calculators or database queries. A2A standardizes how agents communicate with **other agents** - autonomous systems that can reason, plan, and have multi-turn conversations. Use MCP when you need tools; use A2A when you need to collaborate with other agents.
</Accordion>

**Simplified Authentication**: Authentication to third-party providers is completely abstracted - you only need your StackOne API key and account ID to access all integrated systems. Accounts must be linked beforehand through the [StackOne Integration Hub](/guides/accounts-section) or via [auth links](/guides/auth-link).

## A2A or MCP?

You can use StackOne platform actions not only with A2A agents, but also with [MCP Servers](/mcp/quickstart) and the [Actions endpoint](/platform/api-reference/actions/make-an-rpc-call-to-an-action).

Ultimately, experimentation is the best way to decide for your use case. However, here are some reasons you might try A2A vs. MCP:

<AccordionGroup>
  <Accordion title="Quick Setup" icon="bolt-lightning">
    A2A agents are pre-built agents that are ready to go. No need to set up agent deployment, memory, etc. Just send text directly to the relevant agent with your StackOne API key and account ID.
  </Accordion>

  <Accordion title="Multi-agent Systems" icon="network-wired">
    Create a multi-agent system with a single agent in your preferred framework. Just set up your custom orchestrator agent with the A2A MCP.
  </Accordion>

  <Accordion title="Complex Projects" icon="diagram-project">
    Context bloat reduces the reliability of complex projects. Replacing tools with agents keeps tool calls out of the context, and improves accuracy and maintainability as your system grows.
  </Accordion>
</AccordionGroup>

<Note>
  StackOne lets your agents discover and execute business actions with minimal setup, secured by unified enterprise authentication.
</Note>

## How StackOne A2A Works

```mermaid theme={null}
flowchart LR
    Client[A2A Client/Agent] <-->|JSON-RPC 2.0| StackOneA2A[StackOne A2A Agent]
    StackOneA2A <-->|MCP Streamable HTTP| StackOneMCP[StackOne MCP Server]
    StackOneMCP <-->|tools/list| Toolset[StackOne Tool Catalog]
    StackOneMCP <-->|tools/call| Providers[(Connected SaaS APIs)]
    IntegrationConfig[Integration & Account Settings] -->|Defines available tools| Toolset

    style StackOneA2A fill:#10b981,stroke:#059669,color:#fff
    style StackOneMCP fill:#10b981,stroke:#059669,color:#fff
    style Toolset fill:#10b981,stroke:#059669,color:#fff
    style IntegrationConfig fill:#10b981,stroke:#059669,color:#fff
```

When you send your StackOne API key and account ID to `https://a2a.stackone.com` to use the agent, its system message and [MCP server](/mcp/quickstart) are dynamically generated based on your account's configured integrations and enabled actions in the StackOne dashboard.

<Note>
  **Agent Card Routes:**

  * **For connecting to agents:** Always use `https://a2a.stackone.com/.well-known/agent-card.json`. This route dynamically loads the agent card based on your account's configured integrations and enabled actions.
  * **For viewing available skills:** Connector-specific routes like `https://a2a.stackone.com/hibob/agent-card.json` are available for inspecting all available skills for a specific connector. These are for reference only and should not be used for agent connections.
</Note>

## Key Features

* **Ready to Use**: Pre-built agents with memory, etc.
* **Agent per Integration**: Each StackOne Integration (aka Provider or Connector) has its own A2A agent
* **Automatically Customised**: The A2A agent is dynamically generated based on your account's configured integrations and enabled actions
* **Production Ready**: Authentication, rate limiting, and security built-in

## Getting Started

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/a2a/quickstart">
    Get started with the A2A UI and cURL
  </Card>

  <Card title="Authentication" icon="shield" href="/a2a/auth-security">
    Learn about headers, authentication, and security
  </Card>

  <Card title="SDK Guides" icon="code" href="/a2a/sdk-guides/python">
    Use the official A2A SDKs to build your own tools
  </Card>

  <Card title="Agent Guides" icon="robot" href="/a2a/framework-guides/adk">
    Build agents in frameworks with A2A integrations
  </Card>
</CardGroup>

## Integration Options

StackOne A2A agents can be used in two ways, depending on your use case:

### A2A SDK

There are official A2A SDKs for [Python](https://github.com/a2aproject/a2a-python), [JavaScript](https://github.com/a2aproject/a2a-js), [Go](https://github.com/a2aproject/a2a-go), and [more](https://github.com/orgs/a2aproject/repositories). Use these to **build your own tools** in your preferred framework to send messages to StackOne's A2A agents.

<Note>
  See a complete working example in the [StackOne A2A Agents Orchestrator Demo](https://github.com/StackOneHQ/a2a-demo), which shows how to build an orchestrator agent that routes requests to multiple StackOne A2A agents using the JavaScript SDK.
</Note>

### Agent Frameworks

There are official A2A integrations for [Agent Development Kit (ADK)](https://google.github.io/adk-docs/a2a/), [AG2](https://docs.ag2.ai/latest/docs/user-guide/a2a/), [BeeAI Framework](https://framework.beeai.dev/integrations/a2a), and [more](https://framework.beeai.dev/integrations/a2a). Build agents in these frameworks to easily send messages to StackOne's A2A agents.

## Next Steps

Ready to connect your AI agents to StackOne? Start with our [Quickstart Guide](/a2a/quickstart) or jump directly to the [A2A Python SDK](https://github.com/a2aproject/a2a-python), [A2A JavaScript SDK](https://github.com/a2aproject/a2a-js), or your preferred framework.

For more information about StackOne's platform capabilities, see our [AI Tools documentation](/agents/typescript/introduction).


# A2A Quickstart
Source: https://docs.stackone.com/a2a/quickstart

Get started with StackOne's A2A agents with the A2A UI, and use cURL to retrieve an Agent Card, send a Message, and get a Task.

## Overview

StackOne provides an A2A agent for each integration at:

<CodeGroup>
  ```bash theme={null}
  https://a2a.stackone.com
  ```
</CodeGroup>

**Authentication**: All requests require Basic authentication (`Authorization` header with base64-encoded API key) and your StackOne account ID (`x-account-id` header).

This guide walks you through the basic A2A operations to help you understand the protocol before integrating with your preferred agent framework.

***

## Quick Testing Options

Choose your preferred testing method to get started with StackOne's A2A agents:

<AccordionGroup>
  <Accordion title="🎮 StackOne A2A UI (Recommended)" icon="ui">
    ### Interactive Testing Interface

    You can go to [a2a-ui.stackone.com](https://a2a-ui.stackone.com) and interact with StackOne agents directly in your browser.

    **Getting Started:**

    1. Go to [a2a-ui.stackone.com](https://a2a-ui.stackone.com)
    2. Click the Settings "⚙️" icon and enter your StackOne API key and account ID (see our [Authentication Guide](/a2a/auth-security) for details)
    3. Click the "+ Agent" button, enter `https://a2a.stackone.com/.well-known/agent-card.json`, and click "Add Agent"
    4. Start chatting with the agent!

    <Note>
      The response you get from `https://a2a.stackone.com/.well-known/agent-card.json` will depend on the `Authorization` and `x-account-id` headers you use. The A2A agent is dynamically generated based on your account's configured integrations and enabled actions.
    </Note>

    <Tip>
      This is the fastest way to test A2A functionality without any setup!
    </Tip>
  </Accordion>

  <Accordion title="💻 cURL Testing (Command Line)" icon="terminal">
    ### Programmatic Testing

    Perfect for developers who prefer command-line tools or want to integrate A2A into scripts.

    #### Step 1: Get an Agent Card

    Before interacting with an agent, you can fetch its Agent Card to understand its capabilities, skills, and authentication requirements. Agent Cards are available at the standard `.well-known` URI path:

    ```bash theme={null}
    curl -X GET https://a2a.stackone.com/.well-known/agent-card.json \
      -H 'Authorization: Basic <BASE64_APIKEY_COLON>' \
      -H 'x-account-id: <ACCOUNT_ID>'
    ```

    **Example Response:**

    ```json theme={null}
    {
      "name": "StackOne HiBob",
      "description": "HiBob connector",
      "iconUrl": "https://stackone-logos.com/api/hibob/icon/svg",
      "protocolVersion": "0.3.4",
      "version": "0.1.0",
      "url": "https://a2a.stackone.com",
      "skills": [
        {
          "id": "hibob_list_employees",
          "name": "List Employees",
          "description": "Get A List Of Employees",
          "tags": [
            "stackone",
            "hibob",
          ]
        },
        {
          "id": "hibob_get_employee",
          "name": "Get Employee",
          "description": "Get Details Of A Specific Employee",
          "tags": [
            "stackone",
            "hibob",
          ]
        },
        {
          "id": "hibob_update_employee",
          "name": "Update Employee",
          "description": "Update Employee Information",
          "tags": [
            "stackone",
            "hibob",
          ]
        }
      ],
      "capabilities": {
        "streaming": true
      },
      "defaultInputModes": [
        "text/plain"
      ],
      "defaultOutputModes": [
        "text/plain"
      ]
    }
    ```

    <Note>
      The response you get from `https://a2a.stackone.com/.well-known/agent-card.json` will depend on the `Authorization` and `x-account-id` headers you use. The A2A agent is dynamically generated based on your account's configured integrations and enabled actions.
    </Note>

    <Note>
      **Agent Card Routes:**

      * **For connecting to agents:** Always use `https://a2a.stackone.com/.well-known/agent-card.json`. This route dynamically loads the agent card based on your account's configured integrations and enabled actions.
      * **For viewing available skills:** Connector-specific routes like `https://a2a.stackone.com/hibob/agent-card.json` are available for inspecting all available skills for a specific connector. These are for reference only and should not be used for agent connections.
    </Note>

    ***

    #### Step 2: Send a Message

    The `message/send` method sends a message to an agent to initiate a new interaction or continue an existing one. Each message requires a unique `messageId` (a UUID):

    <Tip>
      Replace `messageId` with a unique UUID for each request. On macOS/Linux: `uuidgen | tr '[:upper:]' '[:lower:]'`
    </Tip>

    ```bash theme={null}
    curl -X POST https://a2a.stackone.com \
      -H 'Authorization: Basic <BASE64_APIKEY_COLON>' \
      -H 'x-account-id: <ACCOUNT_ID>' \
      -H 'Content-Type: application/json' \
      -d '{
        "jsonrpc": "2.0",
        "id": "msg-1",
        "method": "message/send",
        "params": {
          "message": {
            "messageId": "550e8400-e29b-41d4-a716-446655440000",
            "role": "user",
            "parts": [
              {
                "kind": "text",
                "text": "List the first 10 employees"
              }
            ],
            "kind": "message"
          },
          "configuration": {
            "blocking": true
          }
        }
      }'
    ```

    **Expected Response:**

    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "id": "msg-1",
      "result": {
        "id": "task-123",
        "contextId": "ctx-456",
        "status": "completed",
        "artifacts": [
          {
            "id": "artifact-1",
            "kind": "text",
            "parts": [
              {
                "kind": "text",
                "text": "Here are the first 10 employees:\n1. John Doe - Software Engineer\n2. Jane Smith - Product Manager\n3. Bob Johnson - HR Specialist\n..."
              }
            ]
          }
        ],
        "history": [
          {
            "role": "user",
            "parts": [
              {
                "kind": "text",
                "text": "List the first 10 employees"
              }
            ]
          }
        ]
      }
    }
    ```

    <Note>
      Pass `"configuration": { "blocking": false }` and poll `tasks/get` continuously for long-running operations.
    </Note>

    ***

    #### Step 3: Get Task Status

    Use `tasks/get` to retrieve the current state of a task (useful for long-running operations):

    ```bash theme={null}
    curl -X POST https://a2a.stackone.com \
      -H 'Authorization: Basic <BASE64_APIKEY_COLON>' \
      -H 'x-account-id: <ACCOUNT_ID>' \
      -H 'Content-Type: application/json' \
      -d '{
        "jsonrpc": "2.0",
        "id": "task-query-1",
        "method": "tasks/get",
        "params": {
          "id": "task-123"
        }
      }'
    ```

    **Expected Response:**

    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "id": "task-query-1",
      "result": {
        "id": "task-123",
        "contextId": "ctx-456",
        "status": "completed",
        "artifacts": [
          {
            "id": "artifact-1",
            "kind": "text",
            "parts": [
              {
                "kind": "text",
                "text": "Here are the first 10 employees:\n1. John Doe - Software Engineer\n2. Jane Smith - Product Manager\n3. Bob Johnson - HR Specialist\n..."
              }
            ]
          }
        ],
        "history": [
          {
            "role": "user",
            "parts": [
              {
                "kind": "text",
                "text": "List the first 10 employees"
              }
            ]
          }
        ]
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

Now that you understand the basic A2A operations, choose your integration path:

<CardGroup>
  <Card title="SDK Guides" icon="code" href="/a2a/sdk-guides/python">
    Use the official A2A SDKs to build your own tools
  </Card>

  <Card title="Agent Guides" icon="robot" href="/a2a/framework-guides/adk">
    Build agents in frameworks with A2A integrations
  </Card>
</CardGroup>

## Common Issues & Solutions

<AccordionGroup>
  <Accordion title="401/403 Authentication Error">
    <Steps>
      <Step>
        Verify your API key is correctly base64 encoded in the Authorization header
      </Step>

      <Step>
        Confirm that the `x-account-id` header matches your linked account ID, and ensure the account belongs to the same project as your API key
      </Step>

      <Step>
        Remember: A2A does not support query parameters for authentication, only headers
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Agent has no skills">
    <Steps>
      <Step>
        Check that the account is active (i.e., is not in an error state or otherwise disabled)
      </Step>

      <Step>
        Verify your integrations are properly configured (agent skills are generated based on the enabled actions for the integration configuration associated with the linked account)
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>


# A2A JavaScript SDK
Source: https://docs.stackone.com/a2a/sdk-guides/javascript

Build agents that communicate with StackOne's A2A agents using the official A2A JavaScript SDK.

## Overview

The [A2A JavaScript SDK](https://github.com/google-a2a/a2a-js) provides a JavaScript/TypeScript client library for building agents that interact with A2A agents following the [Agent2Agent (A2A) Protocol](https://a2a-protocol.org).

Use this SDK to build agents that:

* Discover and connect to StackOne's A2A agents
* Send messages and receive responses
* Manage multi-turn conversations with context

## Installation

Install the A2A SDK using `npm`:

```bash theme={null}
npm install @a2a-js/sdk
```

## Quick Start

Get an Agent Card, send a Message, and print the response.

```typescript theme={null}
import { A2AClient, SendMessageSuccessResponse } from '@a2a-js/sdk/client';
import { Message, MessageSendParams } from '@a2a-js/sdk';
import { v4 as uuidv4 } from 'uuid';

const STACKONE_API_KEY = '<stackone_api_key>';
const STACKONE_ACCOUNT_ID = '<account_id>';

// Base64 encode the API key (with trailing colon for Basic auth)
const base64EncodedApiKey = Buffer.from(`${STACKONE_API_KEY}:`).toString('base64');

async function main() {
  // Create a custom fetch that adds authentication headers
  const authenticatedFetch: typeof fetch = async (url, init) => {
    const headers = new Headers(init?.headers);
    headers.set('Authorization', `Basic ${base64EncodedApiKey}`);
    headers.set('x-account-id', STACKONE_ACCOUNT_ID);
    return fetch(url, { ...init, headers });
  };

  // Create a client pointing to the StackOne A2A Agent Card URL
  const client = await A2AClient.fromCardUrl(
    'https://a2a.stackone.com/.well-known/agent-card.json',
    { fetchImpl: authenticatedFetch }
  );

  // Send a message
  const sendParams: MessageSendParams = {
    message: {
      messageId: uuidv4(),
      role: 'user',
      parts: [{ kind: 'text', text: 'List the first 5 employees' }],
      kind: 'message',
    },
  };

  const response = await client.sendMessage(sendParams);

  if ('error' in response) {
    console.error('Error:', response.error.message);
  } else {
    const result = (response as SendMessageSuccessResponse).result;
    console.log('Agent response:', JSON.stringify(result, null, 2));
  }
}

main();
```

See [Authentication Guide](/a2a/auth-security) for details on obtaining your API key and account ID.

## Getting Agent Cards

During agent initialisation, fetch an Agent Card for every A2A agent you want to send messages to.
This is typically a setup step as opposed to a tool.

<Note>
  Ensure to include the agent information in the agent's context (e.g. system message).
</Note>

```typescript theme={null}
import { A2AClient } from '@a2a-js/sdk/client';
import { AgentCard } from '@a2a-js/sdk';

const STACKONE_API_KEY = '<stackone_api_key>';
const base64EncodedApiKey = Buffer.from(`${STACKONE_API_KEY}:`).toString('base64');

interface AgentCardWithAccountId {
  accountId: string;
  agentCard: AgentCard;
}

/**
 * Fetch Agent Cards from StackOne A2A agents for multiple accounts.
 *
 * The Agent URL is fixed to https://a2a.stackone.com and dynamically loads
 * an Agent Card based on the account ID.
 */
async function fetchAgentCards(accountIds: string[]): Promise<Map<string, AgentCardWithAccountId>> {
  const agentCards = new Map<string, AgentCardWithAccountId>();

  for (const accountId of accountIds) {
    try {
      // Create authenticated fetch for this account
      const authenticatedFetch: typeof fetch = async (url, init) => {
        const headers = new Headers(init?.headers);
        headers.set('Authorization', `Basic ${base64EncodedApiKey}`);
        headers.set('x-account-id', accountId);
        return fetch(url, { ...init, headers });
      };

      const client = await A2AClient.fromCardUrl(
        'https://a2a.stackone.com/.well-known/agent-card.json',
        { fetchImpl: authenticatedFetch }
      );

      const agentCard = client.agentCard;
      agentCards.set(agentCard.name, { accountId, agentCard });
    } catch (error) {
      console.error(`Failed to fetch agent card for account ${accountId}:`, error);
    }
  }

  return agentCards;
}

/**
 * Get A2A agent information for agent context.
 */
function getA2AAgentInfo(agentCards: Map<string, AgentCardWithAccountId>): string {
  const a2aAgentInfo: Array<{ name: string; description: string; skills: string[] }> = [];

  for (const { agentCard } of agentCards.values()) {
    a2aAgentInfo.push({
      name: agentCard.name,
      description: agentCard.description,
      skills: (agentCard.skills || []).map((skill) => skill.name),
    });
  }

  return ['<agents>', JSON.stringify(a2aAgentInfo, null, 4), '</agents>'].join('\n');
}

async function main() {
  // Fetch agent cards from multiple StackOne accounts
  const accountIds = ['<account_id_1>', '<account_id_2>', '<account_id_3>'];
  const agentCards = await fetchAgentCards(accountIds);

  // Get agent information for LLM context (e.g. system message)
  const a2aAgentInfo = getA2AAgentInfo(agentCards);
  console.log(a2aAgentInfo);
}

main();
```

## Sending Messages

To send messages to A2A agents, give your agent access to a tool like below.

<Note>
  The tool below gives the agent relatively high autonomy.
  You might want to abstract context IDs and task IDs outside of the tool.
</Note>

```typescript theme={null}
import { A2AClient, SendMessageSuccessResponse } from '@a2a-js/sdk/client';
import { AgentCard, Message, MessageSendParams, Task } from '@a2a-js/sdk';
import { v4 as uuidv4 } from 'uuid';

const STACKONE_API_KEY = '<stackone_api_key>';
const base64EncodedApiKey = Buffer.from(`${STACKONE_API_KEY}:`).toString('base64');

interface AgentCardWithAccountId {
  accountId: string;
  agentCard: AgentCard;
}

// Map of agent names to their cards and account IDs
const agentCards = new Map<string, AgentCardWithAccountId>();

interface SendMessageResult {
  Message?: {
    messageId: string;
    role: string;
    parts: Array<{ kind: string; text?: string }>;
    contextId?: string;
  };
  Task?: {
    status: { state: string; timestamp: string };
    artifacts: Array<{ artifactId: string; name?: string; parts: Array<{ kind: string; text?: string }> }>;
    contextId: string;
    taskId: string;
  };
  error?: { code: number; message: string };
}

/**
 * Send a message to an agent and receive a response.
 * The response can be a Task, Message, or Error.
 *
 * To start a new conversation, set `contextId` and `taskId` to undefined.
 *
 * To continue a conversation, set `contextId` to the `contextId` of the previous conversation.
 *   - If the previous Task has not terminated (input_required, auth_required),
 *     set `taskId` to the `taskId` of the previous Task.
 *   - If the previous Task has terminated (completed, canceled, rejected, or failed),
 *     set `taskId` to undefined.
 */
async function sendMessageToAgent(
  agentName: string,
  message: string,
  contextId?: string,
  taskId?: string
): Promise<SendMessageResult> {
  const agentEntry = agentCards.get(agentName);

  if (!agentEntry) {
    throw new Error(`Agent ${agentName} not found`);
  }

  const { accountId, agentCard } = agentEntry;

  // Create authenticated fetch for this account
  const authenticatedFetch: typeof fetch = async (url, init) => {
    const headers = new Headers(init?.headers);
    headers.set('Authorization', `Basic ${base64EncodedApiKey}`);
    headers.set('x-account-id', accountId);
    return fetch(url, { ...init, headers });
  };

  const client = await A2AClient.fromCardUrl(agentCard.url, {
    fetchImpl: authenticatedFetch,
  });

  const sendParams: MessageSendParams = {
    message: {
      messageId: uuidv4(),
      role: 'user',
      parts: [{ kind: 'text', text: message }],
      kind: 'message',
    },
    contextId,
    taskId,
  };

  const response = await client.sendMessage(sendParams);

  // Handle error
  if ('error' in response) {
    return { error: response.error };
  }

  const result = (response as SendMessageSuccessResponse).result;

  if (result.kind === 'message') {
    // Agent responded with a Message (i.e. didn't start a Task)
    const msg = result as Message;
    return {
      Message: {
        messageId: msg.messageId,
        role: msg.role,
        parts: msg.parts,
        contextId: msg.contextId,
      },
    };
  } else {
    // Agent responded with a Task (i.e. started a Task)
    // Tasks contain the whole message history. We typically want the
    // Task's status, and Artifacts (if the Task has completed).
    const task = result as Task;
    return {
      Task: {
        status: task.status,
        artifacts: task.artifacts || [],
        contextId: task.contextId,
        taskId: task.id,
      },
    };
  }
}
```

<Note>
  See a complete working example in the [StackOne A2A Agents Orchestrator Demo](https://github.com/StackOneHQ/a2a-demo), which shows how to build an orchestrator agent that routes requests to multiple StackOne A2A agents, manages multi-turn conversations, and serves as an A2A server itself.
</Note>

## Next Steps

<CardGroup>
  <Card title="Python SDK" icon="python" href="/a2a/sdk-guides/python">
    Use the A2A Python SDK
  </Card>

  <Card title="Agent Frameworks" icon="robot" href="/a2a/framework-guides/adk">
    Build agents with framework integrations
  </Card>

  <Card title="Authentication" icon="shield" href="/a2a/auth-security">
    Learn about authentication and security
  </Card>

  <Card title="Quickstart" icon="rocket" href="/a2a/quickstart">
    Learn A2A basics with cURL
  </Card>
</CardGroup>


# A2A Python SDK
Source: https://docs.stackone.com/a2a/sdk-guides/python

Build agents that communicate with StackOne's A2A agents using the official A2A Python SDK.

## Overview

The [A2A Python SDK](https://github.com/a2aproject/a2a-python) provides a Python client library for building agents that interact with A2A agents following the [Agent2Agent (A2A) Protocol](https://a2a-protocol.org).

Use this SDK to build agents that:

* Discover and connect to StackOne's A2A agents
* Send messages and receive responses
* Manage multi-turn conversations with context

## Installation

Install the A2A SDK using `uv` or `pip`:

<Tabs>
  <Tab title="uv">
    ```bash theme={null}
    uv add a2a-sdk
    ```
  </Tab>

  <Tab title="pip">
    ```bash theme={null}
    pip install a2a-sdk
    ```
  </Tab>
</Tabs>

## Quick Start

Get an Agent Card, send a Message, and print the response.

```python theme={null}
import asyncio
import base64
import uuid
import httpx
from a2a.client import A2ACardResolver, ClientFactory, ClientConfig
from a2a.types import Message, Part, TextPart

BASE64_ENCODED_STACKONE_API_KEY: str = base64.b64encode(b"<stackone_api_key>:").decode()
STACKONE_ACCOUNT_ID: str = "<account_id>"

async def main() -> None:
    """
    Fetch an Agent Card, send a message, and print the response.
    """
    async with httpx.AsyncClient(
        headers={
            "Authorization": f"Basic {BASE64_ENCODED_STACKONE_API_KEY}",
            "x-account-id": STACKONE_ACCOUNT_ID
        }
    ) as http_client:
        # Fetch the Agent Card
        card_resolver = A2ACardResolver(http_client, "https://a2a.stackone.com")
        card = await card_resolver.get_agent_card()
        print(card.model_dump_json(indent=4))

        # Initialize client
        factory = ClientFactory(ClientConfig(httpx_client=http_client))
        client = factory.create(card)

        # Send a message
        message = Message(
            messageId=str(uuid.uuid4()),
            role="user",
            parts=[Part(root=TextPart(kind="text", text="List the first 5 employees"))],
            kind="message"
        )

        # send_message returns an async generator of streaming events
        async for event in client.send_message(message):
            if isinstance(event, tuple):
                task, update = event
                if task.status.state == "completed":
                    for artifact in (task.artifacts or []):
                        for part in (artifact.parts or []):
                            if hasattr(part.root, "text"):
                                print(part.root.text)

if __name__ == "__main__":
    asyncio.run(main())
```

See [Authentication Guide](/a2a/auth-security) for details on obtaining your API key and account ID.

## Getting Agent Cards

During agent initialisation, fetch an Agent Card for every A2A agent you want to send messages to.
This is typically a setup step as opposed to a tool.

<Note>
  Ensure to include the agent information in the agent's context (e.g. system message).
</Note>

```python theme={null}
import asyncio
import base64
import json
from typing import Any

import httpx
from a2a.client import A2ACardResolver
from a2a.types import AgentCard

BASE64_ENCODED_STACKONE_API_KEY: str = base64.b64encode(b"<stackone_api_key>:").decode()


async def fetch_agent_cards(account_ids: list[str]) -> dict[str, AgentCard]:
    """
    Fetch Agent Cards from StackOne A2A agents for multiple accounts.

    The Agent URL is fixed to https://a2a.stackone.com and dynamically loads
    an Agent Card based on the account ID.

    Args:
        account_ids (list[str]): List of StackOne account IDs

    Returns:
        dict[str, AgentCard]: Dictionary mapping account IDs to their Agent Cards
    """
    agent_cards: dict[str, AgentCard] = {}

    for account_id in account_ids:
        try:
            async with httpx.AsyncClient(
                headers={
                    "Authorization": f"Basic {BASE64_ENCODED_STACKONE_API_KEY}",
                    "x-account-id": account_id
                }
            ) as http_client:
                card_resolver = A2ACardResolver(http_client, "https://a2a.stackone.com")
                card: AgentCard = await card_resolver.get_agent_card()
                agent_cards[card.name] = card

        except Exception as e:
            print(f"Failed to fetch agent card for account {account_id}: {e}")

    return agent_cards


async def get_a2a_agent_info(agent_cards: dict[str, AgentCard]) -> str:
    """
    Get A2A agent information for agent context.

    Args:
        agent_cards (dict[str, AgentCard]): Dictionary mapping account IDs to their Agent Cards

    Returns:
        str: Agent information for LLM context
    """
    a2a_agent_info: list[dict[str, Any]] = []

    for agent_card in agent_cards.values():
        a2a_agent_info.append({
            "name": agent_card.name,
            "description": agent_card.description,
            "skills": [
                skill.name for skill in (agent_card.skills or [])
            ]
        })

    return "\n".join([
        "<agents>",
        json.dumps(a2a_agent_info, indent=4),
        "</agents>"
    ])


async def main() -> None:
    """
    Fetch agent cards from multiple StackOne accounts and format for LLM context.
    """
    # Fetch agent cards from multiple StackOne accounts
    account_ids: list[str] = ["<account_id_1>", "<account_id_2>", "<account_id_3>"]
    agent_cards: dict[str, AgentCard] = await fetch_agent_cards(account_ids)

    # Get agent information for LLM context (e.g. system message)
    a2a_agent_info: str = await get_a2a_agent_info(agent_cards)
    print(a2a_agent_info)

if __name__ == "__main__":
    asyncio.run(main())
```

## Sending Messages

To send messages to A2A agents, give your agent access to a tool like below.

<Note>
  The tool below gives the agent relatively high autonomy.
  You might want to abstract context IDs and task IDs outside of the tool.
</Note>

```python theme={null}
import uuid
import base64
from typing import Any, List, Tuple
import httpx

from a2a.client import A2ACardResolver, ClientFactory, ClientConfig
from a2a.types import (
    AgentCard,
    Message,
    Part,
    TextPart,
    Task,
)

BASE64_ENCODED_STACKONE_API_KEY: str = base64.b64encode(b"<stackone_api_key>:").decode()

# Dictionary mapping agent names to their (account_id, AgentCard) pairs
agent_cards: dict[str, tuple[str, AgentCard]] = {}


async def send_message_to_agent(
    agent_name: str,
    message: str,
) -> dict[str, Any]:
    """
    Send a message to an agent and receive a response.

    Args:
        agent_name (str): The name of the agent to send the message to
        message (str): The message text to send

    Returns:
        dict[str, Any]: A dictionary containing the response from the agent
    """
    if agent_name not in agent_cards:
        raise ValueError(f"Agent {agent_name} not found")

    account_id, card = agent_cards[agent_name]

    async with httpx.AsyncClient(
        headers={
            "Authorization": f"Basic {BASE64_ENCODED_STACKONE_API_KEY}",
            "x-account-id": account_id
        }
    ) as http_client:
        factory = ClientFactory(ClientConfig(httpx_client=http_client))
        client = factory.create(card)

        msg = Message(
            messageId=str(uuid.uuid4()),
            role="user",
            parts=[Part(root=TextPart(kind="text", text=message))],
            kind="message"
        )

        final_task: Task | None = None
        async for event in client.send_message(msg):
            if isinstance(event, tuple):
                task, update = event
                final_task = task

        if final_task is None:
            return {"error": "No response received"}

        # Tasks contain the whole message history. We typically want the
        # Task's status, and Artifacts (if the Task has completed).
        return {
            "Task": {
                "status": final_task.status.model_dump(),
                "artifacts": [artifact.model_dump() for artifact in (final_task.artifacts or [])],
                "context_id": final_task.contextId,
                "task_id": final_task.id,
            }
        }
```

<Note>
  See a complete working example in the [StackOne A2A Agents Orchestrator Demo](https://github.com/StackOneHQ/a2a-demo), which shows how to build an orchestrator agent that routes requests to multiple StackOne A2A agents, manages multi-turn conversations, and serves as an A2A server itself.
</Note>

## Next Steps

<CardGroup>
  <Card title="JavaScript SDK" icon="js" href="/a2a/sdk-guides/javascript">
    Use the A2A JavaScript SDK
  </Card>

  <Card title="Agent Frameworks" icon="robot" href="/a2a/framework-guides/adk">
    Build agents with framework integrations
  </Card>

  <Card title="Authentication" icon="shield" href="/a2a/auth-security">
    Learn about authentication and security
  </Card>

  <Card title="Quickstart" icon="rocket" href="/a2a/quickstart">
    Learn A2A basics with cURL
  </Card>
</CardGroup>


# Basic Usage
Source: https://docs.stackone.com/agents/python/basic-usage

Learn the fundamentals of using the StackOne Python SDK for AI agents

## Quick Start

The most common pattern: create a toolset and give your agent search and execute tools. The agent discovers and runs tools on demand.

```python theme={null}
from stackone_ai import StackOneToolSet

# search_and_execute returns the tool_search + tool_execute meta tools, so search
# must be enabled on the toolset (pass search={} for defaults).
toolset = StackOneToolSet(search={"method": "auto"})

# Your agent gets 2 tools: tool_search + tool_execute
tools = toolset.openai(mode="search_and_execute", account_ids=["your-account-id"])
```

Pass `tools` to any OpenAI-compatible model and the agent will search for relevant tools, then execute them automatically. See the [OpenAI integration guide](/agents/python/frameworks/openai-integration) for a full agent loop.

## Fetch Tools

When you need specific tools instead of search and execute:

```python theme={null}
tools = toolset.fetch_tools(account_ids=["your-account-id"])
openai_tools = tools.to_openai()
```

<AccordionGroup>
  <Accordion title="Filtering by provider, action, or pattern">
    ```python theme={null}
    # Filter by providers
    tools = toolset.fetch_tools(
        providers=["hibob", "workday"],
        account_ids=["your-account-id"],
    )

    # Filter by actions with exact match
    tools = toolset.fetch_tools(
        actions=["hibob_list_employees", "hibob_create_employees"],
        account_ids=["your-account-id"],
    )

    # Filter by actions with glob patterns
    tools = toolset.fetch_tools(
        actions=["*_list_*"],
        account_ids=["your-account-id"],
    )

    # Combine multiple filters
    tools = toolset.fetch_tools(
        providers=["hibob"],
        actions=["*_list_*"],
        account_ids=["your-account-id"],
    )
    ```

    See [Tool Filtering](/agents/python/tool-filtering) for the full reference.
  </Accordion>

  <Accordion title="Multi-account usage">
    ```python theme={null}
    # Set accounts on the toolset for all subsequent calls
    toolset.set_accounts(["account-123", "account-456"])
    tools = toolset.fetch_tools()

    # Or pass account IDs per request
    tools = toolset.fetch_tools(account_ids=["account-123", "account-456"])

    # Loop over customer accounts dynamically
    customer_accounts = ["account-1", "account-2", "account-3"]

    for account_id in customer_accounts:
        tools = toolset.fetch_tools(
            actions=["workday_list_workers"],
            account_ids=[account_id],
        )
        employee_tool = tools.get_tool("workday_list_workers")
        if employee_tool:
            employees = employee_tool.call()
            print(f"Found {len(employees['data'])} employees")
    ```
  </Accordion>
</AccordionGroup>

## Tool Execution

<AccordionGroup>
  <Accordion title="Direct tool execution (for debugging)">
    Direct execution is useful for testing and debugging. In production, your agent framework handles tool calls automatically.

    ```python theme={null}
    tools = toolset.fetch_tools(account_ids=["your-account-id"])
    employee_tool = tools.get_tool("workday_list_workers")

    # call() with keyword arguments
    result = employee_tool.call(id="employee-123", include_details=True)
    print(result["data"])

    # execute() with dictionary payloads
    result = employee_tool.execute({"id": "employee-123", "include_details": True})

    # execute() with OpenAI-style arguments
    payload = {"arguments": {"id": "employee-123"}}
    result = employee_tool.execute(payload)
    ```
  </Accordion>

  <Accordion title="Error handling">
    ```python theme={null}
    from stackone_ai.models import StackOneError, StackOneAPIError

    try:
        result = employee_tool.call(id="employee-123")
        print("Success:", result)
    except StackOneAPIError as e:
        print(f"API error: {e.message}")
    except StackOneError as e:
        print(f"StackOne error: {e.message}")
    except Exception as e:
        print(f"Unexpected error: {e}")
    ```
  </Accordion>

  <Accordion title="File downloads (binary responses)">
    Actions that download a file (for example `googledrive_unified_download_file`, `documents_download_file`, or any `*_unified_download_file`) return raw bytes plus metadata, not parsed JSON. The SDK decides from the response `Content-Type`: JSON is parsed as usual, and anything else is treated as a file download. `call()` and `execute()` both return this dict directly (it isn't wrapped in a result object), so read its values with dict keys like `result["content"]`.

    ```python theme={null}
    tools = toolset.fetch_tools(actions=["googledrive_*"], account_ids=["your-account-id"])
    download = tools.get_tool("googledrive_unified_download_file")

    result = download.execute({"id": "file-id"})

    # result describes the file. Write the bytes straight to disk:
    with open(result["file_name"] or "download.bin", "wb") as f:
        f.write(result["content"])
    ```

    The returned dict, from both `call()` and `execute()`:

    | Key            | Type          | Description                                                                    |
    | -------------- | ------------- | ------------------------------------------------------------------------------ |
    | `content`      | `bytes`       | Raw file bytes. Not JSON-serializable (see note).                              |
    | `content_type` | `str`         | File MIME type (for example `application/pdf`), or `application/octet-stream`. |
    | `status_code`  | `int`         | HTTP status of the download response.                                          |
    | `headers`      | `dict`        | Response headers.                                                              |
    | `file_name`    | `str \| None` | Filename from `Content-Disposition` (RFC 5987 `filename*` aware), else `None`. |

    <Warning>
      `content` is raw bytes and is not JSON-serializable. If you forward tool results to an LLM (or anything that re-serializes to JSON), handle or strip the `content` key. For example, base64-encode it on the LLM-facing path.
    </Warning>
  </Accordion>
</AccordionGroup>

## Environment Configuration

```bash theme={null}
export STACKONE_API_KEY=your_api_key
```

Account IDs are passed per-request when fetching tools or via `toolset.openai(mode="search_and_execute", account_ids=[...])`.

## Next Steps

* [OpenAI Integration](/agents/python/frameworks/openai-integration) for building agents with function calling
* [LangChain Integration](/agents/python/frameworks/langchain-integration) for framework-based workflows
* [Tool Search](/agents/python/tool-search) for natural language tool discovery
* [Tool Filtering](/agents/python/tool-filtering) for advanced filtering patterns


# CrewAI Integration
Source: https://docs.stackone.com/agents/python/frameworks/crewai-integration

Build multi-agent AI workflows with StackOne tools and CrewAI

Build sophisticated multi-agent AI systems where specialised agents collaborate to complete complex business tasks using StackOne's infrastructure of thousands of turnkey tools, RPC orchestration, and MCP/A2A entry points.

<Warning>
  CrewAI may have compatibility issues with StackOne's LangChain tools depending on your CrewAI and pydantic versions. If you encounter a `ValidationError` for `BaseTool`, check for version updates or use the [OpenAI integration](/agents/python/frameworks/openai-integration) instead.
</Warning>

## Overview

* **Multi-agent collaboration** with business data access
* **Specialized agents** for different business functions
* **Complex workflow automation** with task dependencies
* **Enhanced error handling** and monitoring

```python theme={null}
from crewai import Agent, Crew, Task
from stackone_ai import StackOneToolSet

def create_hr_crew(account_id: str):
    """
    Create multi-agent crew with tools for a specific account.

    In production, account_id comes from:
    - User/tenant context
    - Authentication middleware
    - Database lookup
    """
    # Initialize toolset
    toolset = StackOneToolSet()

    # Fetch tools dynamically for this account
    tools = toolset.fetch_tools(
        account_ids=[account_id]
    ).to_langchain()

    # Optional: Filter by operation type for security
    # read_only_tools = toolset.fetch_tools(
    #     account_ids=[account_id],
    #     actions=["*_list_*", "*_get_*"]  # Only list and get operations
    # ).to_langchain()

    # Create specialized agents
    hr_manager = Agent(
        role="HR Manager",
        goal="Manage employee data and handle HR requests",
        backstory="Expert in human resources with experience in employee management",
        tools=tools,
        llm="gpt-5.4",
        verbose=True
    )

    recruiter = Agent(
        role="Recruiter",
        goal="Find and evaluate candidates for open positions",
        backstory="Experienced recruiter with talent acquisition expertise",
        tools=tools,
        llm="gpt-5.4",
        verbose=True
    )

    # Create collaborative tasks
    employee_analysis_task = Task(
        description="Analyze current employee distribution by department",
        agent=hr_manager,
        expected_output="Employee distribution report with staffing recommendations"
    )

    # Execute multi-agent crew
    crew = Crew(
        agents=[hr_manager, recruiter],
        tasks=[employee_analysis_task],
        verbose=True
    )

    return crew

# Usage: Get account from user context
# Get account ID from your app's auth context or StackOne dashboard
account_id = "your-account-id"
crew = create_hr_crew(account_id)
result = crew.kickoff()
print(result)
```

## Example

<GitHubCode lang="python">
  <iframe />
</GitHubCode>


# LangChain Integration
Source: https://docs.stackone.com/agents/python/frameworks/langchain-integration

Build AI agents with StackOne tools and LangChain framework

Build AI agents using LangChain's framework with direct access to business data through StackOne's infrastructure of pre-built tools, RPC orchestration, and MCP/A2A interfaces.

## Overview

* **ReAct and OpenAI Functions** agents with business tool access
* **Multi-step workflow** automation
* **Conversational agents** with memory
* **Advanced error handling** and resilience

```python theme={null}
from stackone_ai import StackOneToolSet
from langchain_openai import ChatOpenAI

def create_agent_for_account(account_id: str):
    """
    Create LangChain agent with tools for a specific account.

    In production, account_id comes from:
    - User/tenant context
    - Authentication middleware
    - Request parameters
    """
    # Initialize toolset
    toolset = StackOneToolSet()

    # Fetch tools dynamically for this account
    tools = toolset.fetch_tools(account_ids=[account_id])
    langchain_tools = tools.to_langchain()

    # Create model with tools
    model = ChatOpenAI(model="gpt-5.4")
    model_with_tools = model.bind_tools(langchain_tools)

    return model_with_tools, tools

# Usage: Get account from user context
# Get account ID from your app's auth context or StackOne dashboard
account_id = "your-account-id"
model, tools = create_agent_for_account(account_id)

# Use the agent
response = model.invoke("List all employees in engineering")

# Handle tool execution
for tool_call in response.tool_calls:
    tool = tools.get_tool(tool_call["name"])
    if tool:
        result = tool.execute(tool_call["args"])
        print(f"Result: {result}")
```

## Example

<GitHubCode lang="python">
  <iframe />
</GitHubCode>

## Agent-Driven Search

Let the LLM discover tools on its own. LangChain handles tool execution automatically:

```python theme={null}
from langchain_openai import ChatOpenAI
from stackone_ai import StackOneToolSet

toolset = StackOneToolSet(
    search={"method": "semantic", "top_k": 3},
    execute={"account_ids": ["your-account-id"]},
)

# LLM receives only 2 tools - framework handles execution
langchain_tools = toolset.langchain(mode="search_and_execute")
model = ChatOpenAI(model="gpt-5.4").bind_tools(langchain_tools)

response = model.invoke(messages)
```

See [Tool Search](/agents/python/tool-search#agent-driven-search) for the full agent loop example.

## Next Steps

* [Basic Usage](/agents/python/basic-usage) for fetching and executing tools
* [Tool Search](/agents/python/tool-search) for search patterns
* [OpenAI Integration](/agents/python/frameworks/openai-integration) for raw client approach


# LangGraph Integration
Source: https://docs.stackone.com/agents/python/frameworks/langgraph-integration

Build stateful, graph-based AI workflows with StackOne tools and LangGraph

Build sophisticated, stateful AI workflows using LangGraph's graph-based architecture with easy access to business data through StackOne's Tools.

## Overview

* **Stateful workflows** with persistent memory
* **Graph-based execution** with conditional branching
* **Multi-step processes** with human-in-the-loop
* **Dynamic tool loading** based on connected accounts

```python theme={null}
from stackone_ai import StackOneToolSet
from langgraph.prebuilt import create_react_agent
from langchain_openai import ChatOpenAI

def create_agent_for_account(account_id: str):
    """
    Create LangGraph agent with tools for a specific account.

    In production, account_id comes from:
    - User/tenant context
    - Authentication middleware
    - Request parameters
    """
    # Initialize toolset
    toolset = StackOneToolSet()

    # Fetch tools dynamically for this account
    tools = toolset.fetch_tools(account_ids=[account_id])

    # Convert to LangChain format (LangGraph uses LangChain tools)
    langchain_tools = tools.to_langchain()

    # Create LangGraph agent
    model = ChatOpenAI(model="gpt-5.4")
    agent = create_react_agent(model, langchain_tools)

    return agent

# Use the agent
# Get account ID from your app's auth context or StackOne dashboard
account_id = "your-account-id"
agent = create_agent_for_account(account_id)

# Run stateful workflow
config = {"configurable": {"thread_id": "user-123-session"}}
result = agent.invoke(
    {"messages": [("user", "Find all employees hired this year")]},
    config=config
)
```

## Dynamic Tool Loading

Load tools based on available integrations:

```python theme={null}
from stackone_ai import StackOneToolSet

toolset = StackOneToolSet()

# Load all tools for specific accounts (most common)
tools = toolset.fetch_tools(
    account_ids=["account-123"]
)

# Optional: Filter by operation type for security
tools = toolset.fetch_tools(
    account_ids=["account-123"],
    actions=["*_list_*", "*_get_*"]  # Only list and get operations (read-only)
)

# Convert to LangChain format for LangGraph
langchain_tools = tools.to_langchain()
```

## Stateful Workflows

Build complex, multi-step workflows with state:

```python theme={null}
from langgraph.graph import StateGraph, MessagesState
from langgraph.prebuilt import ToolNode
from langchain_core.messages import SystemMessage

# Define workflow state
class AgentState(MessagesState):
    employee_data: dict
    analysis_complete: bool

# Create graph
def create_hr_workflow(account_id: str):
    toolset = StackOneToolSet()
    tools = toolset.fetch_tools(account_ids=[account_id])
    langchain_tools = tools.to_langchain()

    # Create nodes
    tool_node = ToolNode(langchain_tools)

    def agent_node(state: AgentState):
        model = ChatOpenAI(model="gpt-5.4")
        model_with_tools = model.bind_tools(langchain_tools)

        messages = [
            SystemMessage(content="You are an HR data analyst."),
            *state["messages"]
        ]
        response = model_with_tools.invoke(messages)
        return {"messages": [response]}

    # Build graph
    workflow = StateGraph(AgentState)
    workflow.add_node("agent", agent_node)
    workflow.add_node("tools", tool_node)

    workflow.set_entry_point("agent")
    workflow.add_conditional_edges("agent", should_continue)
    workflow.add_edge("tools", "agent")

    return workflow.compile()

def should_continue(state: AgentState):
    """Decide whether to continue or finish"""
    last_message = state["messages"][-1]
    if not last_message.tool_calls:
        return "end"
    return "tools"
```

## Human-in-the-Loop

Add human approval for sensitive operations:

```python theme={null}
from langgraph.prebuilt import create_react_agent
from langgraph.checkpoint.memory import MemorySaver

def create_hr_agent_with_approval(account_id: str):
    toolset = StackOneToolSet()

    # Only expose read operations initially (optional filtering)
    read_tools = toolset.fetch_tools(
        account_ids=[account_id],
        actions=["*_list_*", "*_get_*"]  # Only list and get operations
    )

    agent = create_react_agent(
        model=ChatOpenAI(model="gpt-5.4"),
        tools=read_tools.to_langchain(),
        checkpointer=MemorySaver()
    )

    return agent

# Usage: Approve before executing sensitive actions
agent = create_hr_agent_with_approval(account_id)
result = agent.invoke({"messages": [("user", "Review termination candidates")]})

# Human reviews, then loads write tools for approved actions
if user_approves(result):
    write_tools = toolset.fetch_tools(
        account_ids=[account_id],
        actions=["*_update_*", "*_create_*"]  # Only update and create operations
    )
    # Continue with write operations...
```

## Best Practices

### Account ID from Context

```python theme={null}
# Get from request context
account_id = get_account_from_auth_token(request)
account_id = tenant.stackone_account_id
```

### Tool Security

```python theme={null}
# Optional: Only expose read operations for security
safe_tools = toolset.fetch_tools(
    account_ids=[account_id],
    actions=["*_list_*", "*_get_*"]  # Only list and get operations
)

# Or exclude dangerous operations
safe_tools = toolset.fetch_tools(
    account_ids=[account_id],
    actions=["!*_delete_*"]  # Everything except deletes
)
```

## Next Steps

* [Basic Usage](/agents/python/basic-usage) for fetching and executing tools
* [Tool Filtering](/agents/python/tool-filtering) for security
* [LangChain Integration](/agents/python/frameworks/langchain-integration) for simpler workflows


# OpenAI Integration
Source: https://docs.stackone.com/agents/python/frameworks/openai-integration

Build AI agents with OpenAI Functions using the StackOne Python SDK

Build AI agents that can interact with business systems using OpenAI's function calling atop StackOne's infrastructure: thousands of ready-to-run tools exposed over RPC with unified MCP and A2A interfaces.

## Overview

* **Function calling** with business data access
* **Conversational agents** with tool execution
* **Multi-step workflow** automation
* **Real-time data** integration

```python theme={null}
import json
from openai import OpenAI
from stackone_ai import StackOneToolSet

# Initialise clients
client = OpenAI()
toolset = StackOneToolSet()

# Fetch StackOne tools and convert to OpenAI format
tools = toolset.fetch_tools(
    actions=['workday_get_worker', 'workday_list_workers'],
    account_ids=['your-account-id']
)
openai_tools = tools.to_openai()

# Create an AI agent with tool access
response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[
        {
            "role": "system",
            "content": "You are an HR assistant with access to employee data."
        },
        {
            "role": "user",
            "content": "How many employees are in engineering?"
        }
    ],
    tools=openai_tools,
    tool_choice="auto"
)

# Handle tool calls
message = response.choices[0].message
if message.tool_calls:
    for tool_call in message.tool_calls:
        tool = tools.get_tool(tool_call.function.name)
        if tool:
            result = tool.execute(tool_call.function.arguments)
            print(f"Result: {result}")
```

## Example

<GitHubCode lang="python">
  <iframe />
</GitHubCode>

## Agent-Driven Search

Let the LLM discover and execute tools on its own. Instead of loading all tools upfront, pass `tool_search` + `tool_execute` and the LLM finds what it needs:

```python theme={null}
from stackone_ai import StackOneToolSet

toolset = StackOneToolSet(
    search={"method": "semantic", "top_k": 3},
    execute={"account_ids": ["your-account-id"]},
)

# LLM receives only 2 tools - it searches and executes autonomously
openai_tools = toolset.openai(mode="search_and_execute")

response = client.chat.completions.create(
    model="gpt-5.4",
    messages=messages,
    tools=openai_tools,
    tool_choice="auto",
)

# Execute tool calls
for tool_call in response.choices[0].message.tool_calls:
    result = toolset.execute(tool_call.function.name, tool_call.function.arguments)
```

See [Tool Search](/agents/python/tool-search#agent-driven-search) for the full agent loop example.

## Next Steps

* [Basic Usage](/agents/python/basic-usage) for fetching and executing tools
* [Tool Search](/agents/python/tool-search) for search patterns
* [LangChain Integration](/agents/python/frameworks/langchain-integration) for framework integration


# Pydantic AI Integration
Source: https://docs.stackone.com/agents/python/frameworks/pydantic-ai-integration

Build type-safe AI agents with StackOne tools and Pydantic AI

Build production-ready AI agents with Pydantic AI's type-safe framework and direct access to business data through StackOne's Tools.

## Overview

* **Type-safe agents** with Pydantic validation
* **Structured outputs** with full type checking
* **Dynamic tool loading** based on StackOne Linked Accounts
* **OpenAI-compatible** tool integration

```python theme={null}
import json
from stackone_ai import StackOneToolSet
from pydantic_ai import Agent, Tool

def create_agent_for_account(account_id: str):
    # Initialize toolset and fetch tools
    toolset = StackOneToolSet()
    tools = toolset.fetch_tools(account_ids=[account_id])

    # Convert each StackOne tool to a Pydantic AI Tool with proper schema
    pydantic_tools = []
    for stackone_tool in tools:
        params_schema = stackone_tool.to_openai_function()["function"]["parameters"]

        def execute(t=stackone_tool, **kwargs: object) -> str:
            return json.dumps(t.execute(kwargs))

        pydantic_tools.append(
            Tool.from_schema(
                execute,
                name=stackone_tool.name,
                description=stackone_tool.description,
                json_schema=params_schema,
            )
        )

    # Create agent with tools
    agent = Agent(
        "openai:gpt-5.4",
        system_prompt="You are a helpful HR assistant.",
        tools=pydantic_tools,
    )
    return agent

# Get account ID from your app's auth context or StackOne dashboard
account_id = "your-account-id"
agent = create_agent_for_account(account_id)

result = agent.run_sync("List the first 5 employees")
print(result.output)
```

## Dynamic Tool Loading

Use `fetch_tools()` to load only the tools available for specific accounts:

```python theme={null}
from stackone_ai import StackOneToolSet

toolset = StackOneToolSet()

# Load all tools for specific accounts (most common)
tools = toolset.fetch_tools(
    account_ids=["account-123", "account-456"]
)

# Optional: Filter by operation type for security
tools = toolset.fetch_tools(
    account_ids=["account-123"],
    actions=["*_list_*", "*_get_*"]  # Only list and get operations (read-only)
)
```

## Structured Outputs

Leverage Pydantic AI's type-safe responses:

```python theme={null}
from pydantic import BaseModel
from pydantic_ai import Agent

class EmployeeSummary(BaseModel):
    total_count: int
    departments: list[str]
    average_tenure_years: float

agent = Agent(
    model=OpenAIModel('gpt-5.4'),
    result_type=EmployeeSummary,
    system_prompt="Analyze employee data and return structured summaries."
)

# Returns validated EmployeeSummary instance
result = agent.run_sync("Summarize the employee base")
summary: EmployeeSummary = result.data

print(f"Total employees: {summary.total_count}")
print(f"Departments: {', '.join(summary.departments)}")
```

## Best Practices

### Account ID from Context

```python theme={null}
# Get from user/tenant context
account_id = request.user.stackone_account_id
account_id = get_account_for_tenant(tenant_id)
```

### Error Handling

```python theme={null}
from stackone_ai.models import StackOneError, StackOneAPIError

try:
    result = agent.run_sync(message)
except StackOneAPIError as e:
    print(f"API error: {e.message}")
except StackOneError as e:
    print(f"StackOne error: {e.message}")
```

### Tool Filtering

```python theme={null}
# Only expose read operations (optional - for security)
tools = toolset.fetch_tools(
    account_ids=[account_id],
    actions=["*_list_*", "*_get_*"]  # Only list and get
)

# Or exclude dangerous operations
tools = toolset.fetch_tools(
    account_ids=[account_id],
    actions=["!*_delete_*"]  # Everything except deletes
)
```

## Next Steps

* [Basic Usage](/agents/python/basic-usage) for fetching and executing tools
* [Tool Filtering](/agents/python/tool-filtering) for security
* [Tool Search](/agents/python/tool-search) for natural language tool discovery


# Installation
Source: https://docs.stackone.com/agents/python/installation

Install and setup the StackOne AI Python SDK

Install the StackOne AI SDK for Python applications with first-class support for LangChain, CrewAI, OpenAI, LangGraph, and Pydantic AI. The package includes typed tool definitions, framework adapters, search and execute tools, and dynamic discovery.

## Installation

Install the SDK with MCP support (recommended):

```bash theme={null}
# Using uv (Recommended)
uv add 'stackone-ai[mcp]'

# Using pip
pip install 'stackone-ai[mcp]'
```

## Requirements

* Python 3.10 or higher
* uv or pip

## Optional Extras

Install optional components with extras:

```bash theme={null}
# Pull LangChain/CrewAI/OpenAI example deps
uv add 'stackone-ai[mcp,examples]'
pip install 'stackone-ai[mcp,examples]'
```

## Environment Setup

Set your API key as an environment variable:

```bash theme={null}
export STACKONE_API_KEY=your_api_key_here
```

Account IDs are passed per-request when fetching tools — see [Basic Usage](/agents/python/basic-usage).

## Framework Dependencies

Install additional dependencies based on your framework:

```bash theme={null}
# For LangChain
uv add stackone-ai[examples] langchain langchain-openai
# or using pip
pip install stackone-ai[examples] langchain langchain-openai

# For CrewAI
uv add stackone-ai[examples] crewai
# or using pip
pip install stackone-ai[examples] crewai

# For OpenAI
uv add stackone-ai[examples] openai
# or using pip
pip install stackone-ai[examples] openai
```

## Verification

Test your installation:

```python theme={null}
from stackone_ai import StackOneToolSet

toolset = StackOneToolSet()
print("✅ StackOne AI SDK installed successfully!")
```

## Next Steps

* [Learn basic usage](/agents/python/basic-usage) to start building
* [Integrate with LangChain](/agents/python/frameworks/langchain-integration)
* [Build multi-agent workflows with CrewAI](/agents/python/frameworks/crewai-integration)
* [Explore tool search and filtering](/agents/python/tool-search)


# Python Toolset
Source: https://docs.stackone.com/agents/python/introduction

Build connected agents with StackOne's Python AI SDK & Toolset

Build AI agents that connect to Salesforce, Workday, Slack, Gmail, HubSpot, and 200+ other business systems. The Python SDK integrates natively with LangChain, CrewAI, OpenAI Functions, LangGraph, and Pydantic AI. It includes dynamic tool discovery and search.

<Tip>
  **Not sure if the AI Toolset (SDK) is right for you?** Check out our [Agent Protocols Guide](/guides/calling-stackone-actions) to understand when to use AI Toolset (SDK) vs MCP vs A2A.
</Tip>

## Why StackOne?

<CardGroup>
  <Card title="200+ Providers" icon="plug">Connect to Salesforce, Workday, Slack, Gmail, and more through one SDK</Card>
  <Card title="Multi-Tenant" icon="users">Built-in customer isolation with `account_id` for each connection</Card>
  <Card title="AI-Native" icon="robot">Tools designed for LLM function calling and agent frameworks</Card>
  <Card title="Consistent Data" icon="database">Normalized schemas: no provider-specific parsing needed</Card>
</CardGroup>

## How It Works

<Frame>
  <img alt="StackOne Architecture" />
</Frame>

Your agent connects to StackOne, which handles authentication and data normalization for 200+ SaaS providers like Salesforce, Workday, Slack, and more.

| Component          | Description                                                                |
| ------------------ | -------------------------------------------------------------------------- |
| **Your Agent**     | Built with LangChain, CrewAI, OpenAI, Vercel AI, or any framework          |
| **StackOne**       | AI Integration Gateway: handles auth, transforms data, manages connections |
| **SaaS Providers** | Salesforce, Workday, Greenhouse, Slack, Gmail, HubSpot, and 200+ more      |

## Key Concepts

* **Initialize a ToolSet**: Create a `StackOneToolSet` instance to access tools for providers like Workday, Greenhouse, Slack, and more
* **Filter Tools**: Use provider glob patterns like `"workday_*"`, `"slack_*"` or the `fetch_tools()` method for provider/action/account filters
* **Execute Tools**: Call provider APIs using `tool.call()` to list employees from Workday, send Slack messages, or create Jira tickets
* **Tool Search**: Discover relevant tools at runtime via natural language queries
* **Multi-Tenant**: Each tool execution requires an `account_id` to identify which customer's account to access

## Python Framework Integrations

<CardGroup>
  <Card title="LangChain" href="/agents/python/frameworks/langchain-integration" icon="https://mintcdn.com/stackone-60/O2F4c3prhb0R9e5f/images/agents/langchain-logo.webp?fit=max&auto=format&n=O2F4c3prhb0R9e5f&q=85&s=8943521905cd027e58fade91dbb5aa36">
    Build sophisticated agents with LangChain
  </Card>

  <Card title="CrewAI" href="/agents/python/frameworks/crewai-integration" icon="https://mintcdn.com/stackone-60/O2F4c3prhb0R9e5f/images/agents/crewai-logo.png?fit=max&auto=format&n=O2F4c3prhb0R9e5f&q=85&s=fea1f8fc99187fd08c0f628bd6b4c849">
    Multi-agent workflows and collaboration
  </Card>

  <Card title="OpenAI" href="/agents/python/frameworks/openai-integration" icon="https://mintcdn.com/stackone-60/zRAvvofCYLmP9UF6/images/agents/openai-logo.svg?fit=max&auto=format&n=zRAvvofCYLmP9UF6&q=85&s=a38c135695435b960bc6b40052de4ad0">
    Direct OpenAI function calling
  </Card>
</CardGroup>

## Python Core Features

<CardGroup>
  <Card title="Tool Filtering" href="/agents/python/tool-filtering" icon="filter">
    Glob patterns plus provider/action filters with `fetch_tools()`
  </Card>

  <Card title="Tool Search" href="/agents/python/tool-search" icon="magnifying-glass">
    Discover tools using natural language queries
  </Card>

  <Card title="Installation" href="/agents/python/installation" icon="download">
    Set up the Python SDK
  </Card>

  <Card title="Basic Usage" href="/agents/python/basic-usage" icon="play">
    Core concepts and fundamental usage patterns
  </Card>
</CardGroup>

## Next Steps

1. [Learn about tool filtering](/agents/python/tool-filtering)
2. [Explore Tool Search](/agents/python/tool-search)

## Resources

* **[GitHub Repository](https://github.com/StackOneHQ/stackone-ai-python)**: Complete source code and examples
* **[Examples](https://github.com/StackOneHQ/stackone-ai-python/tree/main/examples)**: LangChain, CrewAI, and semantic search examples
* **[Issues](https://github.com/StackOneHQ/stackone-ai-python/issues)**: Report bugs or request features
* **[PyPI Package](https://pypi.org/project/stackone-ai/)**: Package details and version history


# Tool Filtering
Source: https://docs.stackone.com/agents/python/tool-filtering

Filter tools when using the StackOne Python AI SDK

The StackOne SDK provides glob-based filtering capabilities to help you select and manage specific tools across different SaaS platforms.

## What Tool Filtering Enables

Tool filtering allows you to:

* Select tools by provider (e.g., Salesforce, Gmail, Workday)
* Filter by specific actions (create, read, update, delete)
* Combine multiple patterns for precise selection
* Exclude specific tools or patterns

## Basic Filtering Patterns

### By Provider

* `salesforce_*` - Salesforce CRM
* `gmail_*` - Gmail & Calendar
* `workday_*` - Workday HCM

### By Action

* `*_create_*` - All create operations
* `*_list_*` - All list operations
* `*_get_*` - All get operations

### Combined Patterns

* `hibob_list_*` - HiBob list operations only
* `workday_update_*` - Workday update operations only

## Use Cases

1. **Cross-Domain Agents**: Let assistants reliably interact with whatever tools (CRMs, ERPs, comms suites, etc.) are available for the current account
2. **Operation-Focused Tools**: Create specialized agents for read-only or write operations
3. **Custom Tool Sets**: Combine multiple patterns for precise control
4. **Performance Optimization**: Load only the tools your agent actually needs

## Python Naming Conventions

### Tool Name Structure

StackOne tools follow the pattern: `provider_operation_entity`

```python theme={null}
from stackone_ai import StackOneToolSet

toolset = StackOneToolSet()
account_id = "your-account-id"

# Filter by provider prefix
hibob_tools = toolset.fetch_tools(actions=["hibob_*"], account_ids=[account_id])

# Filter by action
create_tools = toolset.fetch_tools(actions=["*_create_*"], account_ids=[account_id])

# Filter by entity keywords
employee_tools = toolset.fetch_tools(actions=["*employee*"], account_ids=[account_id])
```

### Common Patterns

**By Connector** (using their individual keys, eg. `workday`, `netsuite`, `gmail` `salesforce` and hundreds more)

* `hibob_*` - HiBob
* `workday_*` - Workday
* `greenhouse_*` - Greenhouse

**By Operation:**

* `*_list_*` - Get multiple records
* `*_get_*` - Get single record
* `*_create_*` - Create new record
* `*_update_*` - Update existing record

**By Entity:**

* `*employee*` - Employee operations
* `*candidate*` - Candidate operations
* `*contact*` - Contact operations

## Examples

For complete implementation examples, see:

* [Python Examples on GitHub](https://github.com/StackOneHQ/stackone-ai-python/tree/main/examples)
* [Tool Search](/agents/python/tool-search) - Natural language tool discovery
* [LangChain Integration](/agents/python/frameworks/langchain-integration) - Use filtered tools


# Tool Search
Source: https://docs.stackone.com/agents/python/tool-search

Discover tools using natural language queries with semantic, local, or auto search modes

<Info>
  New to tool search? Start with [Tool Search 101](/agents/python/tool-search-101) for an overview of why, how, and when to use it.
</Info>

## Agent-Driven Search (Recommended)

The simplest way to use tool search: give your agent `tool_search` and `tool_execute`, and let it discover tools on demand.

```python theme={null}
from stackone_ai import StackOneToolSet

toolset = StackOneToolSet()

# LLM receives only 2 tools: tool_search + tool_execute
openai_tools = toolset.openai(mode="search_and_execute")
```

<Tip>
  Only 2 tools are sent to the LLM regardless of how many tools exist in your catalog. Token usage stays constant.
</Tip>

### Framework Examples

<CodeGroup>
  ```python OpenAI theme={null}
  import json
  from openai import OpenAI
  from stackone_ai import StackOneToolSet

  toolset = StackOneToolSet()

  # LLM receives only 2 tools: tool_search + tool_execute
  openai_tools = toolset.openai(mode="search_and_execute", account_ids=["your-account-id"])

  client = OpenAI()
  messages = [
      {
          "role": "system",
          "content": (
              "Use tool_search to find relevant tools, then tool_execute to run them. "
              "Read parameter schemas from tool_search results carefully. "
              "If a tool needs a user URI, search for a 'get current user' tool first."
          ),
      },
      {"role": "user", "content": "List my upcoming Calendly events for the next week."},
  ]

  for _step in range(10):
      response = client.chat.completions.create(
          model="gpt-5.4",
          messages=messages,
          tools=openai_tools,
          tool_choice="auto",
      )

      choice = response.choices[0]
      if not choice.message.tool_calls:
          print(choice.message.content)
          break

      messages.append(choice.message.model_dump(exclude_none=True))
      for tool_call in choice.message.tool_calls:
          result = toolset.execute(tool_call.function.name, tool_call.function.arguments)
          messages.append({
              "role": "tool",
              "tool_call_id": tool_call.id,
              "content": json.dumps(result),
          })
  ```

  ```python LangChain theme={null}
  import json
  from langchain_openai import ChatOpenAI
  from langchain_core.messages import HumanMessage, SystemMessage, ToolMessage
  from stackone_ai import StackOneToolSet

  toolset = StackOneToolSet(
      search={"method": "semantic", "top_k": 3},
      execute={"account_ids": ["your-account-id"]},
  )

  # LangChain tools - framework handles execution automatically
  langchain_tools = toolset.langchain(mode="search_and_execute")
  tools_by_name = {tool.name: tool for tool in langchain_tools}
  model = ChatOpenAI(model="gpt-5.4").bind_tools(langchain_tools)

  messages = [
      SystemMessage(content="Use tool_search to find tools, then tool_execute to run them."),
      HumanMessage(content="List my upcoming Calendly events for the next week."),
  ]

  for _step in range(10):
      response = model.invoke(messages)
      if not response.tool_calls:
          print(response.content)
          break

      messages.append(response)
      for tool_call in response.tool_calls:
          tool = tools_by_name[tool_call["name"]]
          result = tool.invoke(tool_call["args"])
          messages.append(ToolMessage(content=json.dumps(result), tool_call_id=tool_call["id"]))
  ```
</CodeGroup>

## Manual Search

When you need to find tools yourself before passing them to an agent:

```python theme={null}
from stackone_ai import StackOneToolSet

toolset = StackOneToolSet()
tools = toolset.search_tools("manage employee records")

# Use with any framework
openai_tools = tools.to_openai()
langchain_tools = tools.to_langchain()
```

No configuration needed. Defaults to auto mode with sensible defaults.

<AccordionGroup>
  <Accordion title="Search modes (auto, semantic, local)">
    | Mode       | Behaviour                                                                                                                                                            |
    | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `auto`     | Tries semantic API first, falls back to local search on failure. Recommended for production.                                                                         |
    | `semantic` | Strict mode. Uses semantic API only, raises `SemanticSearchError` on failure.                                                                                        |
    | `local`    | Hybrid BM25 + TF-IDF search entirely in-process (powered by [bm25s](https://github.com/xhluca/bm25s)). No network call. Useful for offline or low-latency scenarios. |

    ```python theme={null}
    # Auto (default)
    tools = toolset.search_tools("manage employees", search="auto")

    # Semantic only
    tools = toolset.search_tools("manage employees", search="semantic")

    # Local only
    tools = toolset.search_tools("manage employees", search="local")
    ```
  </Accordion>

  <Accordion title="Constructor configuration">
    Set default search options at the constructor level. These apply to all search calls unless overridden per-call.

    ### SearchConfig Options

    | Option           | Type                              | Description                             |
    | ---------------- | --------------------------------- | --------------------------------------- |
    | `method`         | `"auto" \| "semantic" \| "local"` | Search mode (default: `"auto"`)         |
    | `top_k`          | `int`                             | Maximum number of tools to return       |
    | `min_similarity` | `float`                           | Minimum relevance score threshold (0-1) |

    ```python theme={null}
    from stackone_ai import StackOneToolSet

    # Custom search config
    toolset = StackOneToolSet(search={"method": "semantic", "top_k": 5})

    # Disable search
    toolset = StackOneToolSet(search=None)

    # Default: search enabled with method="auto"
    toolset = StackOneToolSet()
    ```

    Per-call overrides take precedence over constructor defaults:

    ```python theme={null}
    # Constructor sets top_k=5 for all search calls
    toolset = StackOneToolSet(search={"method": "semantic", "top_k": 5})

    # Uses constructor defaults: method="semantic", top_k=5
    tools = toolset.search_tools("manage employees")

    # top_k overridden to 10 for this call; method remains "semantic"
    tools = toolset.search_tools("manage employees", top_k=10)
    ```
  </Accordion>

  <Accordion title="Parameters reference">
    | Parameter        | Type                              | Description                                         |
    | ---------------- | --------------------------------- | --------------------------------------------------- |
    | `query`          | `str`                             | Natural language description of what you want to do |
    | `top_k`          | `int \| None`                     | Maximum number of tools to return                   |
    | `search`         | `"auto" \| "semantic" \| "local"` | Search mode (default: `"auto"`)                     |
    | `connector`      | `str \| None`                     | Filter to a specific provider (e.g., `"workday"`)   |
    | `min_similarity` | `float \| None`                   | Minimum relevance score threshold (0-1)             |
    | `account_ids`    | `list[str] \| None`               | Override account IDs for this search                |
  </Accordion>
</AccordionGroup>

## Advanced Patterns

<AccordionGroup>
  <Accordion title="search_action_names(), lightweight preview">
    Returns action IDs and similarity scores without fetching full tool definitions. Use it to inspect results before committing to a full fetch.

    ```python theme={null}
    results = toolset.search_action_names("manage employees", top_k=5)

    for r in results:
        print(f"{r.id}: {r.similarity_score:.2f}")
    ```

    <Tip>
      `search_action_names()` works with just `STACKONE_API_KEY`, no account ID needed. When called without `account_ids`, results come from the full StackOne catalog.
    </Tip>
  </Accordion>

  <Accordion title="get_search_tool(), callable for custom agent loops">
    Returns a callable `SearchTool` for agent loops where the LLM decides what to search for.

    ```python theme={null}
    search_tool = toolset.get_search_tool(search="auto")

    # In an agent loop, call it with natural language queries
    queries = [
        "create a new employee",
        "list job candidates",
        "send a message to a channel",
    ]

    for query in queries:
        tools = search_tool(query, top_k=3)
        tool_names = [t.name for t in tools]
        print(f'"{query}" -> {", ".join(tool_names)}')
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

* [LangChain Integration](/agents/python/frameworks/langchain-integration)
* [OpenAI Integration](/agents/python/frameworks/openai-integration)
* [CrewAI Integration](/agents/python/frameworks/crewai-integration)
* [Tool Filtering](/agents/python/tool-filtering)


# Tool Search 101
Source: https://docs.stackone.com/agents/python/tool-search-101

How StackOne's tool search finds the right tools from thousands of actions using natural language

Tool search enables AI agents to discover the right tools using natural language queries, without requiring exact action names.

<Tabs>
  <Tab title="Why Tool Search" label="Why">
    **The Problem**: StackOne manages over 10,000 actions across connectors, with some containing 2,000+ actions. Loading all of them into an LLM's context window is not practical:

    * **Token bloat**: every tool definition consumes tokens, leaving less room for reasoning
    * **Accuracy drops**: LLMs make worse tool selections as the candidate set grows
    * **Provider caps**: OpenAI caps function definitions at \~128 per request

    **The Solution**: More tools does not mean more capability. Without structure, they become noise. Tool search finds only the relevant tools for each query, keeping agent prompts lean while expanding their capabilities.
  </Tab>

  <Tab title="How It Works" label="How">
    **Search Flow**

    1. **Search**: Your agent calls the search method with a natural language query
    2. **Discover**: The SDK fetches available connectors and tool definitions from your linked accounts via MCP
    3. **Match**: Each connector is searched in parallel via the semantic search API
    4. **Rank**: Results are matched to MCP tool definitions, ranked by relevance, deduplicated
    5. **Return**: A `Tools` collection is returned, ready for any framework

    The agent only sees the tools it needs, not the entire catalog.

    **Three Search Modes**

    | Mode             | Behavior                                                            | When to use                                                     |
    | ---------------- | ------------------------------------------------------------------- | --------------------------------------------------------------- |
    | `auto` (default) | Tries the semantic API first, falls back to local search on failure | Production use: best accuracy with built-in resilience          |
    | `semantic`       | Semantic API only. Throws an error if the API is unavailable.       | When you need strict control and want to handle errors yourself |
    | `local`          | Hybrid BM25 + TF-IDF search, entirely in-process. No network call.  | Offline environments or when you need minimal latency           |

    **Local search** scores results with `0.2 * BM25 + 0.8 * TF-IDF` and runs with no network calls.

    **Semantic search** uses enriched embeddings where action descriptions are expanded with related terms before embedding. For example, "Create Employee" is enriched with synonyms like "add new", "insert", "worker", "staff", "team member", so natural language queries match even when wording differs.
  </Tab>

  <Tab title="Benchmarks" label="Benchmarks">
    Tested across 103 semantically-challenging queries against 9,340 actions:

    | Approach            | Hit\@5 (all connectors) | Hit\@5 (per connector) |
    | ------------------- | ----------------------- | ---------------------- |
    | BM25 only           | 21%                     | 65%                    |
    | Enhanced Embeddings | 84%                     | 90%                    |

    BM25 keyword matching works well for exact terms but fails on natural language. For example, searching "onboard new hire" won't match "Create Employee" with BM25 alone.

    For comparison, Anthropic's built-in [tool search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool) uses BM25 matching. StackOne's semantic mode uses enriched embeddings for higher accuracy on natural language queries.
  </Tab>

  <Tab title="Examples" label="Examples">
    **Real-World Use Cases**:

    * **HR Agent**: "Approve Alice's time off request" finds `hibob_create_time_off` and executes in HiBob
    * **Support Agent**: "Search for Jira ticket ABC-123" finds `ticketing_ticket_list` and returns details
    * **Knowledge Agent**: "Find training docs on GDPR" finds `documents_file_search` and queries KB

    **When to Use**:

    Use tool search when your agent spans many SaaS systems (dozens to thousands of tools) and you need higher selection accuracy and scalability.

    Skip tool search if you have a very small, static toolset where you can load all tools directly.
  </Tab>
</Tabs>

### Key Features

<CardGroup>
  <Card title="Scales to Thousands of Tools" icon="chart-line">
    StackOne has 10,000+ actions. Search returns only the relevant ones for each query.
  </Card>

  <Card title="Improves Accuracy" icon="bullseye">
    Only relevant tools exposed per request, reducing misfires and hallucinations.
  </Card>

  <Card title="Account-Aware" icon="shield-check">
    Filters results to tools available for configured account IDs, respecting auth boundaries.
  </Card>

  <Card title="Framework-Ready" icon="puzzle-piece">
    Returns a Tools collection with converters for OpenAI, LangChain, Vercel AI SDK, and more.
  </Card>
</CardGroup>

## Quick Example

```python theme={null}
from stackone_ai import StackOneToolSet

toolset = StackOneToolSet()

# Get search & execute tools. The LLM discovers and runs tools on demand
tools = toolset.openai(mode="search_and_execute")

# Pass these to your OpenAI agent
# The agent gets tool_search + tool_execute, only 2 tools regardless of catalog size
```

## Two Approaches

<Tabs>
  <Tab title="Search & Execute (recommended)">
    **Give the LLM 2 tools — it discovers and runs actions on demand.**

    Instead of pre-filtering, you give the LLM `tool_search` and `tool_execute`. The LLM searches for relevant tools, reads their parameter schemas, and executes them within its own reasoning loop.

    Best for:

    * Open-ended assistants ("help me with any HR task")
    * Large tool catalogs where pre-filtering is impractical
    * When you don't know which tools will be needed upfront
    * Minimal token overhead — always 2 tools regardless of catalog size
  </Tab>

  <Tab title="Pre-filtered">
    **You search first, LLM gets a focused set of tools.**

    Your code calls `searchTools()` or `fetchTools()` with filters, gets back a `Tools` collection, and passes those to the LLM. The LLM only sees relevant tools.

    Best for:

    * Known tasks where you can predict which tools are needed
    * Constrained agents with a focused scope
    * When you want full control over which tools the LLM can access
  </Tab>
</Tabs>

| Aspect            | Search & Execute                          | Pre-filtered                |
| ----------------- | ----------------------------------------- | --------------------------- |
| Tools sent to LLM | Always 2 (`tool_search` + `tool_execute`) | Filtered set (5-20)         |
| Token cost        | Constant                                  | Scales with number of tools |
| Discovery         | LLM discovers on-demand                   | You search upfront          |
| Use case          | Open-ended, exploratory                   | Constrained, known tasks    |

## Architecture Overview

```mermaid theme={null}
graph TB
    User["User"] --> Agent["Your AI Agent"]
    Agent --> SearchTools["Search Tools"]
    Agent --> SearchActionNames["Search Action Names"]
    SearchTools --> MCP["MCP Server"]
    SearchTools --> SemanticAPI["Semantic Search API"]
    SearchTools --> Agent
    Agent --> Execute["Execute Tool"]

    style User fill:#f3f4f6,stroke:#d1d5db,stroke-width:2px,color:#374151
    style Agent fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af
    style SearchTools fill:#4ade80,stroke:#22c55e,stroke-width:2px,color:#15803d
    style SearchActionNames fill:#4ade80,stroke:#22c55e,stroke-width:2px,color:#15803d
    style SemanticAPI fill:#16a34a,stroke:#15803d,stroke-width:2px,color:#fff
    style MCP fill:#16a34a,stroke:#15803d,stroke-width:2px,color:#fff
    style Execute fill:#16a34a,stroke:#15803d,stroke-width:2px,color:#fff
```

**Flow:**

1. User sends a natural language query to your AI agent
2. Agent calls **Search Tools** to find relevant actions
3. Search Tools discovers available connectors and tool schemas via **MCP**, then ranks actions via the **Semantic Search API**
4. Search results are matched to MCP tool definitions, sorted by relevance
5. Agent receives a ranked `Tools` collection
6. Agent calls `execute()` on the selected tool

## Next Steps

* [Tool Search](/agents/python/tool-search) for full API reference and all three methods
* [Basic Usage](/agents/python/basic-usage) for fetching and executing tools
* [Tool Filtering](/agents/python/tool-filtering) for glob pattern filtering


# Basic Usage
Source: https://docs.stackone.com/agents/typescript/basic-usage

Learn the fundamentals of using the StackOne TypeScript SDK for AI agents

## Quick Start

The most common pattern: create a toolset and give your agent search and execute tools. The agent discovers and runs tools on demand.

```typescript theme={null}
import { StackOneToolSet } from "@stackone/ai";

// getTools returns the tool_search + tool_execute meta tools, so search must be
// enabled on the toolset (pass search: {} for defaults).
const toolset = new StackOneToolSet({ search: { method: "auto" } });

// Your agent gets 2 tools: tool_search + tool_execute
const tools = toolset.getTools({ accountIds: ["your-account-id"] });
const openaiTools = tools.toOpenAI();
```

Pass `openaiTools` to any OpenAI-compatible model and the agent will search for relevant tools, then execute them automatically. See the [OpenAI integration guide](/agents/typescript/frameworks/openai-integration) for a full agent loop.

## Fetch Tools

When you need specific tools instead of search and execute:

```typescript theme={null}
const tools = await toolset.fetchTools({ accountIds: ["your-account-id"] });
const openaiTools = tools.toOpenAI();
```

<AccordionGroup>
  <Accordion title="Filtering by provider, action, or pattern">
    ```typescript theme={null}
    // Filter by providers
    const byProviders = await toolset.fetchTools({
      providers: ["hibob", "workday"],
      accountIds: ["your-account-id"],
    });

    // Filter by actions with exact match
    const byActions = await toolset.fetchTools({
      actions: ["hibob_list_employees", "hibob_create_employees"],
      accountIds: ["your-account-id"],
    });

    // Filter by actions with glob patterns
    const byGlob = await toolset.fetchTools({
      actions: ["*_list_*"],
      accountIds: ["your-account-id"],
    });

    // Combine multiple filters
    const combined = await toolset.fetchTools({
      providers: ["hibob"],
      actions: ["*_list_*"],
      accountIds: ["your-account-id"],
    });
    ```

    See [Tool Filtering](/agents/typescript/tool-filtering) for the full reference.
  </Accordion>

  <Accordion title="Multi-account usage">
    ```typescript theme={null}
    // Set accounts on the toolset for all subsequent calls
    toolset.setAccounts(["account-123", "account-456"]);
    const tools = await toolset.fetchTools();

    // Or pass account IDs per request
    const toolsDirect = await toolset.fetchTools({
      accountIds: ["account-123", "account-456"],
    });

    // Loop over customer accounts dynamically
    const customerAccounts = ["account-1", "account-2", "account-3"];

    for (const accountId of customerAccounts) {
      const tools = await toolset.fetchTools({
        actions: ["workday_list_workers"],
        accountIds: [accountId],
      });
      const employeeTool = tools.getTool("workday_list_workers");
      if (employeeTool) {
        const employees = await employeeTool.execute({});
        console.log(`Found employees for ${accountId}`);
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Tool Execution

<AccordionGroup>
  <Accordion title="Direct tool execution (for debugging)">
    Direct execution is useful for testing and debugging. In production, your agent framework handles tool calls automatically.

    ```typescript theme={null}
    const tools = await toolset.fetchTools({ accountIds: ["your-account-id"] });
    const employeeTool = tools.getTool("workday_list_workers");

    if (employeeTool) {
      const result = await employeeTool.execute({
        query: { limit: 10 },
      });
      console.log(result);
    }
    ```
  </Accordion>

  <Accordion title="File downloads (binary responses)">
    Actions that download a file (for example `googledrive_unified_download_file`, `documents_download_file`, or any `*_unified_download_file`) return raw bytes plus metadata, not parsed JSON. The SDK decides from the response `Content-Type`: JSON is parsed as usual, and anything else is treated as a file download. Because `execute()` is typed to return a JSON object, use the exported `isBinaryDownloadResult` guard to narrow the result to the file shape.

    ```typescript theme={null}
    import { writeFileSync } from "node:fs";
    import { isBinaryDownloadResult } from "@stackone/ai";

    const tools = await toolset.fetchTools({
      actions: ["googledrive_*"],
      accountIds: ["your-account-id"],
    });
    const download = tools.getTool("googledrive_unified_download_file");

    if (download) {
      const result = await download.execute({ id: "file-id" });

      // isBinaryDownloadResult narrows result so content is a Buffer (no cast) and
      // confirms this was a file download rather than a JSON response.
      if (isBinaryDownloadResult(result)) {
        writeFileSync(result.fileName ?? "download.bin", result.content);
      }
    }
    ```

    The narrowed `result` describes the file:

    | Key           | Type             | Description                                                                    |
    | ------------- | ---------------- | ------------------------------------------------------------------------------ |
    | `content`     | `Buffer`         | Raw file bytes. Not JSON-serializable (see note).                              |
    | `contentType` | `string`         | File MIME type (for example `application/pdf`), or `application/octet-stream`. |
    | `statusCode`  | `number`         | HTTP status of the download response.                                          |
    | `headers`     | `object`         | Response headers.                                                              |
    | `fileName`    | `string \| null` | Filename from `Content-Disposition` (RFC 5987 `filename*` aware), else `null`. |

    <Warning>
      `content` is a `Buffer` and is not JSON-serializable. If you forward tool results to an LLM (or anything that re-serializes to JSON), handle or strip the `content` key. For example, base64-encode it on the LLM-facing path.
    </Warning>
  </Accordion>
</AccordionGroup>

## Environment Configuration

```bash theme={null}
export STACKONE_API_KEY=your_api_key
```

Account IDs are passed per-request when fetching tools or via `getTools({ accountIds: [...] })`.

## Next Steps

* [OpenAI Integration](/agents/typescript/frameworks/openai-integration) for building agents with function calling
* [Vercel AI SDK](/agents/typescript/frameworks/vercel-ai-sdk) for streaming workflows
* [Tool Search](/agents/typescript/tool-search) for natural language tool discovery
* [Tool Filtering](/agents/typescript/tool-filtering) for advanced filtering patterns


# OpenAI Integration
Source: https://docs.stackone.com/agents/typescript/frameworks/openai-integration

Build AI agents with OpenAI Functions using the StackOne TypeScript AI SDK

StackOne tools work with OpenAI's function calling to build AI agents that access business data.

## Overview

* **Convert tools** to OpenAI function schemas automatically
* **Execute functions** with built-in handling
* **Build agents** with conversational context
* **Multi-step workflows** for complex tasks

```typescript theme={null}
import OpenAI from 'openai';
import { StackOneToolSet } from '@stackone/ai';

/**
 * Create agent with tools for a specific account.
 *
 * In production, accountId comes from:
 * - User/tenant context
 * - Authentication middleware
 * - Database lookup
 */
// Get account ID from your app's auth context or StackOne dashboard
const accountId = 'your-account-id';

const openai = new OpenAI();
const toolset = new StackOneToolSet();

// Fetch tools dynamically for this account
const tools = await toolset.fetchTools({
  accountIds: [accountId]
});

// Convert to OpenAI format
const openAITools = tools.toOpenAI();

// Create completion with function calling
const completion = await openai.chat.completions.create({
  model: 'gpt-5.4',
  messages: [
    {
      role: 'system',
      content: 'You are an HR assistant with access to employee data.'
    },
    {
      role: 'user',
      content: 'How many employees do we have?'
    }
  ],
  tools: openAITools,
  tool_choice: 'auto'
});

// Execute any tool calls
const message = completion.choices[0].message;
if (message.tool_calls) {
  for (const toolCall of message.tool_calls) {
    const tool = tools.getTool(toolCall.function.name);
    if (tool) {
      const result = await tool.execute(
        JSON.parse(toolCall.function.arguments)
      );
      console.log('Result:', result.data);
    }
  }
}
```

## Dynamic Tool Loading

Load tools based on available integrations:

```typescript theme={null}
import { StackOneToolSet } from '@stackone/ai';

const toolset = new StackOneToolSet();

// Load all tools for specific accounts (most common)
const tools = await toolset.fetchTools({
  accountIds: ["account-123"]
});

// Optional: Filter by operation type for security
const tools = await toolset.fetchTools({
  accountIds: ["account-123"],
  actions: ["*_list_*", "*_get_*"]  // Only list and get operations (read-only)
});

// Convert to OpenAI format
const openAITools = tools.toOpenAI();
```

## Conversational Agents

Build multi-turn conversational agents:

```typescript theme={null}
import OpenAI from 'openai';

async function runConversationalAgent(accountId: string) {
  const openai = new OpenAI();
  const toolset = new StackOneToolSet();
  const tools = await toolset.fetchTools({ accountIds: [accountId] });
  const openAITools = tools.toOpenAI();

  const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [
    {
      role: 'system',
      content: 'You are an HR assistant with access to employee data.'
    }
  ];

  // Multi-turn conversation loop
  while (true) {
    const userInput = await getUserInput(); // Your function
    if (userInput === 'exit') break;

    messages.push({ role: 'user', content: userInput });

    const completion = await openai.chat.completions.create({
      model: 'gpt-5.4',
      messages,
      tools: openAITools,
      tool_choice: 'auto'
    });

    const message = completion.choices[0].message;
    messages.push(message);

    // Execute tool calls if any
    if (message.tool_calls) {
      for (const toolCall of message.tool_calls) {
        const tool = tools.getTool(toolCall.function.name);
        if (tool) {
          const result = await tool.execute(
            JSON.parse(toolCall.function.arguments)
          );
          messages.push({
            role: 'tool',
            tool_call_id: toolCall.id,
            content: JSON.stringify(result.data)
          });
        }
      }

      // Get final response after tool execution
      const finalCompletion = await openai.chat.completions.create({
        model: 'gpt-5.4',
        messages,
      });

      console.log(finalCompletion.choices[0].message.content);
      messages.push(finalCompletion.choices[0].message);
    } else {
      console.log(message.content);
    }
  }
}
```

## Best Practices

### Account ID from Context

```typescript theme={null}
// Get from user/tenant context
const accountId = req.user.stackoneAccountId;
const accountId = await getAccountForTenant(tenantId);
```

```typescript theme={null}
// Only expose read operations (optional - for security)
const tools = await toolset.fetchTools({
  accountIds: [accountId],
  actions: ["*_list_*", "*_get_*"]  // Only list and get
});

// Or exclude dangerous operations
const tools = await toolset.fetchTools({
  accountIds: [accountId],
  actions: ["!*_delete_*"]  // Everything except deletes
});
```

## Example

<GitHubCode lang="typescript">
  <iframe />
</GitHubCode>

## Agent-Driven Search

Let the LLM discover and execute tools on its own. Instead of loading all tools upfront, pass `tool_search` + `tool_execute` and the LLM finds what it needs:

```typescript theme={null}
const toolset = new StackOneToolSet({
  search: { method: 'semantic', topK: 3 },
  accountId: 'your-account-id',
});

const tools = toolset.getTools({ accountIds: ['your-account-id'] });
const openaiTools = tools.toOpenAI();

// LLM receives only 2 tools - it searches and executes autonomously
const response = await client.chat.completions.create({
  model: 'gpt-5.4',
  messages,
  tools: openaiTools,
  tool_choice: 'auto',
});
```

See [Tool Search](/agents/typescript/tool-search#agent-driven-search) for the full agent loop example.

## Next Steps

* [Basic Usage](/agents/typescript/basic-usage) for fetching and executing tools
* [Tool Search](/agents/typescript/tool-search) for search patterns
* [Tool Filtering](/agents/typescript/tool-filtering) for security
* [Vercel AI SDK](/agents/typescript/frameworks/vercel-ai-sdk) for alternative approach


# Vercel AI SDK
Source: https://docs.stackone.com/agents/typescript/frameworks/vercel-ai-sdk

Build AI applications with Vercel AI SDK and StackOne tools

StackOne tools work with [Vercel AI SDK](https://sdk.vercel.ai/) to build AI applications using React, Next.js, and other frameworks.

## Overview

* **Streaming responses** with real-time tool execution
* **React hooks** for building AI UIs
* **Multi-step tool calls** with automatic handling
* **Framework compatibility** with Next.js, React, Vue, and more

```typescript theme={null}
import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';
import { StackOneToolSet } from '@stackone/ai';

async function createAgentForAccount(accountId: string) {
  /**
   * Create agent with tools for a specific account.
   *
   * In production, accountId comes from:
   * - User/tenant context
   * - Authentication middleware
   * - Database lookup
   */
  const toolset = new StackOneToolSet();

  // Fetch tools dynamically for this account
  const tools = await toolset.fetchTools({
    accountIds: [accountId]
  });

  // Convert to Vercel AI SDK format
  const aiSdkTools = await tools.toAISDK();

  const { text } = await generateText({
    model: openai('gpt-5.4'),
    tools: aiSdkTools,
    prompt: 'Get employee details for id: c28xIQaWQ6MzM5MzczMDA2NzMzMzkwNzIwNA',
    maxSteps: 3,
  });

  return text;
}

// Use the agent
// Get account ID from your app's auth context or StackOne dashboard
const accountId = 'your-account-id';
const result = await createAgentForAccount(accountId);
```

## Dynamic Tool Loading

Load tools based on available integrations:

```typescript theme={null}
import { StackOneToolSet } from '@stackone/ai';

const toolset = new StackOneToolSet();

// Load all tools for specific accounts (most common)
const tools = await toolset.fetchTools({
  accountIds: ["account-123"]
});

// Optional: Filter by operation type for security
const tools = await toolset.fetchTools({
  accountIds: ["account-123"],
  actions: ["*_list_*", "*_get_*"]  // Only list and get operations (read-only)
});

// Convert to Vercel AI SDK format
const aiSdkTools = await tools.toAISDK();
```

## Streaming Responses

Build real-time AI applications with streaming:

```typescript theme={null}
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';

async function streamingAgent(accountId: string, prompt: string) {
  const toolset = new StackOneToolSet();
  const tools = await toolset.fetchTools({ accountIds: [accountId] });
  const aiSdkTools = await tools.toAISDK();

  const result = await streamText({
    model: openai('gpt-5.4'),
    tools: aiSdkTools,
    prompt,
    maxSteps: 5,
  });

  // Stream to client
  for await (const chunk of result.textStream) {
    process.stdout.write(chunk);
  }
}
```

## Multi-Tenant Support

Handle multiple customer accounts:

```typescript theme={null}
async function getAgentForUser(userId: string) {
  // Get user's account IDs from your database
  const accountIds = await db.getUserAccountIds(userId);

  const toolset = new StackOneToolSet();
  const tools = await toolset.fetchTools({ accountIds });

  return await tools.toAISDK();
}

// Usage in API endpoint
app.post('/api/chat', async (req, res) => {
  const { message, userId } = req.body;
  const tools = await getAgentForUser(userId);

  const result = await generateText({
    model: openai('gpt-5.4'),
    tools,
    prompt: message,
  });

  res.json({ response: result.text });
});
```

## Best Practices

### Account ID from Context

```typescript theme={null}
// Get from user/tenant context
const accountId = req.user.stackoneAccountId;
const accountId = await getAccountForTenant(tenantId);
```

### Error Handling

```typescript theme={null}
import { StackOneError } from '@stackone/ai';

try {
  const result = await generateText({ model, tools, prompt });
} catch (error) {
  if (error instanceof StackOneError) {
    console.error('StackOne error:', error.message);
    // Handle gracefully
  }
}
```

### Tool Filtering

```typescript theme={null}
// Only expose read operations (optional - for security)
const tools = await toolset.fetchTools({
  accountIds: [accountId],
  actions: ["*_list_*", "*_get_*"]  // Only list and get
});

// Or exclude dangerous operations
const tools = await toolset.fetchTools({
  accountIds: [accountId],
  actions: ["!*_delete_*"]  // Everything except deletes
});
```

## Example

<GitHubCode lang="typescript">
  <iframe />
</GitHubCode>

## Agent-Driven Search

Let the LLM discover tools on its own using `tool_search` + `tool_execute`:

```typescript theme={null}
const toolset = new StackOneToolSet({
  search: { method: 'semantic', topK: 3 },
  accountId: 'your-account-id',
});

const tools = toolset.getTools({ accountIds: ['your-account-id'] });

// LLM receives only 2 tools - it searches and executes autonomously
const { text } = await generateText({
  model: openai('gpt-5.4'),
  tools: await tools.toAISDK(),
  prompt: 'List my upcoming Calendly events for the next week.',
  stopWhen: stepCountIs(10),
});
```

See [Tool Search](/agents/typescript/tool-search#agent-driven-search) for more details.

## Next Steps

* [Basic Usage](/agents/typescript/basic-usage) for fetching and executing tools
* [Tool Search](/agents/typescript/tool-search) for search patterns
* [Tool Filtering](/agents/typescript/tool-filtering) for security
* [OpenAI Integration](/agents/typescript/frameworks/openai-integration) for alternative approach


# Installation
Source: https://docs.stackone.com/agents/typescript/installation

Install and setup the StackOne AI TypeScript SDK

Install the StackOne AI SDK for TypeScript/Node.js applications.

## Installation

Choose your preferred package manager:

```bash theme={null}
# Using npm
npm install @stackone/ai

# Using pnpm
pnpm add @stackone/ai

# Using yarn
yarn add @stackone/ai

# Using bun
bun add @stackone/ai
```

## Requirements

* Node.js 16.0 or higher
* TypeScript 4.5 or higher (recommended)

## Environment Setup

Set your API key as an environment variable:

```bash theme={null}
export STACKONE_API_KEY=your_api_key_here
```

Account IDs are passed per-request when fetching tools — see [Basic Usage](/agents/typescript/basic-usage).

## Verification

Test your installation:

```typescript theme={null}
import { StackOneToolSet } from '@stackone/ai';

const toolset = new StackOneToolSet();
console.log('✅ StackOne AI SDK installed successfully!');
```

## Next Steps

* [Learn basic usage](/agents/typescript/basic-usage) to start building
* [Integrate with OpenAI](/agents/typescript/frameworks/openai-integration)
* [Use with Vercel AI SDK](/agents/typescript/frameworks/vercel-ai-sdk)


# TypeScript Toolset
Source: https://docs.stackone.com/agents/typescript/introduction

Build connected agents with StackOne's TypeScript AI SDK & Toolset

Build AI agents that connect to Salesforce, Workday, Slack, Gmail, HubSpot, and 200+ other business systems. The TypeScript SDK integrates with OpenAI Functions and Vercel AI SDK, giving your agents the ability to read employee data, post messages, manage files, and more.

<Tip>
  **Not sure if the AI Toolset (SDK) is right for you?** Check out our [Agent Protocols Guide](/guides/calling-stackone-actions) to understand when to use AI Toolset (SDK) vs MCP vs A2A.
</Tip>

## Why StackOne?

<CardGroup>
  <Card title="200+ Providers" icon="plug">Connect to Salesforce, Workday, Slack, Gmail, and more through one SDK</Card>
  <Card title="Multi-Tenant" icon="users">Built-in customer isolation with `account_id` for each connection</Card>
  <Card title="AI-Native" icon="robot">Tools designed for LLM function calling and agent frameworks</Card>
  <Card title="Consistent Data" icon="database">Normalized schemas: no provider-specific parsing needed</Card>
</CardGroup>

## How It Works

<Frame>
  <img alt="StackOne Architecture" />
</Frame>

Your agent connects to StackOne, which handles authentication and data normalization for 200+ SaaS providers like Salesforce, Workday, Slack, and more.

| Component          | Description                                                                |
| ------------------ | -------------------------------------------------------------------------- |
| **Your Agent**     | Built with LangChain, CrewAI, OpenAI, Vercel AI, or any framework          |
| **StackOne**       | AI Integration Gateway: handles auth, transforms data, manages connections |
| **SaaS Providers** | Salesforce, Workday, Greenhouse, Slack, Gmail, HubSpot, and 200+ more      |

## Key Concepts

* **Initialize a ToolSet**: Create a `StackOneToolSet` instance to access tools for providers like Workday, Greenhouse, Slack, and more
* **Filter Tools**: Use provider glob patterns like `workday_*`, `slack_*`, or `salesforce_*` to get specific tool sets
* **Execute Tools**: Call provider APIs through StackOne tool interfaces: list employees, send messages, create tickets
* **Multi-Tenant**: Each tool execution requires an `accountId` to identify which customer's account to access

## TypeScript Framework Integrations

<CardGroup>
  <Card title="OpenAI Integration" href="/agents/typescript/frameworks/openai-integration" icon="https://mintcdn.com/stackone-60/zRAvvofCYLmP9UF6/images/agents/openai-logo.svg?fit=max&auto=format&n=zRAvvofCYLmP9UF6&q=85&s=a38c135695435b960bc6b40052de4ad0">
    Build agents with OpenAI Functions
  </Card>

  <Card title="Vercel AI SDK" href="/agents/typescript/frameworks/vercel-ai-sdk" icon="https://mintcdn.com/stackone-60/Sj5Uq6vhX_QV0uhL/images/agents/vercel-logo.svg?fit=max&auto=format&n=Sj5Uq6vhX_QV0uhL&q=85&s=5b45db3b36ee27b056e5e0baa82ca2da">
    Use with Vercel's AI SDK for streaming and tool calls
  </Card>
</CardGroup>

## TypeScript Core Features

<CardGroup>
  <Card title="Tool Filtering" href="/agents/typescript/tool-filtering" icon="filter">
    Advanced glob pattern filtering for tool selection
  </Card>

  <Card title="Tool Search" href="/agents/typescript/tool-search" icon="magnifying-glass">
    Discover tools using natural language queries
  </Card>

  <Card title="Installation" href="/agents/typescript/installation" icon="download">
    Set up the TypeScript SDK
  </Card>

  <Card title="Basic Usage" href="/agents/typescript/basic-usage" icon="play">
    Core concepts and fundamental usage patterns
  </Card>
</CardGroup>

## TypeScript-Specific Features

* **Type Safety**: Full TypeScript support with comprehensive type definitions
* **Framework Support**: Native integrations with OpenAI, Vercel AI SDK, and more
* **File Handling**: Built-in support for file uploads and transformations

## Next Steps

1. [Build your first OpenAI agent](/agents/typescript/frameworks/openai-integration)
2. [Learn about tool filtering](/agents/typescript/tool-filtering)
3. [Explore Tool Search](/agents/typescript/tool-search)

## Resources

* **[GitHub Repository](https://github.com/StackOneHQ/stackone-ai-node)**: Complete source code and examples
* **[Examples](https://github.com/StackOneHQ/stackone-ai-node/tree/main/examples)**: OpenAI integration, semantic search, and file uploads
* **[Issues](https://github.com/StackOneHQ/stackone-ai-node/issues)**: Report bugs or request features
* **[NPM Package](https://www.npmjs.com/package/@stackone/ai)**: Package details and version history


# Tool Defense
Source: https://docs.stackone.com/agents/typescript/tool-defense

Configure StackOne Defender per-toolset from the Node.js SDK: scan tool call responses, block on risk, or defer to your project dashboard

<Info>
  New to tool defense? Start with [Tool Defense 101](/agents/typescript/tool-defense-101) for an overview of why, how, and when to use it.
</Info>

## Configuration Modes

The `defender` option on `StackOneToolSet` accepts four shapes. Each maps to a distinct behavior for the RPC calls that toolset makes.

### Default (defer to project dashboard)

Omitting `defender` leaves the project's dashboard setting in charge. The SDK adds no `defender_config` field to the RPC payload, so whatever you configured in the StackOne dashboard takes effect.

```typescript theme={null}
import { StackOneToolSet } from '@stackone/ai';

const toolset = new StackOneToolSet();
// defenderMode === 'project'
```

The explicit form is equivalent:

```typescript theme={null}
const toolset = new StackOneToolSet({
  defender: { useProjectSettings: true },
});
// defenderMode === 'project'
```

Use the explicit form when you want the call site to document that deferring is intentional rather than an oversight. `useProjectSettings: true` cannot be combined with other defender fields; passing both throws a `ToolSetConfigError` at construction time.

### Explicit SDK-level config

Pass an object to override your project's dashboard setting with explicit per-toolset values. Missing fields fall back to `DEFAULT_DEFENDER_CONFIG`, which has all scanning on and blocking off.

```typescript theme={null}
import { DEFAULT_DEFENDER_CONFIG, StackOneToolSet } from '@stackone/ai';

// Opt in with safe defaults, but block on HIGH or CRITICAL risk
const toolset = new StackOneToolSet({
  defender: { ...DEFAULT_DEFENDER_CONFIG, blockHighRisk: true },
});
// defenderMode === 'explicit'

// Fully specified
const fullyExplicit = new StackOneToolSet({
  defender: {
    enabled: true,
    blockHighRisk: false,
    useTier1Classification: true,
    useTier2Classification: false, // skip ML scoring on this toolset
  },
});
```

| Field                    | Type      | Fallback | Description                                          |
| ------------------------ | --------- | -------- | ---------------------------------------------------- |
| `enabled`                | `boolean` | `true`   | Master switch for this toolset                       |
| `blockHighRisk`          | `boolean` | `false`  | Throw on HIGH or CRITICAL risk instead of annotating |
| `useTier1Classification` | `boolean` | `true`   | Pattern-based detection (regex, role markers)        |
| `useTier2Classification` | `boolean` | `true`   | ML-based detection (local ONNX model)                |

### Force disabled

Pass `null` to forcibly disable defender for this toolset. The SDK sends `defender_config` with every field set to `false`, overriding whatever the dashboard says.

```typescript theme={null}
const toolset = new StackOneToolSet({ defender: null });
// defenderMode === 'disabled'
```

Use this for trusted internal flows where you've already vetted the data source and want to avoid scanning latency.

## Inspecting the Resolved Mode

Every toolset exposes a `defenderMode` getter that returns one of three strings:

```typescript theme={null}
const toolset = new StackOneToolSet({
  defender: { ...DEFAULT_DEFENDER_CONFIG, blockHighRisk: true },
});

toolset.defenderMode; // 'project' | 'disabled' | 'explicit'
```

| Value        | Meaning                                                                        |
| ------------ | ------------------------------------------------------------------------------ |
| `'project'`  | SDK adds no `defender_config`; the project dashboard setting controls behavior |
| `'disabled'` | SDK forces defender off, overriding the dashboard                              |
| `'explicit'` | SDK sends an explicit `defender_config`, overriding the dashboard              |

The getter is useful in tests, custom observability, and conditional logging without poking at private internals.

### Override warning

When the SDK overrides the project dashboard (modes `disabled` or `explicit`), it emits a `console.warn` once per process per distinct override shape. Repeat constructions with the same configuration stay quiet, so wrapping the SDK in a per-request factory will not flood your logs.

```
Defender forcibly disabled via SDK config; project dashboard setting will be ignored.
Defender configured via SDK (enabled=true, blockHighRisk=true, useTier1Classification=true, useTier2Classification=true); project dashboard setting will be ignored.
```

## Reading the Response

When defender runs (modes `explicit` or, on the backend side, when `project` mode resolves to enabled), the RPC response includes a `defenderMetadata` sibling next to `data`:

```typescript theme={null}
const tools = await toolset.fetchTools();
const tool = tools.toArray().find((t) => t.name === 'gmail_list_messages');

const result = await tool.execute({ body: { max_results: 5 } });

const metadata = (result as { defenderMetadata?: DefenderMetadata }).defenderMetadata;

interface DefenderMetadata {
  applied: boolean;
  result: {
    allowed: boolean;
    riskLevel: 'low' | 'medium' | 'high' | 'critical';
    fieldsSanitized: string[];
    patternsByField: Record<string, string[]>;
    detections: unknown[];
    tier2SkipReason?: string;
    latencyMs: number;
  };
}
```

| Field                    | Description                                                                                                       |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `applied`                | `false` when defender was configured but skipped (e.g. all classification disabled), `true` when it ran           |
| `result.allowed`         | `false` only when `blockHighRisk` was on and content classified as HIGH or CRITICAL caused the call to be blocked |
| `result.riskLevel`       | Final risk classification for the response                                                                        |
| `result.fieldsSanitized` | JSON paths to fields whose content was annotated or stripped                                                      |
| `result.patternsByField` | Per-field map of detection pattern IDs that fired                                                                 |
| `result.detections`      | Raw detection records from Tier 1 / Tier 2                                                                        |
| `result.tier2SkipReason` | Present only when Tier 2 was skipped (e.g. `"No strings extracted from tool result"`)                             |
| `result.latencyMs`       | Time defender spent classifying this response                                                                     |

A typed accessor is not yet exposed on the SDK response surface, so casting through the response object is the current ergonomic.

## Runtime Validation

The constructor validates `useProjectSettings: true` is not combined with other defender fields. JavaScript callers that bypass TypeScript get a runtime error:

```typescript theme={null}
new StackOneToolSet({
  defender: { useProjectSettings: true, enabled: true },
});
// throws ToolSetConfigError:
// "Cannot combine useProjectSettings: true with explicit defender options. Use one or the other."
```

TypeScript catches this at compile time via the discriminated union; the runtime guard exists for JS consumers and runtime-built configs.

## Next Steps

* [Full runnable example](https://github.com/StackOneHQ/stackone-ai-node/blob/main/examples/defender-config.ts) covering all four modes, the `defenderMode` getter, and the override warning
* [Defender (platform guide)](/guides/defender) for dashboard configuration, detection pipeline, and risk thresholds
* [Tool Filtering](/agents/typescript/tool-filtering) for scoping toolsets by provider, action, or account
* [Basic Usage](/agents/typescript/basic-usage) for fetching and executing tools


# Tool Defense 101
Source: https://docs.stackone.com/agents/typescript/tool-defense-101

Protect your AI agents from prompt injection by scanning tool call responses, configured per-toolset from the SDK

Tool Defense protects your AI agents from prompt injection attacks by scanning tool call responses before they reach your LLM. Configure scanning behavior per-toolset from the SDK, or defer to your project's dashboard setting.

<Tabs>
  <Tab title="Why Tool Defense" label="Why">
    **The Problem**: AI agents that call third-party APIs consume data they didn't author: emails, CRM notes, calendar events, support tickets, documents. That data can contain content designed to hijack the agent's behavior, such as hidden instructions, role markers, encoded payloads, or jailbreak phrases.

    * **Indirect prompt injection**: an attacker plants instructions in a document or message the agent will eventually read
    * **Cross-account leaks**: a malicious record in one tool can attempt to steer the agent toward exfiltrating data from another
    * **Silent failures**: without scanning, you never see the attack, only the agent's surprising downstream behavior

    **The Solution**: Tool Defense scans every tool call response, classifies risk, and surfaces annotations so you can observe, block, or both. Configuration is per-toolset, so different parts of your application can opt in or out independently of project-wide settings.
  </Tab>

  <Tab title="How It Works" label="How">
    Tool Defense runs server-side as part of every RPC call your SDK makes. The SDK is the wiring layer that forwards your config and reads back what defender produced.

    **Two-stage pipeline**

    1. **Tier 1 — Pattern matching**: fast rule-based scan for known injection signatures (role markers, encoded payloads, instruction overrides). Adds negligible latency.
    2. **Tier 2 — AI classification**: a local ML model scores risky fields surfaced by Tier 1. Only runs when Tier 1 flags content; never calls an external API.

    **Four SDK modes**

    | `defender` option                 | Wire payload | Behavior                                        |
    | --------------------------------- | ------------ | ----------------------------------------------- |
    | omitted *(default)*               | none         | Project dashboard setting controls              |
    | `{ useProjectSettings: true }`    | none         | Same as omitting (explicit, self-documenting)   |
    | `{ enabled, blockHighRisk, ... }` | full config  | SDK-level config wins, overrides dashboard      |
    | `null`                            | all-false    | Defender forcibly disabled, overrides dashboard |

    For the dashboard side (pattern catalog, risk thresholds, large-response behavior), see the platform-level [Defender](/guides/defender) guide.
  </Tab>

  <Tab title="When to Use" label="When">
    **Use it when**:

    * Your agent consumes third-party tool results (emails, CRM, documents, calendar events, support tickets)
    * You want injection signals visible in your logs even when you're not blocking
    * Different toolsets in your app need different policies (e.g., scan everything in a customer-facing agent but skip in a trusted internal job)
    * You want to override or defer to your project dashboard on a per-toolset basis

    **Skip it when**:

    Skip Tool Defense if all your tool calls hit fully-trusted internal systems with no third-party data ingress, or if you're already running your own injection detection in front of the LLM and want to avoid duplicate work.
  </Tab>

  <Tab title="Examples" label="Examples">
    **Real-world use cases**:

    * **Inbox triage**: an agent reading a customer's Gmail inbox sees a malicious "ignore previous instructions" payload buried in an email body; Tier 1 catches the role marker, defender annotates the response, your logs show the risk level
    * **CRM enrichment**: an agent pulls contact notes from HubSpot for sales summarization; Tier 2 detects a high-confidence injection attempt and (with blocking enabled) the call returns blocked instead of poisoning the agent's context
    * **Mixed-trust pipelines**: an internal-tooling toolset runs with `defender: null` for speed; a customer-facing toolset runs with `defender: { ...DEFAULT_DEFENDER_CONFIG, blockHighRisk: true }` for safety

    In every case, the response metadata surfaces risk level and detection signals so the choice is visible, even when nothing is blocked.
  </Tab>
</Tabs>

### Key Features

<CardGroup>
  <Card title="Per-Toolset Configuration" icon="sliders">
    Different toolsets can opt in or out of scanning independently, overriding your project's dashboard setting per construction.
  </Card>

  <Card title="Observable by Default" icon="binoculars">
    Risk level, sanitized fields, and detection patterns come back in the response metadata even when not blocking.
  </Card>

  <Card title="Runtime Override Warning" icon="bell">
    The SDK warns once per process when it overrides your dashboard setting, so the choice is visible in your logs.
  </Card>

  <Card title="Mode Introspection" icon="magnifying-glass">
    The `defenderMode` getter exposes the resolved mode (`project` / `disabled` / `explicit`) for tests and observability.
  </Card>
</CardGroup>

## Quick Example

```typescript theme={null}
import { StackOneToolSet, DEFAULT_DEFENDER_CONFIG } from '@stackone/ai';

// 1. Default: defer to your project's dashboard defender setting
const dashboardToolset = new StackOneToolSet();

// 2. Explicit opt-in with safe defaults
const scanningToolset = new StackOneToolSet({
  defender: { ...DEFAULT_DEFENDER_CONFIG },
});

// 3. Block on HIGH or CRITICAL risk
const strictToolset = new StackOneToolSet({
  defender: { ...DEFAULT_DEFENDER_CONFIG, blockHighRisk: true },
});

// 4. Forcibly disabled, overrides the dashboard
const offToolset = new StackOneToolSet({ defender: null });
```

## Inspecting the Resolved Mode

Use the `defenderMode` getter to assert how a toolset will behave:

```typescript theme={null}
const toolset = new StackOneToolSet({ defender: null });

toolset.defenderMode; // 'project' | 'disabled' | 'explicit'
```

When the SDK overrides your project dashboard (modes `disabled` or `explicit`), it emits a yellow `console.warn` once per process per distinct override shape, so the override is visible at runtime without flooding your logs. Set `NO_COLOR=1` to suppress color, or `FORCE_COLOR=1` to force it when piping output.

## Reading the Response

When defender runs, the RPC response includes a `defenderMetadata` sibling next to `data`:

```typescript theme={null}
const result = await tool.execute({ body: {} });

const metadata = (result as { defenderMetadata?: unknown }).defenderMetadata;
// {
//   applied: true,
//   result: {
//     allowed: true,                                          // false → blocked when blockHighRisk
//     riskLevel: 'low' | 'medium' | 'high' | 'critical',
//     fieldsSanitized: string[],
//     patternsByField: Record<string, string[]>,
//     detections: unknown[],
//     latencyMs: number,
//   },
// }
```

## Next Steps

* [Tool Defense](/agents/typescript/tool-defense) for the full API reference: all four modes, `defenderMetadata` shape, override warning behavior
* [Defender (platform guide)](/guides/defender) for dashboard configuration, detection pipeline, and risk thresholds
* [Basic Usage](/agents/typescript/basic-usage) for fetching and executing tools


# Tool Filtering
Source: https://docs.stackone.com/agents/typescript/tool-filtering

Filter tools when using the StackOne TypeScript AI SDK

The StackOne SDK provides glob-based filtering capabilities to help you select and manage specific tools across different SaaS platforms.

## What Tool Filtering Enables

Tool filtering allows you to:

* Select tools by provider (e.g., Salesforce, Gmail, Workday)
* Filter by specific actions (create, read, update, delete)
* Combine multiple patterns for precise selection
* Exclude specific tools or patterns

## Basic Filtering Patterns

### By Provider

* `salesforce_*` - Salesforce CRM
* `gmail_*` - Gmail & Calendar
* `workday_*` - Workday HCM

### By Action

* `*_create_*` - All create operations
* `*_list_*` - All list operations
* `*_get_*` - All get operations

### Combined Patterns

* `hibob_list_*` - HiBob list operations only
* `workday_update_*` - Workday update operations only

## Use Cases

1. **Cross-Domain Agents**: Let assistants reliably interact with whatever tools (CRMs, ERPs, comms suites, etc.) are available for the current account
2. **Operation-Focused Tools**: Create specialized agents for read-only or write operations
3. **Custom Tool Sets**: Combine multiple patterns for precise control
4. **Performance Optimization**: Load only the tools your agent actually needs

## TypeScript Naming Conventions

### Tool Name Structure

StackOne tools follow the pattern: `provider_operation_entity`

```typescript theme={null}
import { StackOneToolSet } from '@stackone/ai';

const toolset = new StackOneToolSet();

// Filter by providers
const tools = await toolset.fetchTools({
  providers: ['hibob', 'workday'],
});

// Filter by actions with glob patterns
const listTools = await toolset.fetchTools({
  actions: ['*_list_*'],
});

// Get specific employee tools
const employeeTools = await toolset.fetchTools({
  actions: ['*_list_employees', '*_get_employee'],
});
```

### Common Patterns

**By Provider:**

* `workday_*` - Workday
* `hibob_*` - HiBob
* `greenhouse_*` - Greenhouse

**By Operation:**

* `*_list_*` - Get multiple records
* `*_get_*` - Get single record
* `*_create_*` - Create new record
* `*_update_*` - Update existing record

**By Entity:**

* `*_employees` - Employee operations
* `*_candidates` - Candidate operations
* `*_contacts` - Contact operations

## Example

<GitHubCode lang="typescript">
  <iframe />
</GitHubCode>

## Next Steps

* [Tool Search](/agents/typescript/tool-search) - Natural language tool discovery
* [OpenAI Integration](/agents/typescript/frameworks/openai-integration) - Use filtered tools


# Tool Search
Source: https://docs.stackone.com/agents/typescript/tool-search

Discover tools using natural language queries with semantic, local, or auto search modes

<Info>
  New to tool search? Start with [Tool Search 101](/agents/typescript/tool-search-101) for an overview of why, how, and when to use it.
</Info>

## Agent-Driven Search (Recommended)

The simplest way to use tool search: give your agent `tool_search` and `tool_execute`, and let it discover tools on demand.

```typescript theme={null}
import { StackOneToolSet } from '@stackone/ai';

const toolset = new StackOneToolSet();

// LLM receives only 2 tools: tool_search + tool_execute
const tools = toolset.getTools();
const openaiTools = tools.toOpenAI();
```

<Tip>
  Only 2 tools are sent to the LLM regardless of how many tools exist in your catalog. Token usage stays constant.
</Tip>

### Framework Examples

<CodeGroup>
  ```typescript Vercel AI SDK theme={null}
  import { openai } from '@ai-sdk/openai';
  import { StackOneToolSet } from '@stackone/ai';
  import { generateText, stepCountIs } from 'ai';

  // Uses STACKONE_API_KEY and STACKONE_ACCOUNT_ID from environment
  const toolset = new StackOneToolSet({
    search: { method: 'semantic', topK: 3 },
  });

  // LLM receives only 2 tools: tool_search + tool_execute
  const tools = toolset.getTools();

  const { text } = await generateText({
    model: openai('gpt-5.4'),
    tools: await tools.toAISDK(),
    prompt: 'List my upcoming Calendly events for the next week.',
    stopWhen: stepCountIs(10),
  });

  console.log(text);
  ```

  ```typescript OpenAI theme={null}
  import OpenAI from 'openai';
  import { StackOneToolSet } from '@stackone/ai';

  // Uses STACKONE_API_KEY and STACKONE_ACCOUNT_ID from environment
  const toolset = new StackOneToolSet({
    search: { method: 'semantic', topK: 3 },
  });

  // LLM receives only 2 tools: tool_search + tool_execute
  const tools = toolset.getTools();
  const openaiTools = tools.toOpenAI();

  const client = new OpenAI();
  const messages = [
    {
      role: 'system' as const,
      content:
        'Use tool_search to find relevant tools, then tool_execute to run them. ' +
        'Read parameter schemas from tool_search results carefully.',
    },
    { role: 'user' as const, content: 'List my upcoming Calendly events for the next week.' },
  ];

  for (let i = 0; i < 10; i++) {
    const response = await client.chat.completions.create({
      model: 'gpt-5.4',
      messages,
      tools: openaiTools,
      tool_choice: 'auto',
    });

    const choice = response.choices[0];
    if (!choice.message.tool_calls?.length) {
      console.log(choice.message.content);
      break;
    }

    messages.push(choice.message);
    for (const toolCall of choice.message.tool_calls) {
      const tool = tools.getTool(toolCall.function.name);
      const result = tool ? await tool.execute(toolCall.function.arguments) : { error: 'Unknown tool' };
      messages.push({ role: 'tool', tool_call_id: toolCall.id, content: JSON.stringify(result) });
    }
  }
  ```
</CodeGroup>

## Manual Search

When you need to find tools yourself before passing them to an agent:

```typescript theme={null}
import { StackOneToolSet } from '@stackone/ai';

const toolset = new StackOneToolSet();
const tools = await toolset.searchTools('manage employee records');

// Use with any framework
const openAITools = tools.toOpenAI();
const aiSdkTools = await tools.toAISDK();
```

No configuration needed. Defaults to auto mode with sensible defaults.

<AccordionGroup>
  <Accordion title="Search modes (auto, semantic, local)">
    | Mode       | Behaviour                                                                                                                                               |
    | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `auto`     | Tries semantic API first, falls back to local search on failure. Recommended for production.                                                            |
    | `semantic` | Strict mode. Uses semantic API only, throws `SemanticSearchError` on failure.                                                                           |
    | `local`    | Hybrid BM25 + TF-IDF search entirely in-process (powered by [Orama](https://orama.com/)). No network call. Useful for offline or low-latency scenarios. |

    ```typescript theme={null}
    // Auto (default)
    const tools = await toolset.searchTools('manage employees', { search: 'auto' });

    // Semantic only
    const tools = await toolset.searchTools('manage employees', { search: 'semantic' });

    // Local only
    const tools = await toolset.searchTools('manage employees', { search: 'local' });
    ```
  </Accordion>

  <Accordion title="Constructor configuration">
    Set default search options at the constructor level. These apply to all search calls unless overridden per-call.

    ### SearchConfig Options

    | Option          | Type                              | Description                             |
    | --------------- | --------------------------------- | --------------------------------------- |
    | `method`        | `'auto' \| 'semantic' \| 'local'` | Search mode (default: `'auto'`)         |
    | `topK`          | `number`                          | Maximum number of tools to return       |
    | `minSimilarity` | `number`                          | Minimum relevance score threshold (0-1) |

    ```typescript theme={null}
    import { StackOneToolSet } from '@stackone/ai';

    // Custom search config
    const toolset = new StackOneToolSet({ search: { method: 'semantic', topK: 5 } });

    // Disable search
    const toolset = new StackOneToolSet({ search: null });

    // Default: search enabled with method: 'auto'
    const toolset = new StackOneToolSet();
    ```

    Per-call overrides take precedence over constructor defaults:

    ```typescript theme={null}
    // Constructor sets topK=5 for all search calls
    const toolset = new StackOneToolSet({ search: { method: 'semantic', topK: 5 } });

    // Uses constructor defaults: method='semantic', topK=5
    const tools = await toolset.searchTools('manage employees');

    // topK overridden to 10 for this call; method remains 'semantic'
    const tools = await toolset.searchTools('manage employees', { topK: 10 });
    ```
  </Accordion>

  <Accordion title="Parameters reference">
    | Parameter       | Type                              | Description                                       |
    | --------------- | --------------------------------- | ------------------------------------------------- |
    | `topK`          | `number`                          | Maximum number of tools to return                 |
    | `search`        | `'auto' \| 'semantic' \| 'local'` | Search mode (default: `'auto'`)                   |
    | `connector`     | `string`                          | Filter to a specific provider (e.g., `'workday'`) |
    | `minSimilarity` | `number`                          | Minimum relevance score threshold (0-1)           |
    | `accountIds`    | `string[]`                        | Override account IDs for this search              |
  </Accordion>
</AccordionGroup>

## Advanced Patterns

<AccordionGroup>
  <Accordion title="searchActionNames(), lightweight preview">
    Returns action names and similarity scores without fetching full tool definitions. Use it to inspect results before committing to a full fetch.

    ```typescript theme={null}
    const results = await toolset.searchActionNames('manage employees', {
      topK: 5,
    });

    for (const result of results) {
      console.log(`${result.id}: ${result.similarityScore}`);
    }
    ```

    <Tip>
      `searchActionNames()` works with just `STACKONE_API_KEY`, no account ID needed. When called without `accountIds`, results come from the full StackOne catalog.
    </Tip>
  </Accordion>

  <Accordion title="getSearchTool(), callable for custom agent loops">
    Returns a reusable `SearchTool` for agent loops where the LLM decides what to search for.

    ```typescript theme={null}
    const searchTool = toolset.getSearchTool({ search: 'auto' });

    // In an agent loop, search for tools as needed
    const queries = [
      'create a new employee',
      'list job candidates',
      'send a message to a channel',
    ];

    for (const query of queries) {
      const tools = await searchTool.search(query, { topK: 3 });
      const toolNames = tools.toArray().map((t) => t.name);
      console.log(`"${query}" -> ${toolNames.join(', ')}`);
    }
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

* [OpenAI Integration](/agents/typescript/frameworks/openai-integration)
* [Vercel AI SDK](/agents/typescript/frameworks/vercel-ai-sdk)
* [Tool Filtering](/agents/typescript/tool-filtering)


# Tool Search 101
Source: https://docs.stackone.com/agents/typescript/tool-search-101

How StackOne's tool search finds the right tools from thousands of actions using natural language

Tool search enables AI agents to discover the right tools using natural language queries, without requiring exact action names.

<Tabs>
  <Tab title="Why Tool Search" label="Why">
    **The Problem**: StackOne manages over 10,000 actions across connectors, with some containing 2,000+ actions. Loading all of them into an LLM's context window is not practical:

    * **Token bloat**: every tool definition consumes tokens, leaving less room for reasoning
    * **Accuracy drops**: LLMs make worse tool selections as the candidate set grows
    * **Provider caps**: OpenAI caps function definitions at \~128 per request

    **The Solution**: More tools does not mean more capability. Without structure, they become noise. Tool search finds only the relevant tools for each query, keeping agent prompts lean while expanding their capabilities.
  </Tab>

  <Tab title="How It Works" label="How">
    **Search Flow**

    1. **Search**: Your agent calls the search method with a natural language query
    2. **Discover**: The SDK fetches available connectors and tool definitions from your linked accounts via MCP
    3. **Match**: Each connector is searched in parallel via the semantic search API
    4. **Rank**: Results are matched to MCP tool definitions, ranked by relevance, deduplicated
    5. **Return**: A `Tools` collection is returned, ready for any framework

    The agent only sees the tools it needs, not the entire catalog.

    **Three Search Modes**

    | Mode             | Behavior                                                            | When to use                                                     |
    | ---------------- | ------------------------------------------------------------------- | --------------------------------------------------------------- |
    | `auto` (default) | Tries the semantic API first, falls back to local search on failure | Production use: best accuracy with built-in resilience          |
    | `semantic`       | Semantic API only. Throws an error if the API is unavailable.       | When you need strict control and want to handle errors yourself |
    | `local`          | Hybrid BM25 + TF-IDF search, entirely in-process. No network call.  | Offline environments or when you need minimal latency           |

    **Local search** scores results with `0.2 * BM25 + 0.8 * TF-IDF` and runs with no network calls.

    **Semantic search** uses enriched embeddings where action descriptions are expanded with related terms before embedding. For example, "Create Employee" is enriched with synonyms like "add new", "insert", "worker", "staff", "team member", so natural language queries match even when wording differs.
  </Tab>

  <Tab title="Benchmarks" label="Benchmarks">
    Tested across 103 semantically-challenging queries against 9,340 actions:

    | Approach            | Hit\@5 (all connectors) | Hit\@5 (per connector) |
    | ------------------- | ----------------------- | ---------------------- |
    | BM25 only           | 21%                     | 65%                    |
    | Enhanced Embeddings | 84%                     | 90%                    |

    BM25 keyword matching works well for exact terms but fails on natural language. For example, searching "onboard new hire" won't match "Create Employee" with BM25 alone.

    For comparison, Anthropic's built-in [tool search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool) uses BM25 matching. StackOne's semantic mode uses enriched embeddings for higher accuracy on natural language queries.
  </Tab>

  <Tab title="Examples" label="Examples">
    **Real-World Use Cases**:

    * **HR Agent**: "Approve Alice's time off request" finds `hibob_create_time_off` and executes in HiBob
    * **Support Agent**: "Search for Jira ticket ABC-123" finds `ticketing_ticket_list` and returns details
    * **Knowledge Agent**: "Find training docs on GDPR" finds `documents_file_search` and queries KB

    **When to Use**:

    Use tool search when your agent spans many SaaS systems (dozens to thousands of tools) and you need higher selection accuracy and scalability.

    Skip tool search if you have a very small, static toolset where you can load all tools directly.
  </Tab>
</Tabs>

### Key Features

<CardGroup>
  <Card title="Scales to Thousands of Tools" icon="chart-line">
    StackOne has 10,000+ actions. Search returns only the relevant ones for each query.
  </Card>

  <Card title="Improves Accuracy" icon="bullseye">
    Only relevant tools exposed per request, reducing misfires and hallucinations.
  </Card>

  <Card title="Account-Aware" icon="shield-check">
    Filters results to tools available for configured account IDs, respecting auth boundaries.
  </Card>

  <Card title="Framework-Ready" icon="puzzle-piece">
    Returns a Tools collection with converters for OpenAI, LangChain, Vercel AI SDK, and more.
  </Card>
</CardGroup>

## Quick Example

```typescript theme={null}
import { StackOneToolSet } from '@stackone/ai';

const toolset = new StackOneToolSet();

// Get search & execute tools. The LLM discovers and runs tools on demand
const tools = toolset.getTools();

// Convert to your framework's format
const openAITools = tools.toOpenAI();
// Pass these to your OpenAI agent
```

## Two Approaches

<Tabs>
  <Tab title="Search & Execute (recommended)">
    **Give the LLM 2 tools — it discovers and runs actions on demand.**

    Instead of pre-filtering, you give the LLM `tool_search` and `tool_execute`. The LLM searches for relevant tools, reads their parameter schemas, and executes them within its own reasoning loop.

    Best for:

    * Open-ended assistants ("help me with any HR task")
    * Large tool catalogs where pre-filtering is impractical
    * When you don't know which tools will be needed upfront
    * Minimal token overhead — always 2 tools regardless of catalog size
  </Tab>

  <Tab title="Pre-filtered">
    **You search first, LLM gets a focused set of tools.**

    Your code calls `searchTools()` or `fetchTools()` with filters, gets back a `Tools` collection, and passes those to the LLM. The LLM only sees relevant tools.

    Best for:

    * Known tasks where you can predict which tools are needed
    * Constrained agents with a focused scope
    * When you want full control over which tools the LLM can access
  </Tab>
</Tabs>

| Aspect            | Search & Execute                          | Pre-filtered                |
| ----------------- | ----------------------------------------- | --------------------------- |
| Tools sent to LLM | Always 2 (`tool_search` + `tool_execute`) | Filtered set (5-20)         |
| Token cost        | Constant                                  | Scales with number of tools |
| Discovery         | LLM discovers on-demand                   | You search upfront          |
| Use case          | Open-ended, exploratory                   | Constrained, known tasks    |

## Architecture Overview

```mermaid theme={null}
graph TB
    User["User"] --> Agent["Your AI Agent"]
    Agent --> SearchTools["Search Tools"]
    Agent --> SearchActionNames["Search Action Names"]
    SearchTools --> MCP["MCP Server"]
    SearchTools --> SemanticAPI["Semantic Search API"]
    SearchTools --> Agent
    Agent --> Execute["Execute Tool"]

    style User fill:#f3f4f6,stroke:#d1d5db,stroke-width:2px,color:#374151
    style Agent fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af
    style SearchTools fill:#4ade80,stroke:#22c55e,stroke-width:2px,color:#15803d
    style SearchActionNames fill:#4ade80,stroke:#22c55e,stroke-width:2px,color:#15803d
    style SemanticAPI fill:#16a34a,stroke:#15803d,stroke-width:2px,color:#fff
    style MCP fill:#16a34a,stroke:#15803d,stroke-width:2px,color:#fff
    style Execute fill:#16a34a,stroke:#15803d,stroke-width:2px,color:#fff
```

**Flow:**

1. User sends a natural language query to your AI agent
2. Agent calls **Search Tools** to find relevant actions
3. Search Tools discovers available connectors and tool schemas via **MCP**, then ranks actions via the **Semantic Search API**
4. Search results are matched to MCP tool definitions, sorted by relevance
5. Agent receives a ranked `Tools` collection
6. Agent calls `execute()` on the selected tool

## Next Steps

* [Tool Search](/agents/typescript/tool-search) for full API reference and all three methods
* [Basic Usage](/agents/typescript/basic-usage) for fetching and executing tools
* [Tool Filtering](/agents/typescript/tool-filtering) for glob pattern filtering


# Actions Metadata for Custom UIs
Source: https://docs.stackone.com/api/actions-metadata

Build dynamic interfaces by querying available actions, parameters, and provider capabilities

When building a platform on StackOne, you can dynamically discover what actions are available for each linked account. This enables you to build custom UIs that adapt to each provider's capabilities.

<Info>
  This guide is for **platform builders** creating custom interfaces that display available integrations and actions to their end-users.
</Info>

Instead of hardcoding integration capabilities, query the `/actions` endpoint to dynamically determine what's available.

## List All Available Actions

Use `GET /actions` to retrieve action metadata:

<Tabs>
  <Tab title="TypeScript SDK">
    ```typescript theme={null}
    import { StackOne } from "@stackone/stackone-client-ts";

    const stackOne = new StackOne({
      security: {
        username: process.env.STACKONE_API_KEY!,
        password: "",
      },
    });

    const result = await stackOne.actions.listActionsMeta({});

    // Result contains providers with their available actions
    // result.actionsMetaPaginated?.data = [
    //   { key: "bamboohr", name: "BambooHR", actions: [...] },
    //   { key: "salesforce", name: "Salesforce", actions: [...] }
    // ]
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl "https://api.stackone.com/actions" \
      -u "$STACKONE_API_KEY:"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests
    import base64

    api_key = "v1.eu1.xxxxx"
    headers = {
        "Authorization": f"Basic {base64.b64encode(f'{api_key}:'.encode()).decode()}"
    }

    response = requests.get(
        "https://api.stackone.com/actions",
        headers=headers
    )

    providers = response.json()["data"]
    ```
  </Tab>
</Tabs>

***

## Filter Actions by Context

Filter by connector, account, or action key to get relevant actions for your UI:

<Tabs>
  <Tab title="TypeScript SDK">
    ```typescript theme={null}
    const result = await stackOne.actions.listActionsMeta({
      filter: {
        connectors: "bamboohr,workday",
        accountIds: "acct_abc123",
      },
    });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl "https://api.stackone.com/actions?filter[connectors]=bamboohr&filter[account_ids]=acct_abc123" \
      -u "$STACKONE_API_KEY:"
    ```
  </Tab>
</Tabs>

<Tip>
  See the [List Actions API Reference](/platform/api-reference/actions/list-all-actions-metadata) for all available filter parameters.
</Tip>

***

## Understanding Action Schema

The response is grouped by provider, with each provider containing its available actions:

```json theme={null}
{
  "data": [
    {
      "key": "sapsuccessfactors",
      "name": "SAP SuccessFactors",
      "description": "SAP SuccessFactors is a comprehensive cloud-based HCM solution...",
      "icon": "https://stackone-logos.com/api/sap-sucessfactors/filled/png",
      "version": "1.0.0",
      "categories": ["hris", "ats", "lms", "iam"],
      "authentication": [
        {
          "type": "custom",
          "label": "OAuth 2.0",
          "key": "custom"
        }
      ],
      "actions": [
        {
          "id": "sapsuccessfactors_list_employees",
          "label": "List Employees",
          "description": "Retrieve a list of all employees...",
          "schema_type": "native",
          "authentication": [...]
        },
        {
          "id": "sapsuccessfactors_get_employee",
          "label": "Get Employee",
          "description": "Retrieve detailed information about a specific employee"
        }
      ]
    }
  ],
  "next": "eyJyIjp7InAiOjI1fX0..."
}
```

### Provider Fields

| Field            | Description                                                    |
| ---------------- | -------------------------------------------------------------- |
| `key`            | Provider identifier (e.g., `sapsuccessfactors`, `workday`)     |
| `name`           | Display name for UI                                            |
| `description`    | Provider description                                           |
| `icon`           | URL to provider logo                                           |
| `version`        | Provider integration version                                   |
| `categories`     | Categories this provider supports (e.g., `hris`, `ats`, `lms`) |
| `authentication` | Supported authentication methods                               |
| `actions`        | List of available actions                                      |

### Action Fields

| Field               | Description                                               |
| ------------------- | --------------------------------------------------------- |
| `id`                | Action identifier for RPC calls                           |
| `label`             | Human-readable label for UI                               |
| `description`       | Action description                                        |
| `schema_type`       | Schema type (e.g., `native`)                              |
| `authentication`    | Authentication methods for this specific action           |
| `operation_details` | Detailed operation schema (when `include=action_details`) |

***

## Building a Dynamic Action UI

Here's how to build an interface that adapts to available actions:

<Tabs>
  <Tab title="TypeScript SDK">
    ```typescript theme={null}
    import { StackOne } from "@stackone/stackone-client-ts";

    const stackOne = new StackOne({
      security: {
        username: process.env.STACKONE_API_KEY!,
        password: "",
      },
    });

    async function getActionsForAccounts(accountIds: string[]) {
      const result = await stackOne.actions.listActionsMeta({
        filter: {
          accountIds: accountIds.join(","),
        },
      });

      return result.actionsMetaPaginated?.data ?? [];
    }

    // Flatten all actions across providers for display
    function getAllActions(providers: Awaited<ReturnType<typeof getActionsForAccounts>>) {
      return providers.flatMap(provider =>
        (provider.actions ?? []).map(action => ({
          ...action,
          providerKey: provider.key,
          providerName: provider.name,
        }))
      );
    }

    // Group actions by tag for UI sections
    function groupByTag(actions: ReturnType<typeof getAllActions>) {
      const grouped: Record<string, typeof actions> = {};
      for (const action of actions) {
        for (const tag of action.tags ?? []) {
          grouped[tag] = grouped[tag] || [];
          grouped[tag].push(action);
        }
      }
      return grouped;
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from collections import defaultdict
    import requests
    import base64
    import os

    def get_actions_for_accounts(account_ids: list[str]) -> list[dict]:
        api_key = os.environ["STACKONE_API_KEY"]
        headers = {
            "Authorization": f"Basic {base64.b64encode(f'{api_key}:'.encode()).decode()}"
        }

        response = requests.get(
            "https://api.stackone.com/actions",
            params={"filter[account_ids]": ",".join(account_ids)},
            headers=headers
        )
        return response.json()["data"]

    def get_all_actions(providers: list[dict]) -> list[dict]:
        """Flatten all actions across providers."""
        actions = []
        for provider in providers:
            for action in provider.get("actions", []):
                actions.append({
                    **action,
                    "provider_key": provider.get("key"),
                    "provider_name": provider.get("name"),
                })
        return actions

    def group_by_tag(actions: list[dict]) -> dict[str, list[dict]]:
        """Group actions by their tags."""
        grouped = defaultdict(list)
        for action in actions:
            for tag in action.get("tags", []):
                grouped[tag].append(action)
        return dict(grouped)
    ```
  </Tab>
</Tabs>

***

## Execute Actions via RPC

Once a user selects an action, execute it with the RPC endpoint:

<Tabs>
  <Tab title="TypeScript SDK">
    ```typescript theme={null}
    const result = await stackOne.actions.rpcAction({
      action: "bamboohr_list_employees",
      query: {
        pageSize: "25",
      },
      xAccountId: "customer-bamboohr",
    });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "https://api.stackone.com/actions/rpc" \
      -u "$STACKONE_API_KEY:" \
      -H "x-account-id: customer-bamboohr" \
      -H "Content-Type: application/json" \
      -d '{
        "action": "bamboohr_list_employees",
        "query": {
          "page_size": 25
        }
      }'
    ```
  </Tab>
</Tabs>

<Tip>
  The `action` field matches the `id` from the actions metadata.
</Tip>

***

## Real-World Example: Integration Dashboard

```typescript theme={null}
import { StackOne } from "@stackone/stackone-client-ts";

const stackOne = new StackOne({
  security: {
    username: process.env.STACKONE_API_KEY!,
    password: "",
  },
});

async function renderIntegrationDashboard(customerId: string) {
  // 1. Get customer's linked accounts
  const { linkedAccounts } = await stackOne.accounts.listLinkedAccounts({
    originOwnerId: customerId,
  });

  // 2. Get available actions for these accounts
  const accountIds = (linkedAccounts ?? []).map(a => a.id).filter(Boolean);
  const actionsResult = await stackOne.actions.listActionsMeta({
    filter: {
      accountIds: accountIds.join(","),
    },
  });

  const providers = actionsResult.actionsMetaPaginated?.data ?? [];

  // 3. Build dashboard data with actions grouped by tag
  return {
    accounts: linkedAccounts,
    providers: providers.map(provider => ({
      key: provider.key,
      name: provider.name,
      icon: provider.icon,
      actionsByTag: groupByTag(provider.actions ?? []),
      totalActions: provider.actions?.length ?? 0,
    })),
  };
}

function groupByTag(actions: { tags?: string[] }[]) {
  const grouped: Record<string, typeof actions> = {};
  for (const action of actions) {
    for (const tag of action.tags ?? []) {
      grouped[tag] = grouped[tag] || [];
      grouped[tag].push(action);
    }
  }
  return grouped;
}
```

***

## Related

<CardGroup>
  <Card title="Actions RPC" icon="bolt" href="/platform/api-reference/actions/make-an-rpc-call-to-an-action">
    Execute actions programmatically
  </Card>

  <Card title="List Actions API" icon="code" href="/platform/api-reference/actions/list-all-actions-metadata">
    Full API reference for actions metadata
  </Card>

  <Card title="Multi-Tenant Accounts" icon="users" href="/api/multi-tenant-accounts">
    Segment accounts by customer
  </Card>

  <Card title="Connector Metadata" icon="puzzle-piece" href="/platform/api-reference/connectors/list-connector-meta-information">
    Get connector logos and branding
  </Card>
</CardGroup>


# Authentication
Source: https://docs.stackone.com/api/authentication

Authenticate with StackOne APIs using API keys and Basic Auth

All StackOne APIs use **Basic Auth** with your API key as username and an empty password.

***

## Get Your API Key

1. Go to <a href="https://app.stackone.com/api_keys">**Configuration → API Keys**</a> in the dashboard
2. Click **Create API Key** and copy it securely

<Warning>
  API keys are shown only once. Store securely in a password manager or environment variable.
</Warning>

<Tip>
  For detailed steps with screenshots, see the [API Keys Guide](/guides/api-keys).
</Tip>

***

## Using Your API Key

All StackOne APIs use **Basic Auth** with your API key as username and empty password.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    # -u flag auto-encodes to base64
    curl -u "$STACKONE_API_KEY:" https://api.stackone.com/accounts
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const encoded = Buffer.from(`${apiKey}:`).toString('base64');
    fetch(url, { headers: { 'Authorization': `Basic ${encoded}` } });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import base64
    encoded = base64.b64encode(f"{api_key}:".encode()).decode()
    headers = {'Authorization': f'Basic {encoded}'}
    ```
  </Tab>
</Tabs>

<Tip>
  Get your API key from <a href="https://app.stackone.com/api_keys">**Configuration → API Keys**</a> in the dashboard.
</Tip>

***

## Account ID Header

For APIs that operate on a linked account, include the `x-account-id` header:

<Tabs>
  <Tab title="Get Account">
    ```bash theme={null}
    curl -u "$API_KEY:" \
      -H "x-account-id: your-account-id" \
      https://api.stackone.com/accounts/your-account-id
    ```
  </Tab>

  <Tab title="Execute Action">
    ```bash theme={null}
    curl -X POST -u "$API_KEY:" \
      -H "x-account-id: your-account-id" \
      -H "Content-Type: application/json" \
      https://api.stackone.com/actions/rpc \
      -d '{"action": "google_drive_list_files", "query": {}}'
    ```
  </Tab>
</Tabs>

<Note>
  Get account IDs from the [List Accounts](/platform/api-reference/accounts/list-accounts) endpoint or the <a href="https://app.stackone.com/accounts">**Accounts**</a> page in the dashboard.
</Note>

***

## API Key Scopes

| Scope           | Access                   |
| --------------- | ------------------------ |
| **Full Access** | All operations (default) |
| **Read Only**   | GET requests only        |
| **Accounts**    | Account management       |
| **Actions**     | Action execution via RPC |

<Info>
  Fine-grained scopes are an add-on feature. Contact your account manager for access.
</Info>

***

## Base URL

```
https://api.stackone.com
```

| API      | Pattern                                    |
| -------- | ------------------------------------------ |
| Platform | `/accounts`, `/actions/rpc`, `/connectors` |
| Unified  | `/unified/{category}/{resource}`           |
| MCP      | `/mcp`                                     |

***

## Error Responses

| Code  | Meaning                      |
| ----- | ---------------------------- |
| `401` | Invalid or missing API key   |
| `403` | API key lacks required scope |
| `404` | Invalid account ID           |
| `412` | Account suspended or expired |

<Tip>
  For all error codes including rate limits (429), timeouts (408), and provider errors (502), see the [Error Codes Guide](/guides/unified-api-error-codes-and-troubleshooting-guide).
</Tip>

***

## Next Steps

<CardGroup>
  <Card title="API Keys Guide" icon="key" href="/guides/api-keys">
    Create, scope, and manage API keys
  </Card>

  <Card title="Basic Auth Guide" icon="lock" href="/basic-authentication-with-stackone-api">
    Detailed encoding examples and SDK usage
  </Card>
</CardGroup>


# Execute Actions via RPC
Source: https://docs.stackone.com/api/execute-actions

Run any StackOne action programmatically using the unified RPC endpoint

The Actions RPC endpoint is the unified way to execute any of StackOne's 10,000+ actions. It's the same layer used by MCP servers and AI Toolset, giving you consistent programmatic access to all integrations.

<Info>
  This guide covers the **Platform API** approach to executing actions. For direct REST access to provider data, see the [Unified APIs](/guides/introduction).
</Info>

The RPC endpoint routes your request to the appropriate end-user's provider based on the `x-account-id` header, handles authentication, transforms requests to match provider APIs, and returns normalized data.

## Execute an Action

<Tabs>
  <Tab title="TypeScript SDK">
    ```typescript theme={null}
    import { StackOne } from "@stackone/stackone-client-ts";

    const stackOne = new StackOne({
      security: {
        username: process.env.STACKONE_API_KEY!,
        password: "",
      },
    });

    const result = await stackOne.actions.rpcAction({
      action: "bamboohr_list_employees",
      query: {
        pageSize: "25",
      },
      xAccountId: "customer-bamboohr",
    });

    // result.rpcActionResponse?.data = [{ id: "emp_123", ... }, ...]
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "https://api.stackone.com/actions/rpc" \
      -u "$STACKONE_API_KEY:" \
      -H "x-account-id: customer-bamboohr" \
      -H "Content-Type: application/json" \
      -d '{
        "action": "bamboohr_list_employees",
        "query": { "page_size": 25 }
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests
    import base64
    import os

    api_key = os.environ["STACKONE_API_KEY"]
    headers = {
        "Authorization": f"Basic {base64.b64encode(f'{api_key}:'.encode()).decode()}",
        "x-account-id": "customer-bamboohr",
        "Content-Type": "application/json"
    }

    response = requests.post(
        "https://api.stackone.com/actions/rpc",
        headers=headers,
        json={
            "action": "bamboohr_list_employees",
            "query": {"page_size": 25}
        }
    )

    employees = response.json()["data"]
    ```
  </Tab>
</Tabs>

***

## Request Parameters

| Parameter | Type   | Description                                                                            |
| --------- | ------ | -------------------------------------------------------------------------------------- |
| `action`  | string | The action identifier (e.g., `bamboohr_list_employees`, `greenhouse_create_candidate`) |
| `query`   | object | Query parameters for the action                                                        |
| `body`    | object | Request body for write operations                                                      |
| `path`    | object | Path parameters (e.g., `{ "id": "emp_123" }`)                                          |

### Headers

| Header          | Required | Description                                      |
| --------------- | -------- | ------------------------------------------------ |
| `x-account-id`  | Yes      | The linked account to execute the action against |
| `Authorization` | Yes      | Basic auth with your API key                     |

***

## Discover Available Actions

Use `GET /actions` to find what actions are available for a specific account or provider:

<Tabs>
  <Tab title="TypeScript SDK">
    ```typescript theme={null}
    const result = await stackOne.actions.listActionsMeta({
      filter: {
        connectors: "bamboohr",  // Filter by provider
      },
    });

    const actions = result.actionsMetaPaginated?.data?.[0]?.actions ?? [];

    // actions = [
    //   { id: "bamboohr_list_employees", label: "List Employees", ... },
    //   { id: "bamboohr_get_employee", label: "Get Employee", ... },
    //   ...
    // ]
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl "https://api.stackone.com/actions?filter[connectors]=bamboohr" \
      -u "$STACKONE_API_KEY:"
    ```
  </Tab>
</Tabs>

<Tip>
  Build dynamic agent tooling by querying available actions first, then executing them via RPC. See [Actions Metadata](/api/actions-metadata) for a complete guide.
</Tip>

***

## Common Action Patterns

### Workday: List Employees

```typescript theme={null}
const result = await stackOne.actions.rpcAction({
  action: "workday_list_employees",
  query: { pageSize: "50" },
  xAccountId: "customer-workday",
});
```

### Greenhouse: Create Candidate

```typescript theme={null}
const result = await stackOne.actions.rpcAction({
  action: "greenhouse_create_candidate",
  body: {
    first_name: "Jane",
    last_name: "Doe",
    email: "jane@example.com"
  },
  xAccountId: "customer-greenhouse",
});
```

### Salesforce: Get Contact

```typescript theme={null}
const result = await stackOne.actions.rpcAction({
  action: "salesforce_get_contact",
  path: { id: "contact_abc123" },
  xAccountId: "customer-salesforce",
});
```

***

## Related

<CardGroup>
  <Card title="Actions RPC API Reference" icon="code" href="/platform/api-reference/actions/make-an-rpc-call-to-an-action">
    Full API reference with all parameters
  </Card>

  <Card title="Actions Metadata" icon="list" href="/api/actions-metadata">
    Discover available actions and build dynamic UIs
  </Card>

  <Card title="Multi-Tenant Accounts" icon="users" href="/api/multi-tenant-accounts">
    Manage accounts by owner for multi-tenant apps
  </Card>

  <Card title="Request Logs" icon="scroll" href="/api/observability-sync">
    Monitor and debug action execution
  </Card>
</CardGroup>


# Multi-Tenant Account Management
Source: https://docs.stackone.com/api/multi-tenant-accounts

List and manage end-user accounts by owner for multi-tenant applications

When building on top of StackOne, you need to manage accounts across multiple owners. The `origin_owner_id` field is your key to segmenting accounts by owner.

<Info>
  This guide is for **platform builders** creating multi-tenant applications where each owner has their own set of linked accounts.
</Info>

When you onboard end-users through [Connect Sessions](/guides/embedding-stackone-hub), you provide an `origin_owner_id` that identifies the owner in your system. This ID lets you query accounts for specific owners.

## List Accounts by Owner

Use the `GET /accounts` endpoint with the `origin_owner_id` query parameter to filter accounts for a specific owner.

<Tabs>
  <Tab title="TypeScript SDK">
    ```typescript theme={null}
    import { StackOne } from "@stackone/stackone-client-ts";

    const stackOne = new StackOne({
      security: {
        username: process.env.STACKONE_API_KEY!,
        password: "",
      },
    });

    const { linkedAccounts } = await stackOne.accounts.listLinkedAccounts({
      originOwnerId: "owner_123",
    });

    // linkedAccounts = [
    //   { id: "acct_abc", provider: "bamboohr", status: "active", ... },
    //   { id: "acct_def", provider: "salesforce", status: "active", ... }
    // ]
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl "https://api.stackone.com/accounts?origin_owner_id=owner_123" \
      -u "$STACKONE_API_KEY:"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests
    import base64

    api_key = "v1.eu1.xxxxx"
    headers = {
        "Authorization": f"Basic {base64.b64encode(f'{api_key}:'.encode()).decode()}"
    }

    response = requests.get(
        "https://api.stackone.com/accounts",
        params={"origin_owner_id": "owner_123"},
        headers=headers
    )

    accounts = response.json()["data"]
    ```
  </Tab>
</Tabs>

### Response

```json theme={null}
{
  "data": [
    {
      "id": "acct_abc123",
      "origin_owner_id": "owner_123",
      "origin_owner_name": "Acme Corp",
      "provider": "bamboohr",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "acct_def456",
      "origin_owner_id": "owner_123",
      "origin_owner_name": "Acme Corp",
      "provider": "salesforce",
      "status": "active",
      "created_at": "2024-01-20T14:45:00Z"
    }
  ]
}
```

***

## Filter by Status and Provider

Combine filters to narrow down results:

```bash theme={null}
# Active accounts for an owner with a specific provider
curl "https://api.stackone.com/accounts?origin_owner_id=owner_123&provider=bamboohr&status=active" \
  -u "$STACKONE_API_KEY:"
```

### Available Filters

| Parameter         | Description                                                     |
| ----------------- | --------------------------------------------------------------- |
| `origin_owner_id` | The owner's unique identifier                                   |
| `provider`        | Filter by integration provider (e.g., `bamboohr`, `salesforce`) |
| `status`          | Filter by status: `active`, `inactive`, `error`                 |

***

## Building an Owner Dashboard

Here's how to build a dashboard showing each owner's integrations:

<Tabs>
  <Tab title="TypeScript SDK">
    ```typescript theme={null}
    import { StackOne } from "@stackone/stackone-client-ts";

    const stackOne = new StackOne({
      security: {
        username: process.env.STACKONE_API_KEY!,
        password: "",
      },
    });

    async function getOwnerIntegrations(ownerId: string) {
      const { linkedAccounts } = await stackOne.accounts.listLinkedAccounts({
        originOwnerId: ownerId,
      });
      return linkedAccounts ?? [];
    }

    // Group by provider for display
    function groupByProvider(accounts: typeof linkedAccounts) {
      const grouped: Record<string, typeof accounts> = {};
      for (const account of accounts ?? []) {
        const provider = account.provider ?? "unknown";
        grouped[provider] = grouped[provider] || [];
        grouped[provider].push(account);
      }
      return grouped;
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from collections import defaultdict
    import requests
    import base64
    import os

    def get_owner_integrations(owner_id: str) -> list[dict]:
        api_key = os.environ["STACKONE_API_KEY"]
        headers = {
            "Authorization": f"Basic {base64.b64encode(f'{api_key}:'.encode()).decode()}"
        }

        response = requests.get(
            "https://api.stackone.com/accounts",
            params={"origin_owner_id": owner_id},
            headers=headers
        )
        return response.json()["data"]

    def group_by_provider(accounts: list[dict]) -> dict[str, list[dict]]:
        grouped = defaultdict(list)
        for account in accounts:
            grouped[account.get("provider", "unknown")].append(account)
        return dict(grouped)
    ```
  </Tab>
</Tabs>

***

## Monitor Account Health

Track the health of your owners' integrations:

```typescript theme={null}
async function getAccountHealthSummary(ownerId: string) {
  const accounts = await getOwnerIntegrations(ownerId);

  return {
    total: accounts.length,
    active: accounts.filter(a => a.status === "active").length,
    needsAttention: accounts.filter(a =>
      ["error", "inactive"].includes(a.status ?? "")
    ).length,
    byProvider: accounts.reduce((acc, a) => {
      acc[a.provider ?? "unknown"] = a.status ?? "unknown";
      return acc;
    }, {} as Record<string, string>)
  };
}
```

***

## Webhooks for Account Changes

Subscribe to account lifecycle events to keep your system in sync:

| Event             | Description                   |
| ----------------- | ----------------------------- |
| `account.created` | New account linked            |
| `account.updated` | Account credentials refreshed |
| `account.deleted` | Account disconnected          |
| `account.error`   | Connection error occurred     |

<Card title="Webhooks Guide" icon="bell" href="/guides/webhooks">
  Configure webhooks to receive real-time account updates
</Card>

***

## Related

<CardGroup>
  <Card title="List Accounts API" icon="code" href="/platform/api-reference/accounts/list-accounts">
    Full API reference for listing accounts
  </Card>

  <Card title="Connect Sessions" icon="link" href="/platform/api-reference/connect-sessions/create-connect-session">
    Onboard end-users with origin\_owner\_id
  </Card>

  <Card title="Accounts Dashboard" icon="users" href="/guides/accounts-section">
    Manage accounts in the StackOne dashboard
  </Card>

  <Card title="Actions Metadata" icon="bolt" href="/api/actions-metadata">
    Build custom UIs with available actions
  </Card>
</CardGroup>


# Observability & Log Sync
Source: https://docs.stackone.com/api/observability-sync

Export request logs to Grafana, Datadog, or your internal monitoring systems

StackOne captures detailed logs for every API request. You can integrate these logs with your observability stack for centralized monitoring, alerting, and debugging.

<Info>
  This guide is for **platform builders** who want to integrate StackOne request logs with their existing monitoring infrastructure.
</Info>

***

## Integration Approaches

Choose the approach that fits your needs:

| Approach                              | Best For                                           | Complexity |
| ------------------------------------- | -------------------------------------------------- | ---------- |
| **Direct polling** (Grafana Infinity) | Simple dashboards, ad-hoc queries                  | Low        |
| **Push model** (Sync worker)          | High-volume, real-time alerts, data transformation | Medium     |
| **Webhooks**                          | Real-time alerts on specific events                | Low        |

StackOne retains logs for **90 days**.

***

## Query Request Logs

Use the Request Logs API to retrieve logs:

<Tabs>
  <Tab title="TypeScript SDK">
    ```typescript theme={null}
    import { StackOne } from "@stackone/stackone-client-ts";
    import {
      OrderBy,
      OrderDirection,
    } from "@stackone/stackone-client-ts/sdk/models/operations";

    const stackOne = new StackOne({
      security: {
        username: process.env.STACKONE_API_KEY!,
        password: "",
      },
    });

    const result = await stackOne.requestLogs.listLogs({
      pageSize: 100,
      orderBy: OrderBy.EventDatetime,
      orderDirection: OrderDirection.Desc,
    });

    const logs = result.unifiedLogsPaginated?.data ?? [];
    const nextCursor = result.unifiedLogsPaginated?.next;
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl "https://api.stackone.com/requests/logs?page_size=100&order_by=eventDatetime&order_direction=desc" \
      -u "$STACKONE_API_KEY:"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests
    import base64

    api_key = "v1.eu1.xxxxx"
    headers = {
        "Authorization": f"Basic {base64.b64encode(f'{api_key}:'.encode()).decode()}"
    }

    response = requests.get(
        "https://api.stackone.com/requests/logs",
        params={
            "page_size": 100,
            "order_by": "eventDatetime",
            "order_direction": "desc"
        },
        headers=headers
    )

    data = response.json()
    logs = data["data"]
    next_cursor = data.get("next")
    ```
  </Tab>
</Tabs>

### Log Entry Structure

```json theme={null}
{
  "requestId": "req_abc123",
  "accountId": "acct_xyz789",
  "provider": "bamboohr",
  "service": "hris",
  "action": "bamboohr_list_employees",
  "resource": "employees",
  "httpMethod": "POST",
  "path": "/actions/rpc",
  "url": "https://api.stackone.com/actions/rpc",
  "status": 200,
  "success": true,
  "duration": 245,
  "eventDatetime": "2024-01-15T10:30:00Z",
  "startTime": "2024-01-15T10:29:59Z",
  "endTime": "2024-01-15T10:30:00Z",
  "request": {
    "method": "POST",
    "url": {
      "hostname": "api.stackone.com",
      "path": "/actions/rpc"
    },
    "headers": {}
  },
  "response": {
    "statusCode": 200,
    "headers": {}
  }
}
```

### Key Fields for Monitoring

| Field       | Description                    | Use Case                     |
| ----------- | ------------------------------ | ---------------------------- |
| `status`    | HTTP response status           | Error rate alerts            |
| `success`   | Boolean success flag           | Quick filtering              |
| `duration`  | Request latency (ms)           | Performance monitoring       |
| `provider`  | Integration provider           | Provider-specific dashboards |
| `accountId` | Linked account                 | Customer-level debugging     |
| `action`    | Action executed                | Usage analytics              |
| `service`   | API category (hris, ats, etc.) | Service-level metrics        |

***

## Filter Logs

<Tabs>
  <Tab title="TypeScript SDK">
    ```typescript theme={null}
    // Filter by time range and status
    const result = await stackOne.requestLogs.listLogs({
      filter: {
        startDate: new Date("2024-01-15T09:00:00Z"),
        endDate: new Date("2024-01-15T17:00:00Z"),
        statusCodes: "400,401,500,502,503",  // Comma-separated
        providers: "bamboohr,workday",
        accountIds: "acct_xyz789",
      },
      pageSize: 100,
      orderBy: OrderBy.EventDatetime,
      orderDirection: OrderDirection.Desc,
    });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    # Filter by time range
    curl "https://api.stackone.com/requests/logs?filter[start_date]=2024-01-15T09:00:00Z&filter[end_date]=2024-01-15T17:00:00Z" \
      -u "$STACKONE_API_KEY:"

    # Filter by account
    curl "https://api.stackone.com/requests/logs?filter[account_ids]=acct_xyz789" \
      -u "$STACKONE_API_KEY:"

    # Filter by status codes (errors only)
    curl "https://api.stackone.com/requests/logs?filter[status_codes]=400,500,502,503" \
      -u "$STACKONE_API_KEY:"

    # Filter by provider
    curl "https://api.stackone.com/requests/logs?filter[providers]=bamboohr,workday" \
      -u "$STACKONE_API_KEY:"
    ```
  </Tab>
</Tabs>

<Tip>
  See the [List Logs API Reference](/platform/api-reference/request-logs/list-logs) for all available filter parameters including date ranges, account IDs, providers, status codes, and pagination options.
</Tip>

***

## Grafana Direct Polling

The simplest approach is to let Grafana poll the StackOne API directly using the [Infinity data source](https://grafana.com/grafana/plugins/yesoreyeram-infinity-datasource/).

### Setup

1. Install the Infinity plugin in Grafana
2. Add a new Infinity data source with these settings:

| Setting      | Value                                        |
| ------------ | -------------------------------------------- |
| **URL**      | `https://api.stackone.com`                   |
| **Auth**     | Basic Auth                                   |
| **User**     | Your StackOne API key (e.g., `v1.eu1.xxxxx`) |
| **Password** | Leave empty                                  |

### Example Query

Configure a panel with these Infinity settings:

```yaml theme={null}
Type: JSON
Source: URL
Method: GET
URL: /requests/logs?page_size=100&order_by=eventDatetime&order_direction=desc
Parser: Backend

# For filtering (optional)
URL: /requests/logs?filter[start_date]=${__from:date:iso}&filter[end_date]=${__to:date:iso}&filter[status_codes]=400,500,502,503
```

### Dashboard Variables

Create variables for dynamic filtering:

| Variable   | Query                                                    |
| ---------- | -------------------------------------------------------- |
| `provider` | Static values: `bamboohr`, `workday`, `greenhouse`, etc. |
| `account`  | Use `/accounts` endpoint to fetch linked accounts        |

Then use in queries: `/requests/logs?filter[providers]=${provider}&filter[account_ids]=${account}`

<Tip>
  This approach is best for dashboards and ad-hoc analysis. For real-time alerting or high-volume ingestion, use the sync worker approach below.
</Tip>

***

## Build a Log Sync Worker

For high-volume ingestion or when you need to transform logs before storing, build a sync worker that polls the StackOne API and forwards logs to your observability platform.

<Tip>
  Popular approaches include using [Temporal](https://temporal.io/) workflows, AWS Lambda with EventBridge schedules, or simple cron jobs. The core pattern is the same: poll for new logs since your last sync, then forward to your platform.
</Tip>

### Core Pattern

The essential StackOne integration is fetching logs with cursor-based pagination:

<Tabs>
  <Tab title="TypeScript SDK">
    ```typescript theme={null}
    import { StackOne } from "@stackone/stackone-client-ts";
    import { OrderBy, OrderDirection } from "@stackone/stackone-client-ts/sdk/models/operations";

    const stackOne = new StackOne({
      security: { username: process.env.STACKONE_API_KEY!, password: "" },
    });

    async function fetchLogsSince(startDate: Date) {
      const logs = [];
      let cursor: string | undefined;

      do {
        const result = await stackOne.requestLogs.listLogs({
          filter: { startDate },
          pageSize: 100,
          orderBy: OrderBy.EventDatetime,
          orderDirection: OrderDirection.Asc,
          next: cursor,
        });

        logs.push(...(result.unifiedLogsPaginated?.data ?? []));
        cursor = result.unifiedLogsPaginated?.next ?? undefined;
      } while (cursor);

      return logs;
    }

    // Usage: fetch logs from last sync, forward to your platform
    const logs = await fetchLogsSince(lastSyncTime);
    for (const log of logs) {
      await forwardToObservabilityPlatform(log); // Your implementation
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests
    import base64
    import os

    def fetch_logs_since(start_date: str) -> list[dict]:
        api_key = os.environ["STACKONE_API_KEY"]
        headers = {"Authorization": f"Basic {base64.b64encode(f'{api_key}:'.encode()).decode()}"}

        logs, cursor = [], None
        while True:
            params = {"filter[start_date]": start_date, "page_size": 100, "order_by": "eventDatetime", "order_direction": "asc"}
            if cursor:
                params["next"] = cursor

            data = requests.get("https://api.stackone.com/requests/logs", params=params, headers=headers).json()
            logs.extend(data["data"])
            cursor = data.get("next")
            if not cursor:
                break
        return logs

    # Usage: fetch logs from last sync, forward to your platform
    logs = fetch_logs_since(last_sync_time)
    for log in logs:
        forward_to_observability_platform(log)  # Your implementation
    ```
  </Tab>
</Tabs>

***

## Platform-Specific Examples

### Grafana Loki

```typescript theme={null}
async function sendToLoki(log: TransformedLog) {
  await fetch('http://loki:3100/loki/api/v1/push', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      streams: [{
        stream: log.labels,
        values: [[`${log.timestamp}000000`, JSON.stringify(log)]]
      }]
    })
  });
}
```

### Datadog

```typescript theme={null}
async function sendToDatadog(log: DatadogLog) {
  await fetch('https://http-intake.logs.datadoghq.com/api/v2/logs', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'DD-API-KEY': process.env.DATADOG_API_KEY!
    },
    body: JSON.stringify([log])
  });
}
```

### OpenTelemetry

```typescript theme={null}
import { logs } from '@opentelemetry/api-logs';

function sendToOtel(log: UnifiedLogs) {
  const logger = logs.getLogger('stackone');

  logger.emit({
    severityNumber: (log.status ?? 0) >= 400 ? 17 : 9, // ERROR : INFO
    body: `${log.httpMethod} ${log.path}`,
    attributes: {
      'http.status_code': log.status,
      'http.method': log.httpMethod,
      'stackone.provider': log.provider,
      'stackone.account_id': log.accountId,
      'stackone.action': log.action,
      'duration_ms': log.duration
    }
  });
}
```

***

## Suggested Dashboards

### Key Metrics to Track

| Metric          | Query Pattern                 | Alert Threshold           |
| --------------- | ----------------------------- | ------------------------- |
| Error Rate      | `status >= 400`               | > 5% over 5 min           |
| P95 Latency     | `percentile(duration, 95)`    | > 2000ms                  |
| Provider Health | Group by `provider`, `status` | Any provider > 10% errors |
| Request Volume  | Count by time bucket          | Anomaly detection         |

### Grafana Dashboard JSON

```json theme={null}
{
  "panels": [
    {
      "title": "Error Rate by Provider",
      "type": "timeseries",
      "targets": [{
        "expr": "sum(rate(stackone_requests_total{status_code=~\"4..|5..\"}[5m])) by (provider) / sum(rate(stackone_requests_total[5m])) by (provider)"
      }]
    },
    {
      "title": "P95 Latency",
      "type": "stat",
      "targets": [{
        "expr": "histogram_quantile(0.95, sum(rate(stackone_request_duration_bucket[5m])) by (le))"
      }]
    }
  ]
}
```

***

## Webhooks for Real-Time Alerts

For critical events, use webhooks instead of polling:

| Event             | Use Case                         |
| ----------------- | -------------------------------- |
| `account.error`   | Alert on integration failures    |
| `account.expired` | Notify about expired credentials |
| `request.failed`  | Real-time error alerts           |

<Card title="Webhooks Guide" icon="bell" href="/guides/webhooks">
  Configure webhooks for real-time notifications
</Card>

***

## Related

<CardGroup>
  <Card title="Request Logs API" icon="code" href="/platform/api-reference/request-logs/list-logs">
    Full API reference for logs
  </Card>

  <Card title="Dashboard Logs" icon="scroll" href="/guides/request-logs">
    View logs in the StackOne dashboard
  </Card>

  <Card title="Webhooks" icon="bell" href="/guides/webhooks">
    Real-time event notifications
  </Card>

  <Card title="Error Codes" icon="triangle-exclamation" href="/guides/unified-api-error-codes-and-troubleshooting-guide">
    Understanding error responses
  </Card>
</CardGroup>


# Platform API Overview
Source: https://docs.stackone.com/api/platform-overview

Manage accounts, execute actions, and control integrations with the Platform API

The Platform API is the **control plane** for StackOne. It powers MCP servers and AI Toolset. Use it to execute actions, manage end-user accounts, and build custom integrations.

<CardGroup>
  <Card title="Execute Actions" icon="bolt" href="#execute-actions">
    Run any of 10,000+ actions via RPC
  </Card>

  <Card title="Manage Accounts" icon="users" href="#manage-accounts">
    CRUD operations on linked accounts
  </Card>

  <Card title="Onboard End-Users" icon="link" href="#onboard-end-users">
    Generate connect session URLs
  </Card>
</CardGroup>

***

## Execute Actions

The RPC endpoint is the unified way to execute any of StackOne's 10,000+ actions, the same layer used by MCP and AI Toolset.

<Card title="Execute Actions Guide" icon="bolt" href="/api/execute-actions">
  Learn how to execute actions via RPC, discover available actions, and build dynamic agent tooling.
</Card>

<div>
  <CardGroup>
    <Card title="Actions RPC" icon="play" href="/platform/api-reference/actions/make-an-rpc-call-to-an-action">
      **`POST /actions/rpc`**: Execute any StackOne action.
    </Card>

    <Card title="List Actions" icon="list" href="/platform/api-reference/actions/list-all-actions-metadata">
      **`GET /actions`**: Discover available actions and parameters.
    </Card>
  </CardGroup>
</div>

***

## Manage Accounts

Linked accounts are your end-users' connections to their SaaS systems. The Accounts API manages the full lifecycle.

<CardGroup>
  <Card title="List Accounts" icon="list-ul" href="/platform/api-reference/accounts/list-accounts">
    **`GET /accounts`**: Get all linked accounts with status, provider, and metadata.
  </Card>

  <Card title="Get Account" icon="magnifying-glass" href="/platform/api-reference/accounts/get-account">
    **`GET /accounts/{id}`**: Get details for a specific account.
  </Card>

  <Card title="Update Account" icon="pen" href="/platform/api-reference/accounts/update-account">
    **`PATCH /accounts/{id}`**: Update labels, metadata, or configuration.
  </Card>

  <Card title="Delete Account" icon="trash" href="/platform/api-reference/accounts/delete-account">
    **`DELETE /accounts/{id}`**: Remove an account and its stored credentials.
  </Card>
</CardGroup>

***

## Onboard End-Users

The Connect Sessions API powers the [Integration Hub](/guides/embedding-stackone-hub), the embeddable UI where end-users link accounts.

<CardGroup>
  <Card title="Create Session" icon="plus" href="/platform/api-reference/connect-sessions/create-connect-session">
    **`POST /connect_sessions`**: Generate a connect URL for your app.
  </Card>

  <Card title="Authenticate Session" icon="key" href="/platform/api-reference/connect-sessions/authenticate-connect-session">
    **`POST /connect_sessions/authenticate`**: Authenticate a session programmatically.
  </Card>
</CardGroup>

### Typical Flow

```mermaid theme={null}
sequenceDiagram
    participant App as Your App
    participant API as Platform API
    participant Hub as Integration Hub
    participant User as End-User

    App->>API: POST /connect_sessions
    API-->>App: { connect_url, token }
    App->>User: Redirect to connect_url
    User->>Hub: Selects provider & authenticates
    Hub->>API: Creates linked account
    API-->>App: Webhook: account.created
```

***

## Discover Connectors

Query metadata about available connectors. Useful for building UIs that show which integrations you support.

<CardGroup>
  <Card title="List Connectors" icon="grid-2" href="/platform/api-reference/connectors/list-connector-meta-information">
    **`GET /connectors`**: Get all connectors with categories, logos, and capabilities.
  </Card>

  <Card title="Get Connector" icon="puzzle-piece" href="/platform/api-reference/connectors/get-connector-meta-information">
    **`GET /connectors/{provider}`**: Get a connector's fields and actions.
  </Card>
</CardGroup>

***

## Monitor & Debug

Access detailed logs for every API request. Essential for debugging integrations in production.

<CardGroup>
  <Card title="List Logs" icon="scroll" href="/platform/api-reference/request-logs/list-logs">
    **`GET /logs`**: Query logs with filters for account, status, and time.
  </Card>

  <Card title="Get Log Details" icon="magnifying-glass-plus" href="/platform/api-reference/request-logs/get-log">
    **`GET /logs/{id}`**: Get full request/response details for a log entry.
  </Card>

  <Card title="Step-by-Step Execution" icon="stairs" href="/platform/api-reference/request-logs/list-step-logs">
    **`GET /logs/{id}/steps`**: See execution steps (auth, transformation, provider calls).
  </Card>

  <Card title="Platform Logs" icon="server" href="/platform/api-reference/request-logs/list-platform-logs">
    **`GET /logs/platform`**: Logs for sessions, webhooks, and other platform operations.
  </Card>
</CardGroup>

***

## MCP Endpoint

The MCP (Model Context Protocol) endpoint enables direct integration with Claude, Cursor, n8n, and other MCP-compatible clients. Most users connect via our hosted MCP server, but you can also build custom MCP integrations.

<CardGroup>
  <Card title="Send Message" icon={<svg fill="currentColor" fillRule="evenodd" height="1em" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><path d="M15.688 2.343a2.588 2.588 0 00-3.61 0l-9.626 9.44a.863.863 0 01-1.203 0 .823.823 0 010-1.18l9.626-9.44a4.313 4.313 0 016.016 0 4.116 4.116 0 011.204 3.54 4.3 4.3 0 013.609 1.18l.05.05a4.115 4.115 0 010 5.9l-8.706 8.537a.274.274 0 000 .393l1.788 1.754a.823.823 0 010 1.18.863.863 0 01-1.203 0l-1.788-1.753a1.92 1.92 0 010-2.754l8.706-8.538a2.47 2.47 0 000-3.54l-.05-.049a2.588 2.588 0 00-3.607-.003l-7.172 7.034-.002.002-.098.097a.863.863 0 01-1.204 0 .823.823 0 010-1.18l7.273-7.133a2.47 2.47 0 00-.003-3.537z"></path><path d="M14.485 4.703a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a4.115 4.115 0 000 5.9 4.314 4.314 0 006.016 0l7.12-6.982a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a2.588 2.588 0 01-3.61 0 2.47 2.47 0 010-3.54l7.12-6.982z"></path></svg>} href="/platform/api-reference/mcp/send-mcp-json-rpc-message">
    **`POST /mcp`**
  </Card>

  <Card title="SSE Stream" icon={<svg fill="currentColor" fillRule="evenodd" height="1em" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><path d="M15.688 2.343a2.588 2.588 0 00-3.61 0l-9.626 9.44a.863.863 0 01-1.203 0 .823.823 0 010-1.18l9.626-9.44a4.313 4.313 0 016.016 0 4.116 4.116 0 011.204 3.54 4.3 4.3 0 013.609 1.18l.05.05a4.115 4.115 0 010 5.9l-8.706 8.537a.274.274 0 000 .393l1.788 1.754a.823.823 0 010 1.18.863.863 0 01-1.203 0l-1.788-1.753a1.92 1.92 0 010-2.754l8.706-8.538a2.47 2.47 0 000-3.54l-.05-.049a2.588 2.588 0 00-3.607-.003l-7.172 7.034-.002.002-.098.097a.863.863 0 01-1.204 0 .823.823 0 010-1.18l7.273-7.133a2.47 2.47 0 00-.003-3.537z"></path><path d="M14.485 4.703a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a4.115 4.115 0 000 5.9 4.314 4.314 0 006.016 0l7.12-6.982a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a2.588 2.588 0 01-3.61 0 2.47 2.47 0 010-3.54l7.12-6.982z"></path></svg>} href="/platform/api-reference/mcp/open-mcp-sse-stream">
    **`GET /mcp/sse`**
  </Card>

  <Card title="End Session" icon={<svg fill="currentColor" fillRule="evenodd" height="1em" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><path d="M15.688 2.343a2.588 2.588 0 00-3.61 0l-9.626 9.44a.863.863 0 01-1.203 0 .823.823 0 010-1.18l9.626-9.44a4.313 4.313 0 016.016 0 4.116 4.116 0 011.204 3.54 4.3 4.3 0 013.609 1.18l.05.05a4.115 4.115 0 010 5.9l-8.706 8.537a.274.274 0 000 .393l1.788 1.754a.823.823 0 010 1.18.863.863 0 01-1.203 0l-1.788-1.753a1.92 1.92 0 010-2.754l8.706-8.538a2.47 2.47 0 000-3.54l-.05-.049a2.588 2.588 0 00-3.607-.003l-7.172 7.034-.002.002-.098.097a.863.863 0 01-1.204 0 .823.823 0 010-1.18l7.273-7.133a2.47 2.47 0 00-.003-3.537z"></path><path d="M14.485 4.703a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a4.115 4.115 0 000 5.9 4.314 4.314 0 006.016 0l7.12-6.982a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a2.588 2.588 0 01-3.61 0 2.47 2.47 0 010-3.54l7.12-6.982z"></path></svg>} href="/platform/api-reference/mcp/delete-mcp-session">
    **`DELETE /mcp/session`**
  </Card>
</CardGroup>

<Info>
  For most use cases, use our [hosted MCP server](/mcp/quickstart) at `https://api.stackone.com/mcp` instead of building a custom integration.
</Info>

***

## Proxy Requests

Bypass the unified layer and make raw requests directly to provider APIs. Useful when you need provider-specific functionality not covered by StackOne actions.

<Card title="Proxy Request" icon="arrows-left-right" href="/platform/api-reference/proxy/proxy-request">
  **`POST /proxy`**: Forward requests to the provider API. StackOne handles authentication.
</Card>

```bash theme={null}
curl -X POST "https://api.stackone.com/proxy" \
  -u "$STACKONE_API_KEY:" \
  -H "x-account-id: customer-bamboohr" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "path": "/api/gateway.php/mycompany/v1/reports/custom"
  }'
```

<Warning>
  Proxy requests bypass StackOne's unified data model. Use them sparingly for edge cases not covered by standard actions.
</Warning>

***

## Platform API vs Unified APIs

| I want to...                           | Use                                             |
| -------------------------------------- | ----------------------------------------------- |
| Execute actions from my agent/backend  | **Platform API** → `POST /actions/rpc`          |
| List all my end-users' linked accounts | **Platform API** → `GET /accounts`              |
| Generate an onboarding link            | **Platform API** → `POST /connect_sessions`     |
| List employees from BambooHR           | **Unified API** → `GET /unified/hris/employees` |
| Create a job posting in Greenhouse     | **Unified API** → `POST /unified/ats/jobs`      |
| Query CRM contacts                     | **Unified API** → `GET /unified/crm/contacts`   |

<Tip>
  **Rule of thumb:** Use the **Platform API** for managing StackOne itself (accounts, sessions, actions). Use **Unified APIs** when you want direct REST access to provider data with a standardized schema.
</Tip>

***

## Get Started

<CardGroup>
  <Card title="Authentication" icon="key" href="/api/authentication">
    Set up your API key and learn the auth format
  </Card>

  <Card title="Try Actions RPC" icon="bolt" href="/platform/api-reference/actions/make-an-rpc-call-to-an-action">
    Execute your first action
  </Card>

  <Card title="Explore in Playground" icon="flask" href="https://app.stackone.com/playground">
    Test actions with natural language
  </Card>

  <Card title="View All Endpoints" icon="book" href="/platform/api-reference/accounts/list-accounts">
    Browse the full API reference
  </Card>
</CardGroup>


# 360Learning
Source: https://docs.stackone.com/connectors/360learning/index

78 actions available for 360Learning through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# 7shifts
Source: https://docs.stackone.com/connectors/7shifts/index

59 actions available for 7shifts through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# X (Twitter)
Source: https://docs.stackone.com/connectors/X/index

55 actions available for X (Twitter) through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# absence.io
Source: https://docs.stackone.com/connectors/absenceio/index

24 actions available for absence.io through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# ActiveCampaign
Source: https://docs.stackone.com/connectors/activecampaign/index

23 actions available for ActiveCampaign through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Add New Connector or Action
Source: https://docs.stackone.com/connectors/add-new

Request a new connector or build your own with StackOne

## Two Ways to Add Connectors

<Card title="Request a New Connector or Action" icon="hand" href="https://www.stackone.com/demo">
  <Frame>
    <img alt="StackOne connector build process: API docs → Automated QA → AI optimization → Manual QA → Your connector" />
  </Frame>

  Our team builds and maintains the connector for you. Delivery depends on StackOne's internal roadmap priorities unless you're on a plan with connector build SLAs.

  * **Fast turnaround:** typically days, not weeks (when API access is provided)
  * **Full support:** we handle API mapping, auth, and testing
  * **QA pipeline:** automated tests, AI-driven optimization, and manual verification
  * **Fork & customize:** optionally fork and edit actions after delivery
</Card>

<Card title="Build Your Own" icon="hammer" href="/guides/connector-engine/introduction">
  <Frame>
    <img alt="AI-assisted connector development workflow" />
  </Frame>

  Use Connector Engine to build custom connectors with full CI/CD control.

  * **AI-assisted:** Claude Code generates YAML from API docs
  * **Full control:** version, test, and deploy on your schedule
  * **Your environments:** integrate with your existing CI/CD
</Card>


# Adobe Learning Manager
Source: https://docs.stackone.com/connectors/adobelearningmanager/index

72 actions available for Adobe Learning Manager through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Adobe PDF Services
Source: https://docs.stackone.com/connectors/adobepdfservices/index

41 actions available for Adobe PDF Services through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# ADP Workforce Now
Source: https://docs.stackone.com/connectors/adpworkforcenow/index

50 actions available for ADP Workforce Now through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Affinity
Source: https://docs.stackone.com/connectors/affinity/index

34 actions available for Affinity through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Aha!
Source: https://docs.stackone.com/connectors/aha/index

91 actions available for Aha! through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Aircall
Source: https://docs.stackone.com/connectors/aircall/index

70 actions available for Aircall through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Airship
Source: https://docs.stackone.com/connectors/airship/index

38 actions available for Airship through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Airtable
Source: https://docs.stackone.com/connectors/airtable/index

24 actions available for Airtable through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Algolia
Source: https://docs.stackone.com/connectors/algolia/index

42 actions available for Algolia through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Amplemarket
Source: https://docs.stackone.com/connectors/amplemarket/index

43 actions available for Amplemarket through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Amplitude
Source: https://docs.stackone.com/connectors/amplitude/index

53 actions available for Amplitude through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Anthropic
Source: https://docs.stackone.com/connectors/anthropic/index

29 actions available for Anthropic through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Apollo
Source: https://docs.stackone.com/connectors/apollo/index

45 actions available for Apollo through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# ApprovalMax
Source: https://docs.stackone.com/connectors/approvalmax/index

64 actions available for ApprovalMax through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Asana
Source: https://docs.stackone.com/connectors/asana/index

126 actions available for Asana through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Ashby
Source: https://docs.stackone.com/connectors/ashby/index

137 actions available for Ashby through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Attentive
Source: https://docs.stackone.com/connectors/attentive/index

19 actions available for Attentive through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Attio
Source: https://docs.stackone.com/connectors/attio/index

58 actions available for Attio through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Auth0
Source: https://docs.stackone.com/connectors/auth0/index

78 actions available for Auth0 through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Autodesk
Source: https://docs.stackone.com/connectors/autodesk/index

51 actions available for Autodesk through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Amazon S3
Source: https://docs.stackone.com/connectors/awss3/index

89 actions available for Amazon S3 through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Azure Blob Storage
Source: https://docs.stackone.com/connectors/azureblobstorage/index

26 actions available for Azure Blob Storage through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Azure DevOps
Source: https://docs.stackone.com/connectors/azuredevops/index

185 actions available for Azure DevOps through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# BambooHR
Source: https://docs.stackone.com/connectors/bamboohr/index

100 actions available for BambooHR through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Basecamp
Source: https://docs.stackone.com/connectors/basecamp/index

118 actions available for Basecamp through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# BigChange
Source: https://docs.stackone.com/connectors/bigchange/index

98 actions available for BigChange through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# BigCommerce
Source: https://docs.stackone.com/connectors/bigcommerce/index

120 actions available for BigCommerce through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Bitbucket
Source: https://docs.stackone.com/connectors/bitbucket/index

133 actions available for Bitbucket through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Bitly
Source: https://docs.stackone.com/connectors/bitly/index

85 actions available for Bitly through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Box
Source: https://docs.stackone.com/connectors/box/index

92 actions available for Box through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Brainier
Source: https://docs.stackone.com/connectors/brainier/index

47 actions available for Brainier through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Braze
Source: https://docs.stackone.com/connectors/braze/index

98 actions available for Braze through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# BreatheHR
Source: https://docs.stackone.com/connectors/breathehr/index

42 actions available for BreatheHR through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# BreezyHR
Source: https://docs.stackone.com/connectors/breezyhr/index

47 actions available for BreezyHR through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Browserbase
Source: https://docs.stackone.com/connectors/browserbase/index

19 actions available for Browserbase through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Bullhorn
Source: https://docs.stackone.com/connectors/bullhorn/index

47 actions available for Bullhorn through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Cal.com
Source: https://docs.stackone.com/connectors/calcom/index

52 actions available for Cal.com through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Calendly
Source: https://docs.stackone.com/connectors/calendly/index

38 actions available for Calendly through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Campaign Monitor
Source: https://docs.stackone.com/connectors/campaignmonitor/index

73 actions available for Campaign Monitor through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Canva
Source: https://docs.stackone.com/connectors/canva/index

21 actions available for Canva through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Capsule CRM
Source: https://docs.stackone.com/connectors/capsulecrm/index

127 actions available for Capsule CRM through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Cascade HR
Source: https://docs.stackone.com/connectors/cascadehr/index

48 actions available for Cascade HR through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# CezanneHR
Source: https://docs.stackone.com/connectors/cezannehr/index

47 actions available for CezanneHR through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Chargebee
Source: https://docs.stackone.com/connectors/chargebee/index

60 actions available for Chargebee through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Chargify (Maxio)
Source: https://docs.stackone.com/connectors/chargify/index

125 actions available for Chargify (Maxio) through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# CharlieHR
Source: https://docs.stackone.com/connectors/charliehr/index

22 actions available for CharlieHR through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# CircleCI
Source: https://docs.stackone.com/connectors/circleci/index

82 actions available for CircleCI through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# ClickUp
Source: https://docs.stackone.com/connectors/clickup/index

95 actions available for ClickUp through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Clockify
Source: https://docs.stackone.com/connectors/clockify/index

105 actions available for Clockify through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Close
Source: https://docs.stackone.com/connectors/close/index

81 actions available for Close through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Cloudflare
Source: https://docs.stackone.com/connectors/cloudflare/index

141 actions available for Cloudflare through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Cohere
Source: https://docs.stackone.com/connectors/cohere/index

14 actions available for Cohere through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Confluence
Source: https://docs.stackone.com/connectors/confluence/index

133 actions available for Confluence through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Constant Contact
Source: https://docs.stackone.com/connectors/constantcontact/index

78 actions available for Constant Contact through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Contentful
Source: https://docs.stackone.com/connectors/contentful/index

54 actions available for Contentful through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Cornerstone
Source: https://docs.stackone.com/connectors/cornerstone/index

21 actions available for Cornerstone through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Coursera
Source: https://docs.stackone.com/connectors/coursera/index

16 actions available for Coursera through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Customer.io
Source: https://docs.stackone.com/connectors/customerio/index

48 actions available for Customer.io through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Dagster
Source: https://docs.stackone.com/connectors/dagster/index

52 actions available for Dagster through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Databricks
Source: https://docs.stackone.com/connectors/databricks/index

72 actions available for Databricks through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Databricks Workspace
Source: https://docs.stackone.com/connectors/databricksworkspace/index

36 actions available for Databricks Workspace through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Datadog
Source: https://docs.stackone.com/connectors/datadog/index

26 actions available for Datadog through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Deel
Source: https://docs.stackone.com/connectors/deel/index

60 actions available for Deel through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Demio
Source: https://docs.stackone.com/connectors/demio/index

6 actions available for Demio through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Deputy
Source: https://docs.stackone.com/connectors/deputy/index

49 actions available for Deputy through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Discord
Source: https://docs.stackone.com/connectors/discord/index

145 actions available for Discord through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Discourse
Source: https://docs.stackone.com/connectors/discourse/index

67 actions available for Discourse through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Dixa
Source: https://docs.stackone.com/connectors/dixa/index

65 actions available for Dixa through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Docebo
Source: https://docs.stackone.com/connectors/docebo/index

56 actions available for Docebo through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# DocuSign
Source: https://docs.stackone.com/connectors/docusign/index

63 actions available for DocuSign through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Domo
Source: https://docs.stackone.com/connectors/domo/index

23 actions available for Domo through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Drata
Source: https://docs.stackone.com/connectors/drata/index

57 actions available for Drata through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Dropbox
Source: https://docs.stackone.com/connectors/dropbox/index

90 actions available for Dropbox through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Dropbox Sign
Source: https://docs.stackone.com/connectors/dropboxsign/index

69 actions available for Dropbox Sign through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Microsoft Dynamics 365 Business Central
Source: https://docs.stackone.com/connectors/dynamics365bc/index

70 actions available for Microsoft Dynamics 365 Business Central through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# EasyLlama
Source: https://docs.stackone.com/connectors/easyllama/index

27 actions available for EasyLlama through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Easyship
Source: https://docs.stackone.com/connectors/easyship/index

48 actions available for Easyship through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Elastic Cloud
Source: https://docs.stackone.com/connectors/elasticcloud/index

50 actions available for Elastic Cloud through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Employment Hero
Source: https://docs.stackone.com/connectors/employmenthero/index

51 actions available for Employment Hero through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Envoy
Source: https://docs.stackone.com/connectors/envoy/index

42 actions available for Envoy through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Eploy
Source: https://docs.stackone.com/connectors/eploy/index

92 actions available for Eploy through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Eventbrite
Source: https://docs.stackone.com/connectors/eventbrite/index

83 actions available for Eventbrite through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Expensify
Source: https://docs.stackone.com/connectors/expensify/index

17 actions available for Expensify through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Factorial
Source: https://docs.stackone.com/connectors/factorialhr/index

127 actions available for Factorial through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Fastbill
Source: https://docs.stackone.com/connectors/fastbill/index

57 actions available for Fastbill through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# FastSpring
Source: https://docs.stackone.com/connectors/fastspring/index

59 actions available for FastSpring through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Fathom
Source: https://docs.stackone.com/connectors/fathom/index

7 actions available for Fathom through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Figma
Source: https://docs.stackone.com/connectors/figma/index

44 actions available for Figma through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Firebase
Source: https://docs.stackone.com/connectors/firebase/index

36 actions available for Firebase through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Fireflies.ai
Source: https://docs.stackone.com/connectors/fireflies/index

16 actions available for Fireflies.ai through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Fivetran
Source: https://docs.stackone.com/connectors/fivetran/index

144 actions available for Fivetran through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Fourth
Source: https://docs.stackone.com/connectors/fourth/index

30 actions available for Fourth through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# FreeAgent
Source: https://docs.stackone.com/connectors/freeagent/index

105 actions available for FreeAgent through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# FreshBooks
Source: https://docs.stackone.com/connectors/freshbooks/index

82 actions available for FreshBooks through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Freshdesk
Source: https://docs.stackone.com/connectors/freshdesk/index

73 actions available for Freshdesk through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Freshsales
Source: https://docs.stackone.com/connectors/freshsales/index

120 actions available for Freshsales through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Freshservice
Source: https://docs.stackone.com/connectors/freshservice/index

84 actions available for Freshservice through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Front
Source: https://docs.stackone.com/connectors/front/index

53 actions available for Front through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# GitBook
Source: https://docs.stackone.com/connectors/gitbook/index

48 actions available for GitBook through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# GitHub
Source: https://docs.stackone.com/connectors/github/index

100 actions available for GitHub through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# GitLab
Source: https://docs.stackone.com/connectors/gitlab/index

125 actions available for GitLab through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Globalization Partners
Source: https://docs.stackone.com/connectors/globalizationpartners/index

23 actions available for Globalization Partners through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Gmail
Source: https://docs.stackone.com/connectors/gmail/index

42 actions available for Gmail through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Go1
Source: https://docs.stackone.com/connectors/go1/index

69 actions available for Go1 through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# GoCardless
Source: https://docs.stackone.com/connectors/gocardless/index

66 actions available for GoCardless through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Gong
Source: https://docs.stackone.com/connectors/gong/index

41 actions available for Gong through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Google Analytics
Source: https://docs.stackone.com/connectors/googleanalytics/index

33 actions available for Google Analytics through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Google BigQuery
Source: https://docs.stackone.com/connectors/googlebigquery/index

41 actions available for Google BigQuery through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Google Calendar
Source: https://docs.stackone.com/connectors/googlecalendar/index

37 actions available for Google Calendar through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Google Chat
Source: https://docs.stackone.com/connectors/googlechat/index

32 actions available for Google Chat through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Google Cloud Compute
Source: https://docs.stackone.com/connectors/googlecloudcompute/index

40 actions available for Google Cloud Compute through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Google Cloud Data
Source: https://docs.stackone.com/connectors/googleclouddata/index

43 actions available for Google Cloud Data through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Google Cloud Observability
Source: https://docs.stackone.com/connectors/googlecloudobservability/index

45 actions available for Google Cloud Observability through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Google Cloud Security
Source: https://docs.stackone.com/connectors/googlecloudsecurity/index

56 actions available for Google Cloud Security through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Google Cloud Storage
Source: https://docs.stackone.com/connectors/googlecloudstorage/index

30 actions available for Google Cloud Storage through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Google Contacts
Source: https://docs.stackone.com/connectors/googlecontacts/index

21 actions available for Google Contacts through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Google Docs
Source: https://docs.stackone.com/connectors/googledocs/index

4 actions available for Google Docs through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Google Drive
Source: https://docs.stackone.com/connectors/googledrive/index

64 actions available for Google Drive through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Google Forms
Source: https://docs.stackone.com/connectors/googleforms/index

6 actions available for Google Forms through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Google Gemini
Source: https://docs.stackone.com/connectors/googlegemini/index

30 actions available for Google Gemini through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Google Meet
Source: https://docs.stackone.com/connectors/googlemeet/index

18 actions available for Google Meet through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Google Search Console
Source: https://docs.stackone.com/connectors/googlesearchconsole/index

10 actions available for Google Search Console through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Google Sheets
Source: https://docs.stackone.com/connectors/googlesheets/index

16 actions available for Google Sheets through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Google Shopping
Source: https://docs.stackone.com/connectors/googleshopping/index

82 actions available for Google Shopping through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Google Slides
Source: https://docs.stackone.com/connectors/googleslides/index

47 actions available for Google Slides through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Google Tasks
Source: https://docs.stackone.com/connectors/googletasks/index

12 actions available for Google Tasks through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Gorgias
Source: https://docs.stackone.com/connectors/gorgias/index

69 actions available for Gorgias through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# GoTo Webinar
Source: https://docs.stackone.com/connectors/goto/index

52 actions available for GoTo Webinar through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Grafana
Source: https://docs.stackone.com/connectors/grafana/index

89 actions available for Grafana through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Greenhouse - Harvest v3
Source: https://docs.stackone.com/connectors/greenhouse/index

99 actions available for Greenhouse - Harvest v3 through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Gusto
Source: https://docs.stackone.com/connectors/gusto/index

72 actions available for Gusto through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Harness
Source: https://docs.stackone.com/connectors/harness/index

69 actions available for Harness through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Harvest
Source: https://docs.stackone.com/connectors/harvest/index

78 actions available for Harvest through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Heap
Source: https://docs.stackone.com/connectors/heap/index

6 actions available for Heap through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Help Scout
Source: https://docs.stackone.com/connectors/helpscout/index

36 actions available for Help Scout through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# HiBob
Source: https://docs.stackone.com/connectors/hibob/index

123 actions available for HiBob through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Hive
Source: https://docs.stackone.com/connectors/hive/index

20 actions available for Hive through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Honeycomb
Source: https://docs.stackone.com/connectors/honeycomb/index

79 actions available for Honeycomb through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Hootsuite
Source: https://docs.stackone.com/connectors/hootsuite/index

45 actions available for Hootsuite through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# HubSpot
Source: https://docs.stackone.com/connectors/hubspot/index

98 actions available for HubSpot through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Humaans
Source: https://docs.stackone.com/connectors/humaans/index

117 actions available for Humaans through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# InfoSec
Source: https://docs.stackone.com/connectors/infosec/index

34 actions available for InfoSec through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Instagram
Source: https://docs.stackone.com/connectors/instagram/index

52 actions available for Instagram through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Intercom
Source: https://docs.stackone.com/connectors/intercom/index

113 actions available for Intercom through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Connectors
Source: https://docs.stackone.com/connectors/introduction

Explore 400 connectors and 21000 actions available through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

Choose a connector below to see available actions, or expand the sections below for integration options.

<AccordionGroup>
  <Accordion title="How to Use Actions">
    Choose the integration method that fits your architecture:

    * **[MCP Server](/mcp/quickstart):** AI assistants like Claude, Cursor, or Windsurf. Drop-in server that exposes actions as tools.
    * **[A2A Protocol](/a2a/quickstart):** Agent-to-agent communication. Google's open protocol for autonomous systems.
    * **[AI Toolset (TypeScript)](/agents/typescript/introduction):** Custom TypeScript agents. Full control with OpenAI, Vercel AI SDK, and more.
    * **[AI Toolset (Python)](/agents/python/introduction):** Custom Python agents. Works with LangChain, CrewAI, PydanticAI, and more.
  </Accordion>

  <Accordion title="Test Actions">
    Try actions before integrating:

    * **[Playground](/guides/playground):** Test actions in the StackOne dashboard with real data.
    * **[Postman](/guides/using-postman):** Import our Postman collection to test the Actions RPC API directly.
    * **[API Reference](/platform/api-reference/actions/make-an-rpc-call-to-an-action):** Full API documentation for the Actions RPC endpoint.
  </Accordion>

  <Accordion title="How Actions Are Built">
    StackOne creates actions by analyzing **thousands of documented APIs** using AI agents and manual QA. Each action is automatically tested, then **manually verified by developers**. Evaluation data continuously improves action quality.
  </Accordion>

  <Accordion title="Adding New Connectors">
    Need a connector that's not listed? [Request it from StackOne](https://www.stackone.com/demo) (delivery depends on roadmap priorities unless on a plan with connector build SLAs) or build your own with Connector Engine.

    <Card title="Build a Connector with Connector Engine" icon="wand-magic-sparkles" href="/guides/connector-engine/introduction">
      Create custom connectors from any API documentation using AI-assisted generation.
    </Card>
  </Accordion>
</AccordionGroup>

## All Connectors

<ConnectorGrid />

***

<LastUpdatedNote />


# Jira
Source: https://docs.stackone.com/connectors/jira/index

147 actions available for Jira through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Jira Service Management
Source: https://docs.stackone.com/connectors/jiraservicemanagement/index

42 actions available for Jira Service Management through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# JobAdder
Source: https://docs.stackone.com/connectors/jobadder/index

246 actions available for JobAdder through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# JotForm
Source: https://docs.stackone.com/connectors/jotform/index

44 actions available for JotForm through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# JumpCloud
Source: https://docs.stackone.com/connectors/jumpcloud/index

65 actions available for JumpCloud through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# JustCall
Source: https://docs.stackone.com/connectors/justcall/index

76 actions available for JustCall through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Kit
Source: https://docs.stackone.com/connectors/kit/index

57 actions available for Kit through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Klaviyo
Source: https://docs.stackone.com/connectors/klaviyo/index

162 actions available for Klaviyo through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# LastPass
Source: https://docs.stackone.com/connectors/lastpass/index

34 actions available for LastPass through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Lattice
Source: https://docs.stackone.com/connectors/lattice/index

34 actions available for Lattice through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Lattice Talent
Source: https://docs.stackone.com/connectors/lattice_talent/index

26 actions available for Lattice Talent through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# LaunchDarkly
Source: https://docs.stackone.com/connectors/launchdarkly/index

85 actions available for LaunchDarkly through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Lemlist
Source: https://docs.stackone.com/connectors/lemlist/index

60 actions available for Lemlist through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Lever
Source: https://docs.stackone.com/connectors/lever/index

77 actions available for Lever through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Liferay
Source: https://docs.stackone.com/connectors/liferay/index

92 actions available for Liferay through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Linear
Source: https://docs.stackone.com/connectors/linear/index

135 actions available for Linear through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# LinkedIn
Source: https://docs.stackone.com/connectors/linkedin/index

2 actions available for LinkedIn through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# LinkedIn Learning
Source: https://docs.stackone.com/connectors/linkedinlearning/index

7 actions available for LinkedIn Learning through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Logfire
Source: https://docs.stackone.com/connectors/logfire/index

30 actions available for Logfire through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# LogicMelon
Source: https://docs.stackone.com/connectors/logicmelon/index

28 actions available for LogicMelon through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Lokalise
Source: https://docs.stackone.com/connectors/lokalise/index

101 actions available for Lokalise through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Lusha
Source: https://docs.stackone.com/connectors/lusha/index

40 actions available for Lusha through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Magento
Source: https://docs.stackone.com/connectors/magento/index

128 actions available for Magento through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Mailchimp
Source: https://docs.stackone.com/connectors/mailchimp/index

80 actions available for Mailchimp through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Mailgun
Source: https://docs.stackone.com/connectors/mailgun/index

89 actions available for Mailgun through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Matillion
Source: https://docs.stackone.com/connectors/matillion/index

40 actions available for Matillion through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Microsoft Entra ID
Source: https://docs.stackone.com/connectors/microsoftentraid/index

67 actions available for Microsoft Entra ID through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Microsoft Excel
Source: https://docs.stackone.com/connectors/microsoftexcel/index

102 actions available for Microsoft Excel through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Microsoft OneDrive
Source: https://docs.stackone.com/connectors/microsoftonedrive/index

46 actions available for Microsoft OneDrive through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Microsoft Outlook
Source: https://docs.stackone.com/connectors/microsoftoutlook/index

39 actions available for Microsoft Outlook through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Microsoft Teams
Source: https://docs.stackone.com/connectors/microsoftteams/index

75 actions available for Microsoft Teams through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Mintlify
Source: https://docs.stackone.com/connectors/mintlify/index

16 actions available for Mintlify through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Miro
Source: https://docs.stackone.com/connectors/miro/index

86 actions available for Miro through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Mistral AI
Source: https://docs.stackone.com/connectors/mistral/index

59 actions available for Mistral AI through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Mixpanel
Source: https://docs.stackone.com/connectors/mixpanel/index

45 actions available for Mixpanel through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Monday.com
Source: https://docs.stackone.com/connectors/monday/index

99 actions available for Monday.com through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Netlify
Source: https://docs.stackone.com/connectors/netlify/index

35 actions available for Netlify through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# New Relic
Source: https://docs.stackone.com/connectors/newrelic/index

126 actions available for New Relic through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Notion
Source: https://docs.stackone.com/connectors/notion/index

35 actions available for Notion through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Nutshell
Source: https://docs.stackone.com/connectors/nutshell/index

75 actions available for Nutshell through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Okta
Source: https://docs.stackone.com/connectors/okta/index

32 actions available for Okta through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# OneLogin
Source: https://docs.stackone.com/connectors/onelogin/index

110 actions available for OneLogin through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# OneNote
Source: https://docs.stackone.com/connectors/onenote/index

37 actions available for OneNote through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# 1Password
Source: https://docs.stackone.com/connectors/onepassword/index

23 actions available for 1Password through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# OpenAI
Source: https://docs.stackone.com/connectors/openai/index

121 actions available for OpenAI through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Open-Meteo
Source: https://docs.stackone.com/connectors/openmeteo/index

6 actions available for Open-Meteo through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# OpenVPN CloudConnexa
Source: https://docs.stackone.com/connectors/openvpncloudconnexa/index

62 actions available for OpenVPN CloudConnexa through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Oracle Fusion HCM
Source: https://docs.stackone.com/connectors/oraclehcm/index

120 actions available for Oracle Fusion HCM through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Orderspace
Source: https://docs.stackone.com/connectors/orderspace/index

42 actions available for Orderspace through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Outlook Calendar
Source: https://docs.stackone.com/connectors/outlookcalendar/index

77 actions available for Outlook Calendar through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Oyster HR
Source: https://docs.stackone.com/connectors/oysterhr/index

52 actions available for Oyster HR through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Paddle
Source: https://docs.stackone.com/connectors/paddle/index

54 actions available for Paddle through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# PagerDuty
Source: https://docs.stackone.com/connectors/pagerduty/index

38 actions available for PagerDuty through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Pardot
Source: https://docs.stackone.com/connectors/pardot/index

88 actions available for Pardot through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# PayFit
Source: https://docs.stackone.com/connectors/payfit/index

23 actions available for PayFit through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Paylocity
Source: https://docs.stackone.com/connectors/paylocity/index

49 actions available for Paylocity through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# PayPal
Source: https://docs.stackone.com/connectors/paypal/index

61 actions available for PayPal through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# PeopleFluent
Source: https://docs.stackone.com/connectors/peoplefluent/index

54 actions available for PeopleFluent through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Personio
Source: https://docs.stackone.com/connectors/personio/index

54 actions available for Personio through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# PingOne
Source: https://docs.stackone.com/connectors/pingone/index

113 actions available for PingOne through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Pinpoint
Source: https://docs.stackone.com/connectors/pinpoint/index

91 actions available for Pinpoint through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Pipedrive
Source: https://docs.stackone.com/connectors/pipedrive/index

121 actions available for Pipedrive through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Pipeliner CRM
Source: https://docs.stackone.com/connectors/pipeliner_crm/index

59 actions available for Pipeliner CRM through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Plaid
Source: https://docs.stackone.com/connectors/plaid/index

59 actions available for Plaid through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Planday
Source: https://docs.stackone.com/connectors/planday/index

73 actions available for Planday through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# PostHog
Source: https://docs.stackone.com/connectors/posthog/index

63 actions available for PostHog through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Pylon
Source: https://docs.stackone.com/connectors/pylon/index

52 actions available for Pylon through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Qlik
Source: https://docs.stackone.com/connectors/qlik/index

100 actions available for Qlik through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# QuickBooks Online
Source: https://docs.stackone.com/connectors/quickbooksonline/index

95 actions available for QuickBooks Online through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Rally
Source: https://docs.stackone.com/connectors/rally/index

68 actions available for Rally through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Range
Source: https://docs.stackone.com/connectors/range/index

13 actions available for Range through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Re:amaze
Source: https://docs.stackone.com/connectors/reamaze/index

33 actions available for Re:amaze through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Recruitee
Source: https://docs.stackone.com/connectors/recruitee/index

26 actions available for Recruitee through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Recurly
Source: https://docs.stackone.com/connectors/recurly/index

138 actions available for Recurly through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Remote
Source: https://docs.stackone.com/connectors/remote/index

68 actions available for Remote through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Render
Source: https://docs.stackone.com/connectors/render/index

98 actions available for Render through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Reo.dev
Source: https://docs.stackone.com/connectors/reodev/index

8 actions available for Reo.dev through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Retool
Source: https://docs.stackone.com/connectors/retool/index

44 actions available for Retool through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Rippling
Source: https://docs.stackone.com/connectors/rippling/index

37 actions available for Rippling through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Rollbar
Source: https://docs.stackone.com/connectors/rollbar/index

25 actions available for Rollbar through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Saba
Source: https://docs.stackone.com/connectors/saba/index

122 actions available for Saba through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Sage HR
Source: https://docs.stackone.com/connectors/sagehr/index

35 actions available for Sage HR through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Salesforce
Source: https://docs.stackone.com/connectors/salesforce/index

380 actions available for Salesforce through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Salesforce Marketing Cloud
Source: https://docs.stackone.com/connectors/salesforcemc/index

50 actions available for Salesforce Marketing Cloud through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Salesforce Service Cloud
Source: https://docs.stackone.com/connectors/salesforceservicecloud/index

34 actions available for Salesforce Service Cloud through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Salesloft
Source: https://docs.stackone.com/connectors/salesloft/index

39 actions available for Salesloft through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# SAP SuccessFactors
Source: https://docs.stackone.com/connectors/sapsuccessfactors/index

111 actions available for SAP SuccessFactors through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# SEC EDGAR
Source: https://docs.stackone.com/connectors/secedgar/index

7 actions available for SEC EDGAR through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# SendGrid
Source: https://docs.stackone.com/connectors/sendgrid/index

100 actions available for SendGrid through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Sentinel XS
Source: https://docs.stackone.com/connectors/sentinelxs/index

69 actions available for Sentinel XS through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Sentry
Source: https://docs.stackone.com/connectors/sentry/index

74 actions available for Sentry through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# ServiceNow
Source: https://docs.stackone.com/connectors/servicenow/index

77 actions available for ServiceNow through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Sesame HR
Source: https://docs.stackone.com/connectors/sesame/index

60 actions available for Sesame HR through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# SharePoint
Source: https://docs.stackone.com/connectors/sharepoint/index

19 actions available for SharePoint through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# ShipStation
Source: https://docs.stackone.com/connectors/shipstation/index

45 actions available for ShipStation through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Shopify
Source: https://docs.stackone.com/connectors/shopify/index

85 actions available for Shopify through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Shortcut
Source: https://docs.stackone.com/connectors/shortcut_pm/index

91 actions available for Shortcut through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Simployer One
Source: https://docs.stackone.com/connectors/simployer/index

54 actions available for Simployer One through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Slack
Source: https://docs.stackone.com/connectors/slack/index

38 actions available for Slack through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# SmartRecruiters
Source: https://docs.stackone.com/connectors/smartrecruiters/index

164 actions available for SmartRecruiters through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Smartsheet
Source: https://docs.stackone.com/connectors/smartsheet/index

189 actions available for Smartsheet through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Snowflake
Source: https://docs.stackone.com/connectors/snowflake/index

80 actions available for Snowflake through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Sophos Central
Source: https://docs.stackone.com/connectors/sophos/index

54 actions available for Sophos Central through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Spotify
Source: https://docs.stackone.com/connectors/spotify/index

47 actions available for Spotify through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Square
Source: https://docs.stackone.com/connectors/square/index

125 actions available for Square through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Squarespace
Source: https://docs.stackone.com/connectors/squarespace/index

27 actions available for Squarespace through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Staffology HR
Source: https://docs.stackone.com/connectors/staffologyhr/index

46 actions available for Staffology HR through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Stripe
Source: https://docs.stackone.com/connectors/stripe/index

133 actions available for Stripe through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Supabase
Source: https://docs.stackone.com/connectors/supabase/index

129 actions available for Supabase through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# SurveyMonkey
Source: https://docs.stackone.com/connectors/surveymonkey/index

104 actions available for SurveyMonkey through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Tableau
Source: https://docs.stackone.com/connectors/tableau/index

122 actions available for Tableau through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Talend
Source: https://docs.stackone.com/connectors/talend/index

60 actions available for Talend through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Teamtailor
Source: https://docs.stackone.com/connectors/teamtailor/index

106 actions available for Teamtailor through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Teamwork
Source: https://docs.stackone.com/connectors/teamwork/index

123 actions available for Teamwork through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Telegram
Source: https://docs.stackone.com/connectors/telegram/index

38 actions available for Telegram through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Terraform
Source: https://docs.stackone.com/connectors/terraform/index

118 actions available for Terraform through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Thrive Learning
Source: https://docs.stackone.com/connectors/thrive/index

38 actions available for Thrive Learning through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# TikTok Ads
Source: https://docs.stackone.com/connectors/tiktokads/index

51 actions available for TikTok Ads through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Todoist
Source: https://docs.stackone.com/connectors/todoist/index

52 actions available for Todoist through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Toggl
Source: https://docs.stackone.com/connectors/toggl/index

92 actions available for Toggl through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Trello
Source: https://docs.stackone.com/connectors/trello/index

133 actions available for Trello through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Twilio
Source: https://docs.stackone.com/connectors/twilio/index

40 actions available for Twilio through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Typeform
Source: https://docs.stackone.com/connectors/typeform/index

25 actions available for Typeform through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Udemy
Source: https://docs.stackone.com/connectors/udemy/index

9 actions available for Udemy through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# UKG Pro
Source: https://docs.stackone.com/connectors/ukg-pro/index

56 actions available for UKG Pro through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# UKG Ready
Source: https://docs.stackone.com/connectors/ukg-ready/index

139 actions available for UKG Ready through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Unbounce
Source: https://docs.stackone.com/connectors/unbounce/index

23 actions available for Unbounce through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Veremark
Source: https://docs.stackone.com/connectors/veremark/index

22 actions available for Veremark through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Vimeo
Source: https://docs.stackone.com/connectors/vimeo/index

100 actions available for Vimeo through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Vincere
Source: https://docs.stackone.com/connectors/vincere/index

206 actions available for Vincere through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Vtiger
Source: https://docs.stackone.com/connectors/vtiger/index

56 actions available for Vtiger through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Webex
Source: https://docs.stackone.com/connectors/webex/index

112 actions available for Webex through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Webflow
Source: https://docs.stackone.com/connectors/webflow/index

98 actions available for Webflow through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# WhatsApp Business
Source: https://docs.stackone.com/connectors/whatsapp-business/index

58 actions available for WhatsApp Business through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Wistia
Source: https://docs.stackone.com/connectors/wistia/index

63 actions available for Wistia through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# WooCommerce
Source: https://docs.stackone.com/connectors/woocommerce/index

72 actions available for WooCommerce through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Workable
Source: https://docs.stackone.com/connectors/workable/index

70 actions available for Workable through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Workday (Rest and Soap)
Source: https://docs.stackone.com/connectors/workday/index

128 actions available for Workday (Rest and Soap) through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Wrike
Source: https://docs.stackone.com/connectors/wrike/index

47 actions available for Wrike through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# X (Twitter)
Source: https://docs.stackone.com/connectors/x/index

55 actions available for X (Twitter) through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Xero
Source: https://docs.stackone.com/connectors/xero/index

70 actions available for Xero through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Xyleme
Source: https://docs.stackone.com/connectors/xyleme/index

79 actions available for Xyleme through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# YouTube
Source: https://docs.stackone.com/connectors/youtube/index

47 actions available for YouTube through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Zelt
Source: https://docs.stackone.com/connectors/zelt/index

34 actions available for Zelt through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Zendesk
Source: https://docs.stackone.com/connectors/zendesk/index

43 actions available for Zendesk through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Zinc
Source: https://docs.stackone.com/connectors/zinc/index

8 actions available for Zinc through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Zoho Desk
Source: https://docs.stackone.com/connectors/zoho-desk/index

40 actions available for Zoho Desk through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Zoho Books
Source: https://docs.stackone.com/connectors/zohobooks/index

107 actions available for Zoho Books through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Zoho BugTracker
Source: https://docs.stackone.com/connectors/zohobugtracker/index

51 actions available for Zoho BugTracker through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Zoho CRM
Source: https://docs.stackone.com/connectors/zohocrm/index

126 actions available for Zoho CRM through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Zoho People
Source: https://docs.stackone.com/connectors/zohopeople/index

73 actions available for Zoho People through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Zoho Recruit
Source: https://docs.stackone.com/connectors/zohorecruit/index

63 actions available for Zoho Recruit through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Zoho Sprints
Source: https://docs.stackone.com/connectors/zohosprints/index

76 actions available for Zoho Sprints through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Zoom
Source: https://docs.stackone.com/connectors/zoom/index

54 actions available for Zoom through StackOne. Use via Actions RPC, Toolset SDK, MCP, or A2A.

<ConnectorPage />


# Get Drive
Source: https://docs.stackone.com/documents/api-reference/drives/get-drive

get /unified/documents/drives/{id}



# List Drives
Source: https://docs.stackone.com/documents/api-reference/drives/list-drives

get /unified/documents/drives



# Download File
Source: https://docs.stackone.com/documents/api-reference/files/download-file

get /unified/documents/files/{id}/download



# Get File
Source: https://docs.stackone.com/documents/api-reference/files/get-file

get /unified/documents/files/{id}



# List Files
Source: https://docs.stackone.com/documents/api-reference/files/list-files

get /unified/documents/files



# Upload File
Source: https://docs.stackone.com/documents/api-reference/files/upload-file

post /unified/documents/files/upload



# Get Folder
Source: https://docs.stackone.com/documents/api-reference/folders/get-folder

get /unified/documents/folders/{id}



# List Folders
Source: https://docs.stackone.com/documents/api-reference/folders/list-folders

get /unified/documents/folders



# Basic Authentication with StackOne API
Source: https://docs.stackone.com/documents/common-guide/basic-authentication-with-stackone-api

Learn how to authenticate with the StackOne API using Basic Authentication.

## Overview

StackOne uses API key-based authentication to secure access to all endpoints. This guide explains how to use your API keys with Basic Authentication to make secure requests to the StackOne API.

<Info>
  **Basic Authentication** is one of the simplest authentication methods where credentials are sent as a Base64-encoded string in the Authorization header.
</Info>

## Prerequisites

Before using Basic Authentication, ensure you have completed these steps:

➡️ **[Create an API Key](/guides/api-keys)** : Generate your API key from the StackOne Dashboard

## Steps for Basic Authentication

<Steps>
  <Step title="Convert the API Key into a Base64 Encoded String">
    To authenticate using Basic Auth, you must convert your API key into a Base64 encoded string.

    <Warning>
      **Important**: The API key must be base64 encoded when using Basic authentication. You cannot use the raw API key directly.
    </Warning>

    Here are examples of how to encode your API key:

    **Terminal/Command Line:**

    ```bash theme={null}
    echo -n "your_api_key_here" | base64
    ```

    **Python:**

    ```python theme={null}
    import base64

    api_key = 'your_api_key_here'
    base64_api_key = base64.b64encode(api_key.encode()).decode()
    print(base64_api_key)
    ```

    **JavaScript/Node.js:**

    ```javascript theme={null}
    const apiKey = 'your_api_key_here';
    const base64ApiKey = Buffer.from(apiKey).toString('base64');
    console.log(base64ApiKey);
    ```

    **Example**: If your API key is `v1.eu1.abc123xyz`, the base64 encoded result would be: `djEuZXUxLmFiYzEyM3h5eg==`
  </Step>

  <Step title="Using the Base64 Encoded API Key for API Requests">
    Include the Base64 encoded API key in the Authorization header of your requests.

    **Header Format:**

    ```bash theme={null}
    Authorization: Basic <BASE64_ENCODED_API_KEY>
    ```

    **Complete cURL Example:**

    ```bash theme={null}
    curl --request GET \
         --url 'https://api.stackone.com/accounts' \
         --header 'accept: application/json' \
         --header 'authorization: Basic djEuZXUxLmFiYzEyM3h5eg=='
    ```
  </Step>

  <Step title="Making Unified API Requests">
    For unified API endpoints, you'll also need to include the account ID in the `x-account-id` header:

    ```bash theme={null}
    curl --request GET \
         --url 'https://api.stackone.com/unified/ats/applications' \
         --header 'accept: application/json' \
         --header 'authorization: Basic djEuZXUxLmFiYzEyM3h5eg==' \
         --header 'x-account-id: your_account_id_here'
    ```

    <Note>
      Replace `your_account_id_here` with the actual account ID obtained from the [List Accounts](/platform/api-reference/accounts/list-accounts) endpoint.
    </Note>
  </Step>

  <Step title="Using StackOne SDKs with Basic Authentication">
    StackOne provides official SDKs for multiple programming languages that simplify API integration and handle authentication automatically. Here's how to initialize each SDK with your API key:

    <Tabs>
      <Tab title="TypeScript">
        ```typescript theme={null}
        import { StackOne } from '@stackone/stackone-client-ts';

        // Initialize the StackOne client with your API credentials
        const stackOne = new StackOne({
          security: {
            username: "your_api_key_here",
            password: "",
          },
        });

        // Example: List accounts
        const accounts = await stackOne.accounts.list();

        // Example: Make a unified API request
        const applications = await stackOne.ats.applications.list({
          accountId: 'your_account_id_here'
        });
        ```
      </Tab>

      <Tab title="Ruby">
        ```ruby theme={null}
        require 'stackone_client'

        # Initialize the StackOne client with your API key
        s = ::StackOne::StackOne.new(
          security: Models::Shared::Security.new(
            password: "",
            username: "your_api_key_here",
          ),
        )

        # Example: List accounts
        res = s.accounts.list_linked_accounts()
        if ! res.linked_accounts_paginated.nil?
          # handle response
        end

        # Example: Make a unified API request
        req = Models::Operations::AtsListApplicationsRequest.new(
          x_account_id: "your_account_id_here",
        )
        res = s.ats.list_applications(req)
        if ! res.applications_paginated.nil?
          # handle response
        end
        ```
      </Tab>

      <Tab title="PHP">
        ```php theme={null}
        <?php
        require_once 'vendor/autoload.php';

        use StackOne\client;
        use StackOne\client\Models\Components;

        // Initialize the StackOne client with your API credentials
        $sdk = client\StackOne::builder()
            ->setSecurity(
                new Components\Security(
                    username: 'your_api_key_here',
                    password: '',
                )
            )
            ->build();

        // Example: List accounts
        $result = $sdk->accounts->listLinkedAccounts();

        // Example: Make a unified API request
        $result = $sdk->ats->listApplications(
            xAccountId: 'your_account_id_here',
        );
        ?>
        ```
      </Tab>

      <Tab title="Java">
        ```java theme={null}
        import com.stackone.stackone_client_java.StackOne;
        import com.stackone.stackone_client_java.models.components.Security;
        import com.stackone.stackone_client_java.models.operations.ListLinkedAccountsResponse;
        import com.stackone.stackone_client_java.models.operations.AtsListApplicationsResponse;

        // Initialize the StackOne client with your API credentials
        StackOne sdk = StackOne.builder()
            .security(Security.builder()
                .username("your_api_key_here")
                .password("")
                .build())
            .build();

        // Example: List accounts
        ListLinkedAccountsResponse res = sdk.accounts().listLinkedAccounts()
            .call();

        // Example: Make a unified API request
        AtsListApplicationsResponse res = sdk.ats().listApplications()
            .xAccountId("your_account_id_here")
            .call();
        ```
      </Tab>

      <Tab title="C#">
        ```csharp theme={null}
        using StackOneHQ.Client;
        using StackOneHQ.Client.Models.Components;
        using StackOneHQ.Client.Models.Operations;

        // Initialize the StackOne client with your API credentials
        var sdk = new StackOneHQClient(security: new Security() {
            Username = "your_api_key_here",
            Password = "",
        });

        // Example: List accounts
        var res = await sdk.Accounts.ListLinkedAccountsAsync();

        // Example: Make a unified API request
        var res = await sdk.Ats.ListApplicationsAsync(new AtsListApplicationsRequest() {
            XAccountId = "your_account_id_here",
        });
        ```
      </Tab>
    </Tabs>

    <Note>
      The SDKs automatically handle Base64 encoding and proper Authorization header formatting for HTTP Basic Authentication. Provide your raw API key in the `username` field and leave `password` empty when initializing the client.
    </Note>
  </Step>
</Steps>

## Security Best Practices

<Warning>
  **Store API Keys Securely**: Never expose API keys in client-side code, version control, or public repositories. Store them in secure locations such as environment variables or key vaults.
</Warning>

* Use environment variables to pass API keys to your application
* Rotate API keys regularly for enhanced security
* Use API key scopes to limit permissions when possible
* Monitor API key usage through the StackOne Dashboard

## Next Steps

After setting up Basic Authentication:

1. **[Making Your First API Request](/guides/making-your-first-api-request)** - Step-by-step examples for common API operations
2. **[Explore API Endpoints](/platform/api-reference)** - Browse available Platform API endpoints
3. **[Try Unified APIs](/documents/introduction)** - Start with Documents or IAM
4. **[Use SDKs](/guides/stackone-api-sdks)** - Simplify integration with official SDKs
5. **[Set up Webhooks](/guides/webhooks)** - Get real-time updates from connected providers

## Additional Resources

* [API Keys Management Guide](/guides/api-keys)
* [Making Your First API Request](/guides/making-your-first-api-request)
* [StackOne API SDKs](/guides/stackone-api-sdks)
* [Rate Limiting](/guides/rate-limiting)


# Expression Language Syntax
Source: https://docs.stackone.com/documents/common-guide/expression-language-syntax

Learn about the expression language syntax for field mapping and transformations.

There are three types of expressions supported:

### JSON Path Expressions

When the expression starts with `$`, it is treated as a JSON Path expression and will be evaluated as such.

#### JSON Path Syntax

| JSON Path              | Description                                                        |
| ---------------------- | :----------------------------------------------------------------- |
| `$`                    | The root object                                                    |
| `.`                    | Child operator                                                     |
| `@`                    | The current object                                                 |
| `*`                    | Wildcard. All elements in an array, or all properties of an object |
| `..`                   | Recursive descent                                                  |
| `[]`                   | Subscript operator                                                 |
| `[,]`                  | Union operator                                                     |
| `[start : end : step]` | Array slice operator                                               |
| `?(expression)`        | Filter expression                                                  |
| `()`                   | Script expression                                                  |

Examples:

```js theme={null}
// Given the context: { user: { name: "John", age: 30 }, "info/email": "info@email.com" }
'$.user.name'         // Returns "John"
'$.user.age'          // Returns 30
'$.user[*]'           // Returns ["John", 30]
'$["info/email"]'     // Returns "info@email.com"
```

For more information on JSON Path syntax, refer to the original [JSON Path documentation](https://goessner.net/articles/JsonPath/).

### JEXL Expressions

This kind of expression is enclosed in double brackets `{{expression}}`. It supports variables and operators.

#### Operators

| Operator | Description                    |
| :------- | :----------------------------- |
| `!`      | Logical NOT                    |
| `+`      | Addition, string concatenation |
| `-`      | Subtraction                    |
| `*`      | Multiplication                 |
| `/`      | Division                       |
| `//`     | Floor division                 |
| `%`      | Modulus                        |
| `^`      | Exponentiation                 |
| `&&`     | Logical AND                    |
| `\|`     | Logical OR                     |
| `==`     | Equal                          |
| `!=`     | Not equal                      |
| `>`      | Greater than                   |
| `>=`     | Greater than or equal          |
| `<`      | Less than                      |
| `<=`     | Less than or equal             |
| `in`     | Element of string or array     |
| `? :`    | Ternary operator               |

Examples:

```js theme={null}
// Given the context: { x: 10, y: 5 }
'{{x + y}}'                  // Returns 15
'{{x * 2}}'                  // Returns 20
'{{x > y}}'                  // Returns true
'{{x == 10 ? "yes" : "no"}}' // Returns "yes"
'{{x in [1, 2, 3]}}'         // Returns false
'{{x != y}}'                 // Returns true
```

#### Identifiers

Identifiers can be used to reference variables in the context.

```js theme={null}
// Given the context:
// { 
//     name: {
//         first: "John",
//         last: "Smith"
//     },
//     jobs: ["Developer", "Designer"]
// }
`{{name.first}}`          // Returns "John"
`{{jobs[1]}}`             // Returns "Designer"
```

#### Collections

Collections, or arrays of objects, can be filtered by including a filter expression in brackets.

```js theme={null}
// Given the context:
// {
//     users: [
//         { name: "John", age: 30 },
//         { name: "Jane", age: 25 }
//     ]
// }
`{{users[.name == "John"].age}}` // Returns 30
`{{users[.age > 25].name}}`      // Returns ["John"]
```

### String Interpolation

To simplify strings usage, a more straightforward syntax is provided for string interpolation of variables using the `${var}` syntax.

Examples:

```js theme={null}
// Given the context: { name: "John", age: 30 }
"Hello ${name}"       // Returns "Hello John"
"User is ${age}"    // Returns "User is 30"
```

Note: If the expression is a string without any of the patterns described above, it will be returned as is.

```js theme={null}
// Given the context: { name: "John", age: 30 }
"Hello world"       // Returns "Hello world"
```

For more information on the JEXL syntax, refer to the [JEXL Syntax documentation](https://commons.apache.org/proper/commons-jexl/reference/syntax.html).


# Field Coverage
Source: https://docs.stackone.com/documents/common-guide/field-coverage

Understand which fields are supported across different connectors and API operations.

<Frame>
  <img alt="" />
</Frame>

# Overview

Field Coverage is a feature in StackOne that helps you understand which fields are supported across different connectors and API operations. This tool is great for planning your implementation, evaluating connector compatibility, and ensuring your use cases can be fully supported.

> Field Coverage is available in the Dashboard at [app.stackone.com/field\_coverage](https://app.stackone.com/field_coverage)

# Key Features

## Search Experience

The field coverage interface provides a multiselect search experience.

* Search by field and model
* Layer multiple search terms and filters to display the union of all results
* Fuzzy search - find fields and models even with partial or similar names

<Frame>
  <img alt="" />
</Frame>

## Filters

### Integration Filters

Filter field coverage by specific connectors to focus on those relevant to your use case.

* **Category filters**: HRIS, ATS, CRM, LMS, Marketing, Documents, etc.
* **Provider filters**: Specific providers (e.g., BambooHR, Greenhouse, HubSpot)
* **Status filters**: Active connectors

### Operation Filters

Narrow down results by operation filters.

* **List operations**: Fields available when listing resources
* **Get operations**: Fields available when retrieving individual resources
* **Create operations**: Fields that can be set when creating new resources
* **Update operations**: Fields that can be modified in existing resources

<Frame>
  <img alt="" />
</Frame>

## Export Behavior

Field coverage data can be exported as CSV for analysis and documentation.

* **CSV export**: For spreadsheet analysis and reporting

### Export Options

1. **Full export**: All field coverage data across all connectors
2. **Filtered export**: Only data matching your current filters

<Frame>
  <img alt="" />
</Frame>

## Key/Legend

Understanding the visual indicators in field coverage.

### Operation Indicators

* **GET - Green G**
* **LIST - Blue L**
* **CREATE - Brown C**
* **UPDATE - Purple U**
* **UPSERT - Teal UP**

### Capability Indicators

* **Custom fields**: Wrench/gear icon indicating custom field support
* **Enums**: Lowercase 'e' icon indicating enum field support
* **Required**: Red dot in white square indicating required fields
* **Conditionally required**: Orange dot with red outline indicating conditionally required fields
* **Filtering**: Filter icon indicating filtering support
* **Batch**: Refresh/sync icon indicating batch operation support
* **Unsupported by Provider**: Grey icon with strikethrough indicating unsupported fields

<Frame>
  <img alt="" />
</Frame>

# Use Cases

## Evaluating New Connectors

**Scenario**: You want to evaluate whether a new connector can support your use case.

### Step-by-Step Process

1. **Filter for the specific integration**
   * Choose the relevant category (HRIS, ATS, CRM, etc.)
   * Use the integration filter to select the connector you're evaluating

2. **Search for specific fields**
   * Use the search functionality to find fields critical to your use case
   * Look for both exact matches and similar field names

3. **Expand relevant objects/models**
   * Click on objects to see their complete field structure
   * Check nested objects and relationships

4. **Analyze coverage**
   * Review the coverage indicators for each required field
   * Note any limitations or unsupported fields

5. **Export results**
   * Export the filtered data for stakeholder review
   * Document gaps and workarounds

## Integration Planning

**Scenario**: Planning a new integration and need to understand field availability.

### Best Practices

1. **Start with core fields**
   * Identify the essential fields for your use case
   * Check coverage across multiple potential connectors

2. **Compare connectors**
   * Use filters to compare field support across different providers
   * Export comparison data for decision-making

3. **Plan for gaps**
   * Identify unsupported fields early
   * Consider alternative approaches or custom field mapping

## API Development

**Scenario**: Building an application that consumes StackOne APIs.

### Development Workflow

1. **Research field availability**
   * Use field coverage to understand what data is available
   * Plan your data models based on actual field support

2. **Handle field variations**
   * Use the expand functionality to understand field differences
   * Implement fallback logic for unsupported fields

3. **Optimize API calls**
   * Use field coverage to determine which fields to request
   * Avoid requesting unsupported fields to improve performance

# Caveats and Disclaimers

## Coverage Accuracy

<Warning>
  **Field coverage data may not always reflect the complete picture**
</Warning>

* **Dynamic fields**: Some connectors support dynamic or custom fields that may not appear in coverage data
* **Provider updates**: Integration providers may add or modify fields without immediate coverage updates
* **Conditional support**: Some fields may be available under specific conditions or configurations

## Limitations

### Data Freshness

* Field coverage is updated regularly but may lag behind provider changes
* Always verify critical field support through testing or direct API calls

## Best Practices

1. **Verify with testing**: Always test critical fields with actual API calls
2. **Stay updated**: Regularly check field coverage for updates
3. **Contact support**: Reach out to StackOne support for clarification on specific field support
4. **Document findings**: Keep records of field support for your specific use cases

# Getting Help

If you need assistance with field coverage or have questions about specific field support:

* **Status Page**: Check [status.stackone.com](https://status.stackone.com) for system status and incidents
* **Documentation**: Check the relevant [API Reference](/hris/introduction) for detailed field information
* **Support**: Contact StackOne support through the in-app support, email ([support@stackone.com](mailto:support@stackone.com))


# Field Mapping
Source: https://docs.stackone.com/documents/common-guide/field-mapping

Learn how to map custom fields across different providers using StackOne's unified field mapping.

<Frame>
  <img alt="" />
</Frame>

# Overview

Custom Unified Fields enables you to create bespoke fields that and implement them across any connector already supported on the StackOne platform.

This gives you flexibility and control over any unified API and connectors available on StackOne, allowing you to tailor each connector to meet your specific product needs.

➡️ Custom unified fields can only use data that is already returned by underlying connectors. You cannot fetch additional requests or use data not already present in the underlying provider requests that StackOne's default unified operations make.

➡️ Custom unified fields are, like any other unified fields, real-time by default meaning that the data returned by the StackOne unified API will reflect the latest values from the source fields.

> 🙋 Reach out to StackOne's support to get Custom Unified Fields enabled for your organization

# Use-cases

Use-cases are broad and entirely dependant on the product and feature you're building and what type of connectors you're using. Some examples of custom unified fields:

* A new `emergency_contact_number` to be retrieved when listing [Employees](/hris/api-reference/employees/list-employees) (HRIS)
* A `multi_factor_authentication` boolean variable on IAM [Users](/iam/api-reference/users/list-users) on top of the existing array (IAM)
* Support for an LMS [Content](/lms/api-reference/content/list-content) `label` surfacing label and tag data from LMS systems that support it (LMS)

# Nomenclature:

We'll refer throughout the guides and user interface to various properties

* **Custom Unified Field:** A user-defined field that can be mapped and unified across various connectors by a Project Admin
* **Variable Key:** The unique identifier for the custom field.
* **Display Name:** The user-friendly name for the custom field.
* **Variable Type:** The data type of the custom field (currently only primitive data types are supported).
* **Field Mapping:** The process of linking a custom unified field to fields from different HR systems.

# Creating and managing fields

Project admins can access the field mapping section by clicking on ["Field Mapping"](https://app.stackone.com/field_mapping) in the left-hand menu.:

<Frame>
  <img alt="" />
</Frame>

To create the Custom Unified Field, you will need to specify the necessary details such as the Variable Key (which will be the actual property key in the returned JSON, an associated Type and a name & description to go with it (meant more for documentation and readability purposes as these latter two will not be returned in the request's response). All these details can be updated later via the `edit` button.

<Frame>
  <img alt="" />
</Frame>

### Limitations

* **Data Types:** Only primitive data types (string, number, boolean) are supported. Values will be typecasted when possible.
* **Operations:** Initially, only read operations (List and Get) are supported. Write operations will be introduced in future updates.

# Future capabilities of custom unified fields

Currently, Custom Unified Field mapping allows you to pull and use information that is already returned by the provider. Here's what we'll enable and add in future release

* Ability to update and add underlying provider requests so you can use more data from the underlying tools
* Creation of brand new operations and unified models
* Operations, formulas and functions so you can create more complex, derived fields and values.
* Account specific overrides so you can have different mapping per account and use tenant-based custom fields for specific field mappings when relevant

# FAQ

**Why can't I see the `Field Mapping` section in the side-menu?**\
The feature is only available to Project Admin and needs to first be enabled by StackOne (reach out to StackOne support for it to be enabled for your organization)

**Why can't I see the unified model I want to add custom unified for in the `Field Mapping` page?**\
Only pre-selected unified models have been enabled, if you would like to access another model available in our API but not visible in the custom unified fields section, reach out to our support team.

**How can I map a complex object like an array, enum or object?**\
This is currently not supported in the beta version but will come shortly with the global release of this feature.


# Integration Field Mapping
Source: https://docs.stackone.com/documents/common-guide/integration-field-mapping

Learn how to configure field mappings for specific integrations.

Once you've created a [custom unified field](/guides/field-mapping), you need to define the "mapping" for each integration you want this field to be enabled and usable for.

<Frame>
  <img alt="" />
</Frame>

Adding an integration field mapping is done via the *integration-level* mapping tab after selecting a specific custom unified field.

<Info>
  Only connectors configured and enabled on the [Connector Profiles](https://app.stackone.com/connector_profiles) page can be mapped.
</Info>

# Configuring the mapping

Although it's possible to map without using an underlying linked account, it's always advised to use a connected linked account (eg. a sandbox account) to have the most realistic view of what type of properties and fields may be available on the underlying integration.

<Frame>
  <img alt="" />
</Frame>

## Preview & Test

1. **Preview Fields:** *(optional)*
   * Select a source from the dropdown list to pull a sample set of field data.
   * Click on "Request" to preview the data.
   * Example preview JSON response:
     ```json theme={null}
     {
       "employees": [
         {
           "id": "5",
           "firstName": "Anna",
           "lastName": "Skywalker",
           "terminationDate": "2024-05-28"
         }
       ]
     }
     ```
2. **Field Mapping Steps:**
   * **Step 1:** Select the source field you want to map from the integration.
   * **Step 2:** Enter the target custom field name.
   * **Step 3:** Use the expression language syntax to point to the relevant integration field
     * Example: `$.employees.output.data.terminationDate`

***

### Tips & Tricks

#### Mapping array values

Some origin data will return a list of resources instead of a single resource (eg: all the documents instead of a specific document). In this case, you should make sure to use one of the provided default variables (eg: `id`) to find the element in the array that matches the ID.

#### Expression language

Custom unified fields can be mapped using the StackOne's expression language. This language supports JSON path syntax, JEXL expressions for more complex use cases or simple string interpolation. For more information about all the expression language capabilities please refer to the [Expression language syntax documentation](/guides/expression-language-syntax).

***

## Additional Features:

* **Typecasting:** Values will be automatically typecasted to the defined variable type when possible (eg: if the variable type is a `string` but the underlying integration returns a `number` the number will be return as a string and vice-versa).
* **Viewing Mappings:** Once an integration mapping is configured, the source will be visible directly in the integration-level mapping list:

  <Frame>
    <img alt="" />
  </Frame>

# Using a Custom Unified Field

Once you have configured an integration custom field mapping you will need to make sure the field is enabled:

<Frame>
  <img alt="" />
</Frame>

You can retrieve the data via any `GET` or `LIST` API request for the model you created the field on:

The unified custom field will be embedded in an property called `unified_custom_fields`.

<Frame>
  <img alt="" />
</Frame>

<Info>
  When using SDKs (ie: Typescript SDK) the property may be camel cased instead (ie: `unifiedCustomFields`). The SDK will not have types for the individual properties contained in this object given it is fully customizable.
</Info>


# Pagination
Source: https://docs.stackone.com/documents/common-guide/pagination

Understand cursor-based pagination in the Documents API and how to efficiently retrieve large datasets.

StackOne's <Tooltip>Unified API</Tooltip> allows paginating on API requests that return multiple records using a page cursor.

The following optional URL parameters are used for pagination:

<ParamField type="string">
  The number of records per page.
</ParamField>

<ParamField type="string">
  The `next` parameter is used to iterate through data pages.
</ParamField>

<Warning>
  It is recommended to keep the same page\_size throughout the sequence of pagination requests otherwise unexpected behaviour may occur.
</Warning>

## Sample URL

```
https://api.stackone.com/unified/hris/employees?page_size=25&next=eyJyIjphAsHHere
```

## Sample Response

In the response payload, you can find the `next` cursor. To get the next page of data send a new request with the `next` parameter set to this value.

```json theme={null}
"next":"eyJyIjphAsHHere",
"data":[
   0: [...],
   1: [...],
   ...
   24: [...],
]
```

Once the cursor reaches the end of the data list, both values become NULL.

## Page Size

By default, the `page_size` parameter is set to 25 results per page, you can over-ride this by passing in a custom page size with this parameter. If fewer records remain in the underlying connected provider than a given page\_size, you will not receive a `next`  cursor value on the next request.

For example, if you have 17 records in total, all of them will be shown on one page with `next` parameter being empty. Then you specify the `page_size` = 10, you'll get the `next` value. If you use this `next` value, you will get a stripped array of the last 7 records.

## Early Cursor return

Occasionally we have to apply custom filters or structure requests to ensure we can get data which is not returned by the native API, this can cause timeout issues where we wouldn't fill an entire page.

In this case we will return a cursor value with the incomplete page, and you can continue paginating through the data to the end of the data set. When the final record is reached on the underlying provider we will return an empty next cursor.

```json theme={null}
"next":"eyJyIjphAsHHere",
"data":[]
```


# API SDKs
Source: https://docs.stackone.com/documents/common-guide/stackone-api-sdks

Language-native libraries for StackOne Unified APIs

## Postman

StackOne maintains a Postman collection to more easily test & interact with the StackOne internal API and unified APIs:  [***Run in Postman***](https://god.gw.postman.com/run-collection/25987823-c68540f2-7aba-475e-89d2-77625c6a6424?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D25987823-c68540f2-7aba-475e-89d2-77625c6a6424%26entityType%3Dcollection%26workspaceId%3Df291b2e0-d0cb-4dc2-93c4-c2d4f581da3f)

* You can also directly Download / import the Postman collection [via our github repository](https://github.com/StackOneHQ/stackone-client-postman)

## Unified API SDKs

StackOne maintains and publishes the following SDKs:

* **Ruby** ([RubyGems](https://rubygems.org/gems/stackone_client), [GitHub](https://github.com/StackOneHQ/stackone-client-ruby))
* **Typescript** ([npm](https://www.npmjs.com/package/@stackone/stackone-client-ts), [GitHub](https://github.com/StackOneHQ/stackone-client-typescript))
* **PHP** ([Packagist](https://packagist.org/packages/stackone/client-sdk), [GitHub](https://github.com/stackoneHQ/stackone-client-php)) - Beta
* **Java** ([Maven](https://mvnrepository.com/artifact/com.stackone/stackone-client-java), [GitHub](https://github.com/StackOneHQ/stackone-client-java)) - Beta
* **C#** ([nuget](https://www.nuget.org/packages/StackOneHQ.Client), [GitHub](https://github.com/StackOneHQ/stackone-client-csharp)) - Beta

Additionally, our API Reference provides code snippets in multiple languages (JavaScript, Python, PHP, Go, Java, Ruby), making it easy to copy and test our endpoints.

## AI Tools

StackOne makes it easy for AI agents to interact with any connected SaaS via its AI Toolset:

* **Node/Typescript** ([GitHub](https://github.com/StackOneHQ/stackone-ai-node))
  * [Basic Usage](/agents/typescript/basic-usage)
* **Python** ([GitHub](https://github.com/stackoneHQ/stackone-ai-python))

Reach out to our team via your dedicated Slack channel or at [support@stackone.com](mailto:support@stackone.com) to request access to any other SDK.


# StackOne Identifiers
Source: https://docs.stackone.com/documents/common-guide/stackone-identifiers

Understand synthetic IDs and how to use them interchangeably with provider IDs across the unified API

# Understanding Synthetic IDs in Our API

We often need to combine data from multiple sources to create unified responses. For instance, consider Workday's Applications. To create a unified application with the data provided by Workday, we need to link Job Requisitions with Candidates. Here, a candidate can be associated with multiple job requisitions and vice versa. Consequently, we can't use either of these IDs to identify a specific record.

## What Are Synthetic IDs?

To address this, we've introduced the concept of synthetic IDs. These IDs do not match an ID in the underlying provider, but allow you (and us) to identify the combined resources that were used to create this unified response. You can then use these IDs across our unified API. For example, you could use a `job_id` from a listing to search for candidates matching that value.

For simplicity, all IDs provided by the API will be synthetic IDs. These IDs are easy to identify because they are prefixed with `c28xIQ`. In most cases, you'll still be able to see the underlying ID from the provider in a field prefixed by `remote_`. For example, in the case of `job_id`, the underlying ID will be in `remote_job_id`.

## Using Synthetic and Regular IDs

When it comes to writing or fetching data, both types of IDs can be used interchangeably.

### Fetching Data

For reading, let's say we have the synthetic and regular IDs:

```jsx theme={null}
{
  job_id: 'c28xIQaWQ6MQ',
  remote_id: '1'
}

```

You can make either of these calls and expect the same response:

```bash theme={null}
# Using a regular ID
curl --request GET \
--url https://api.stackone.com/unified/ats/jobs/1 \
--header 'accept: application/json'

# Using a synthetic ID
curl --request GET \
--url https://api.stackone.com/unified/ats/jobs/c28xIQaWQ6MQ \
--header 'accept: application/json'

```

This applies to any query parameters as well:

```bash theme={null}
# Using a regular ID
curl --request GET \
     --url https://api.stackone.com/unified/ats/applications?raw=false&filter[job_id]=1&page_size=25 \
     --header 'accept: application/json'

# Using a synthetic ID
curl --request GET \
     --url https://api.stackone.com/unified/ats/applications?raw=false&filter[job_id]=c28xIQaWQ6MQ&page_size=25 \
     --header 'accept: application/json'

```

### Writing Data

When it comes to writing, the behavior is similar. You can use the ID field as usual and provide either a regular ID or a synthetic ID:


# Synthetic Identifiers
Source: https://docs.stackone.com/documents/common-guide/synthetic-identifiers

Learn about synthetic identifiers in the Documents API and how StackOne normalizes IDs across providers.

StackOne's Unified API generates unique synthetic identifiers for each resource to avoid any potential clashes that may have occurred through the process of unifying data from multiple sources. These are only used within the Unified API and are not found in the underlying provider systems.

* By default, all IDs are returned as synthetic identifiers.
* All synthetic identifiers are prefixed with `c28xIQ`.
* In most cases we also provide the "remote" id from the underlying provider, identified by the `remote_` prefix.
* Both synthetic and remote identifiers can be used interchangeably within the Unified API, the result will be the same.

<Note>
  It is strongly recommended to use the synthetic identifier for ease of use and consistency.
</Note>

Here's an example response showing both StackOne and remote identifiers:

```json theme={null}
{
    "id": "c28xIQ123ABC",               // StackOne identifier for current resource
    "remote_id": "E123456",             // Provider's original identifier
    "first_name": "John",
    "last_name": "Doe",
    "department_id": "c28xIQ789XYZ",    // StackOne identifier for department
    "remote_department_id": "D789"      // Provider's department identifier
}
```

For further information see [Guides - StackOne Identifiers](/guides/stackone-identifiers)


# Using Expand and Include Parameters
Source: https://docs.stackone.com/documents/common-guide/using-expand-and-include-api-parameters

Learn how to use expand and include parameters to retrieve related data in a single API request.

## Overview

While getting familiar with <Tooltip>Unified API</Tooltip>, you want to extend API functionality. StackOne API allows joining data from different objects into one combined response.

The StackOne implementation adds advanced <Tooltip>query parameters</Tooltip>, `include` or `expand`, to obtain the required information.

## Example scenario

Let's imagine an example:

1. You've acquired a [list of your available Accounts](/platform/api-reference/accounts/list-accounts) (account `id`)

2. Then you've retrieved a [list of employees](/hris/api-reference/employees/list-employees) for a specific `x-account-id` and selected one particular employee by specifying the resource`id` in the path

3. Next you want to [get all available information of that employee](/hris/api-reference/employees/get-employee)

At this point, you're getting basic info, such as name, gender, birthday, email, etc. However, you may be missing information documented in the API reference such as `avatar_url` or additional information about the `work_location` and `employment`. This is where the `include ` and `expand` parameters become handy.

## Including optional params

`include` and `expand` reserved keywords allow retrieving additional information about the employee. As an example, the usage of `include`=`avatar_url` and `expand`=`work_location` returns a link to the employee's avatar and details of work location.

**Include**

Include is meant to return additional fields not included by default for privacy or performance reasons. For example, the `avatar_url` field may require the hosting of the underlying image, which can slow down the response unnecessarily if you do not need it.

**Expand**

Expand, on the other hand, is used to expand objects (also called `models`) for which only the ID would otherwise be given and would therefore require a call to another resource to retrieve the underlying data (such as an employee's employment or work location details )

<Frame>
  <img alt="Expand and Include API Parameters" />
</Frame>

## Supported parameter-value mapping

The supported include and expand parameters are specific to the unified API endpoints. They can be seen within the individual endpoints in the API references (e.g., [List Employees](/hris/api-reference/employees/list-employees))


# Using Postman with StackOne API
Source: https://docs.stackone.com/documents/common-guide/using-postman

Learn how to use Postman to test and explore the StackOne API.

<Warning>
  **Prerequisites**

  Before testing with Postman, set up an integration and link an account following the [Getting Started](/guides/introduction) guide.
</Warning>

## Get the collection

The StackOne public Postman workspace has a pre-configured collection for the Unified APIs (HRIS, ATS, CRM, and more). Fork it into your own workspace to get started:

<a href="https://www.postman.com/stackonehq/stackone-public/collection/8d04033a-b6b1-4c91-8235-729f5c46123a">
  <img alt="Run in Postman" />
</a>

The collection has Basic Auth configured with `{{apiKey}}` as the username, and an `x-account-id` header set to `{{accountId}}`.

## Set up your environment

<Steps>
  <Step title="Create an environment">
    In Postman, click the **Environments** icon in the left sidebar, then **+** to create a new environment. Name it "StackOne" (or similar).
  </Step>

  <Step title="Add your credentials">
    Add these variables to the environment:

    | Variable    | Value                                                                                                        |
    | ----------- | ------------------------------------------------------------------------------------------------------------ |
    | `apiKey`    | Your StackOne API key — find it in the [dashboard](https://app.stackone.com) under **Settings → API Keys**   |
    | `accountId` | The linked account ID you want to target — visible in the [Accounts page](https://app.stackone.com/accounts) |
  </Step>

  <Step title="Select the environment">
    Select your environment from the dropdown in the top-right corner of Postman before sending any request.
  </Step>
</Steps>

## Make a request

With your environment active, open any request in the collection and click **Send**. The `{{apiKey}}` and `{{accountId}}` variables are resolved automatically from your environment.

<Tip>
  Start with **GET /accounts** to confirm your API key is working — it returns all linked accounts for your project.
</Tip>

## Troubleshooting

**`{"error":"Invalid authentication token"}`** — Your `apiKey` variable is missing or incorrect. Check that the right environment is selected and the value matches your key from the dashboard.


# Using the Passthrough Query Parameters
Source: https://docs.stackone.com/documents/common-guide/using-the-passthrough-query-parameters

Learn how to use passthrough query parameters to send custom parameters directly to the underlying provider.

Passthrough query parameters let you inject custom parameters directly into underlying provider APIs. This gives you access to provider-specific features without waiting for Unified API support.

## What is a Passthrough Query Parameter?

When invoking our unified API, you can provide query parameters to customize the API response. A passthrough query parameter is a special parameter that can be included in your API request, which will be directly passed on to the underlying provider API.

## How Does it Work?

The passthrough query mechanism uses a specific parameter pattern – the keyword "proxy" followed by brackets. If any parameter in this format is present in the API call, it will be extracted and passed as a query parameter to the underlying provider API.

**Pattern**: `proxy[custom-query-name]=custom-query-value`

* `custom-query-name`: The name of the custom query parameter.
* `custom-query-value`: The value assigned to the custom query parameter.

<Note>
  Note:

  More advanced filters are also supported: `proxy[filter[eq][age]]=25`.
</Note>

<Warning>
  Using the `proxy` passthrough parameter to set page-related parameter (eg: page limits, offsets, size etc.) may result in unexpected behaviour as it will override the values that StackOne sends with every provider request
</Warning>

## Example

Suppose you use the unified API to get all candidates for <Tooltip>ATS</Tooltip> category. This API already supports some optional filters, such as the `page_size` query parameter. If you know that one of the underlying providers supports a specific filter called `my-custom-filter`, you can use the passthrough query parameter to include this in your request, and it will be used when calling the provider API.

API Request: `https://api.stackone.com/unified/ats/candidates?proxy[my-custom-filter]=123`

With the above request, while the `page_size=20` parameter will be interpreted by our unified API, the `proxy[my-custom-filter]=123` will be extracted and passed directly to the underlying provider API as `my-custom-filter=123`.

<Frame>
  <img alt="Proxy Parameter Mechanism" />
</Frame>

Sorting candidates by the First Name for [TeamTailor API](https://docs.teamtailor.com/):

`https://api.stackone.com/unified/ats/candidates?page_size=20&proxy[sort]=first_name`

<Frame>
  <img alt="TeamTailor sort filter parameter" />
</Frame>

## Benefits

1. **Flexibility**: Developers can maximize the use of underlying provider APIs by tapping into specific features or filters that the unified API might not support directly.
2. **Future-Proofing**: As underlying provider APIs evolve and introduce new query parameters, developers can start using those without waiting for the unified API to offer built-in support.

## Caveats

Although it's great to have the flexibility to use all the filters that the underlying provider supports, you should consider the following caveats when using this functionality:

* These requests will not benefit from the unified vision, so a specific custom request with proxy parameters will not likely be supported between different providers;
* We often need to use some filters in the underlying requests to support the unified models. To keep the response data as unified as possible between different providers, if you passthrough query parameters that are already being used by default, the values that you pass will have less precedence and will not be overridden;
* The filters might be removed or deprecated by the underlying provider without the intervention of the StackOne team, which might break your custom use cases without notice.

## Conclusion

Passthrough query parameters give you direct access to provider-specific features and filters. Keep the tradeoffs in mind when using this mechanism.


# Error Codes and Troubleshooting
Source: https://docs.stackone.com/documents/error-codes-and-troubleshooting

Documents API error codes and troubleshooting guide

Encountering errors while interacting with APIs is a common occurrence. Although the StackOne Unified API will try to remediate issues automatically, it is important to understand what each error code signifies.

This guide lists the error codes you may encounter while using the Documents API, the possible reasons behind these errors, and steps for resolution.

***

<Snippet />

***

## Provider Errors

When the underlying provider API returns an error, the StackOne Unified API includes any data returned by the provider in the `provider_errors` array:

```json theme={null}
{
  "statusCode": 404,
  "message": "Resource not found",
  "provider_errors": [
    {
      "status": 404,
      "url": "/api/v1/files/250",
      "raw": { "error": "File with id 250 does not exist" }
    }
  ]
}
```

<Tip>
  Always check the `provider_errors` array for additional context from the upstream provider. This can help diagnose issues specific to the connected system.
</Tip>

***

## Getting Help

For any unresolved issues or further assistance, contact our support team via your dedicated Slack channel or at [support@stackone.com](mailto:support@stackone.com).

<CardGroup>
  <Card title="Status Page" icon="signal" href="https://status.stackone.com">
    Check system status and incidents
  </Card>

  <Card title="Request Tester" icon="flask" href="/documents/request-tester">
    Debug Documents requests directly in the dashboard
  </Card>

  <Card title="Request Logs" icon="scroll" href="/guides/request-logs">
    View detailed request history
  </Card>

  <Card title="Documents Integration Errors" icon="bug" href="/documents/integration-errors">
    Provider-specific Documents errors
  </Card>

  <Card title="AI Error Explainer" icon="robot" href="/guides/ai-features#error-explainer">
    Get AI-powered error resolution steps
  </Card>
</CardGroup>


# File Picker
Source: https://docs.stackone.com/documents/file-Picker



# StackOne File Picker

The **StackOne File Picker** provides a unified interface for browsing and selecting documents from third-party platforms. It abstracts provider-specific differences behind a consistent user experience and developer interface, whether the source is a **file storage system** (like SharePoint, OneDrive, Google Drive) or a **knowledge base** (like Confluence or Notion).

***

## How It Works

The File Picker allows users to:

* Navigate a hierarchical file tree (folders, pages, blocks)
* Select one or more files or documents
* Return a list of **StackOne file objects**, which can be used with unified operations such as `GET /unified/documents/files/{id}` or `POST /unified/documents/files/{id}/download`

***

## Picker Types

| Provider         | Picker Type | Navigation Model                 | Notes                                                             |
| ---------------- | ----------- | -------------------------------- | ----------------------------------------------------------------- |
| **SharePoint**   | Native      | Site → Drive → Folder → File     | Microsoft-native picker with StackOne-built **site selection UI** |
| **OneDrive**     | Native      | Drive → Folder → File            | Standard OneDrive picker scoped to user’s personal/business drive |
| **Google Drive** | Native      | Drive → Folder → File            | Uses Google Picker SDK                                            |
| **Confluence**   | Custom      | Space → Page                     | Pages act as both **folders and files** based on content/children |
| **Notion**       | Custom      | Workspace → Search → Page/Folder | Search-based navigation from the General Workspace level          |

***

## Output Format

When a user completes selection, the picker returns:

```json theme={null}
{
  "files": [
    {
      "id": "c28xIQaWQ6ODA5MzcyMg",
      "name": "QA text 1",
      "path": "https://exploreconfluence.atlassian.net/wiki/spaces/QS/pages/8093722/QA+text+1",
      "driveId": "7733268"
    }
  ]
}
```

Each `fileId` corresponds to a StackOne-normalized file object that can be accessed via API:

* `GET /unified/documents/files/{id}` – fetch file metadata
* `POST /unified/documents/files/{id}/download` – retrieve file contents (if supported)

## File Object Structure (for Fetch)

When queried individually, a file returns the following structure:

```json theme={null}
{
  "id": "file_123",
  "name": "Report Q1.pdf",
  "path": "/Marketing/Reports/Q1",
  "mimeType": "application/pdf",
  "size": 204800,
  "lastModified": "2024-12-01T10:00:00Z",
  "provider": "sharepoint",
  "downloadUrl": "https://..."
}
```

* For **knowledge bases** like Confluence and Notion:
  * Files may represent **pages or blocks**
  * Additional metadata like `hasContent`, `hasChildren` is provided

## Developer Integration Example

1. **Trigger the Picker**
   Use the StackOne SDK, embed directly via the UI component or trigger via the StackOne Dashboard.

2. **Receive Selection**
   The picker will return:

   ```json theme={null}
   {
     "files": [
       {
         "id": "c28xIQaWQ6ODA5MzcyMg",
         "name": "QA text 1",
         "path": "https://exploreconfluence.atlassian.net/wiki/spaces/QS/pages/8093722/QA+text+1",
         "driveId": "7733268"
       }
     ]
   }
   ```

3. **Perform Unified Actions**
   * Fetch metadata: `GET /unified/documents/files/{id}`
   * Download file: `POST /unified/documents/files/{id}/download`

***

## Provider Feature Table

| Feature / Capability     | SharePoint           | OneDrive             | Google Drive         | Confluence           | Notion               |
| ------------------------ | -------------------- | -------------------- | -------------------- | -------------------- | -------------------- |
| Picker Type              | Native               | Native               | Native               | Custom               | Custom               |
| Tree Navigation          | ✅                    | ✅                    | ✅                    | ✅                    | ✅                    |
| Multi-file Selection     | ✅                    | ✅                    | ✅                    | ✅                    | ✅                    |
| Selectable File Types    | Any document         | Any document         | Any document         | Pages                | Pages                |
| Folder Navigation        | ✅                    | ✅                    | ✅                    | ✅                    | ✅                    |
| Dual-role Items          | N/A                  | N/A                  | N/A                  | ✅ (pages)            | ✅ (pages/blocks)     |
| Output (on select)       | List of File objects | List of File objects | List of File objects | List of File objects | List of File objects |
| Unified Fetch / Download | ✅                    | ✅                    | ✅                    | ✅                    | ✅                    |

***

## Developer Integration

1. **Trigger the Picker**
   Use the StackOne SDK, embed directly via the UI component or trigger via the StackOne Dashboard.

2. **Receive Selection**
   The picker will return:

   ```json theme={null}
   {
     "files": [
       {
         "id": "c28xIQaWQ6ODA5MzcyMg",
         "name": "QA text 1",
         "path": "https://exploreconfluence.atlassian.net/wiki/spaces/QS/pages/8093722/QA+text+1",
         "driveId": "7733268"
       }
     ]
   }
   ```

3. **Perform Unified Actions**

   * Fetch metadata: `GET /unified/documents/files/{id}`
   * Download file: `POST /unified/documents/files/{id}/download`

***

## Auth & Permissions

* Each provider uses OAuth2 authentication via StackOne's integration flow
* File access scopes are handled per provider during auth

  * **SharePoint**: `Files.Read.All`, `Sites.Read.All`
  * **Google Drive**: `https://www.googleapis.com/auth/drive.readonly`
  * **Confluence/Notion**: Read access to spaces/pages/blocks

***

# StackOne File Picker SDK Documentation

The StackOne File Picker SDK enables you to integrate file selection from connected accounts into your application.

Below are the installation steps, usage examples, and API details.

<Frame>
  <img alt="" />
</Frame>

<Frame>
  <img alt="" />
</Frame>

## Installation

Install the SDK using one of the following package managers:

```bash theme={null}
# Using NPM
npm install --save @stackone/file-picker

# Using Yarn
yarn add @stackone/file-picker
```

## Connect Session Token

The File Picker requires creating a separate connect session token with the **Account ID** and **Provider Key** of a connected account.

# Usage

Below you can find the basic usage of the StackOne File Picker SDK using React:

```jsx theme={null}
import React, { useState, useEffect, useCallback } from 'react';
import { FilePicker } from '@stackone/file-picker';
import { StackOne } from "@stackone/stackone-client-ts";

const _stackOne = new StackOne({
  security: {
    password: "",
    username: "",
  },
});

export const FilePickerButton = () => {
  const [filePicker, setFilePicker] = useState(null);

  useEffect(() => {
    const initializePicker = async () => {
      const { sessionToken } = await _stackOne.connectSessions.createConnectSession({
        categories: [ConnectSessionCreateCategories.Documents],
        accountId: '{{Connected Account ID}}',
        provider: '{{Provider Key}}',
        ...
      });
      setFilePicker(new FilePicker({ sessionToken }));
    };

    initializePicker();
  }, []);

  const handleClick = useCallback(() => {
    filePicker?.open();
  }, [filePicker]);

  return (
    <button onClick={handleClick} disabled={!filePicker}>
      Open File Picker
    </button>
  );
};
```

# API Reference

#### File Picker Configuration Options

```javascript theme={null}
const filePicker = new FilePicker({
  sessionToken: 'your-session-token', // Required
  containerId: 'file-picker-container', // Optional: DOM container ID
  baseUrl: 'https://app.stackone.com', // Optional: API instance
  fields: ['name', 'path', 'driveId'], // Optional: which file fields to return
  showBranding: false, // Optional: show StackOne footer (default: true)
  folderSelectionEnabled: true, // Optional: allow folder selection (default: false)
  driveSelectionEnabled: true, // Optional: allow drive selection (default: false)

  // Callback Events
  onFilesPicked: (files) => {
    console.log('Selected files:', files);
    // Process selected files for indexing
  },
  onOpen: () => {
    console.log('File picker opened');
  },
  onClose: () => {
    console.log('File picker closed');
  },
  onCancel: () => {
    console.log('File selection canceled');
  },
  onError: (error) => {
    console.log('File picker error:', error);
  }
});
```

#### File Selection Response Format

When users complete their selection, the `onFilesPicked` callback receives different response formats depending on what was selected:

<Tabs>
  <Tab title="Files Only">
    ```javascript theme={null}
    // Example response when only files are selected
    {
      "files": [
        {
          "id": "c28xIQaWQ6ODA5MzcyMg", // Unified file ID
          "name": "Project Proposal.pdf", // File name
          "path": "/Projects/2024/Project Proposal.pdf", // File path
          "driveId": "7733268" // Drive identifier
        },
        {
          "id": "d39yJRbXR7PEB6NzY3Ng",
          "name": "Budget Analysis.xlsx",
          "path": "/Projects/2024/Budget Analysis.xlsx",
          "driveId": "7733268"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Files + Folders">
    ```javascript theme={null}
    // Example response when both files and folders are selected
    {
      "files": [
        {
          "id": "c28xIQaWQ6ODA5MzcyMg", // Individual file
          "name": "Project Proposal.pdf",
          "path": "/Projects/2024/Project Proposal.pdf",
          "driveId": "7733268"
        }
      ],
      "folders": [
        {
          "id": "f84mKLpQS8QFB7NzY4Mg", // Folder ID
          "name": "Marketing Materials",
          "path": "/Projects/2024/Marketing Materials",
          "driveId": "7733268"
        },
        {
          "id": "g95nLMqRT9RGC8NzY5Ng",
          "name": "Legal Documents",
          "path": "/Projects/2024/Legal Documents",
          "driveId": "7733268"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

<Note>
  **Folder Selection Handling**: When `folderSelectionEnabled: true` is set, users can select entire folders. The response will include folder IDs in the selection. To retrieve all files within selected folders (including nested subfolders), use the [List Files API](/documents/api-reference/files/list-files) with the `folder_id` parameter and `nested_files: true` option to automatically fetch all nested content.
</Note>

**Note**: Only `onFilesPicked` is typically required for document management use cases. Other callbacks (`onOpen`, `onClose`, `onCancel`, `onError`) are optional and depend on specific user actions or error conditions.

#### Picker Output Format

When users complete their selection, the picker returns different formats based on what was selected and configured:

<Tabs>
  <Tab title="Single File">
    ```json theme={null}
    {
      "files": [
        {
          "id": "c28xIQaWQ6ODA5MzcyMg",
          "name": "Project Proposal.pdf",
          "path": "/Projects/2024/Project Proposal.pdf",
          "driveId": "7733268",
          "mimeType": "application/pdf",
          "size": 2048000,
          "lastModified": "2024-01-15T10:30:00Z"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Multiple Files">
    ```json theme={null}
    {
      "files": [
        {
          "id": "c28xIQaWQ6ODA5MzcyMg",
          "name": "Project Proposal.pdf",
          "path": "/Projects/2024/Project Proposal.pdf",
          "driveId": "7733268",
          "mimeType": "application/pdf",
          "size": 2048000,
          "lastModified": "2024-01-15T10:30:00Z"
        },
        {
          "id": "d39yJRbXR7PEB6NzY3Ng",
          "name": "Budget Analysis.xlsx",
          "path": "/Projects/2024/Budget Analysis.xlsx",
          "driveId": "7733268",
          "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
          "size": 1024000,
          "lastModified": "2024-01-10T14:22:00Z"
        },
        {
          "id": "e40zKScYS8RFC7NzY4Og",
          "name": "Meeting Notes.docx",
          "path": "/Projects/2024/Meeting Notes.docx",
          "driveId": "7733268",
          "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
          "size": 512000,
          "lastModified": "2024-01-12T09:15:00Z"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Limited Fields">
    ```json theme={null}
    {
      "files": [
        {
          "id": "c28xIQaWQ6ODA5MzcyMg",
          "name": "Project Proposal.pdf",
          "driveId": "7733268"
        },
        {
          "id": "d39yJRbXR7PEB6NzY3Ng",
          "name": "Budget Analysis.xlsx",
          "driveId": "7733268"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Folders Selected">
    ```json theme={null}
    {
      "files": [
        {
          "id": "c28xIQaWQ6ODA5MzcyMg",
          "name": "Project Proposal.pdf",
          "path": "/Projects/2024/Project Proposal.pdf",
          "driveId": "7733268"
        }
      ],
      "folders": [
        {
          "id": "f84mKLpQS8QFB7NzY4Mg",
          "name": "Marketing Materials",
          "path": "/Projects/2024/Marketing Materials",
          "driveId": "7733268"
        },
        {
          "id": "g95nLMqRT9RGC8NzY5Ng",
          "name": "Legal Documents",
          "path": "/Projects/2024/Legal Documents",
          "driveId": "7733268"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Drives Selected">
    ```json theme={null}
    {
      "drives": [
        {
          "id": "7733268",
          "name": "Company SharePoint",
          "path": "/",
          "type": "sharepoint"
        },
        {
          "id": "8844379",
          "name": "Marketing Drive",
          "path": "/",
          "type": "googledrive"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

## FilePicker Methods

<ParamField type="method">
  Opens the file picker interface.
</ParamField>

<ParamField type="method">
  Closes the file picker interface.
</ParamField>

## Notion File Picker

StackOne's custom picker for Notion provides a unified interface for browsing and selecting Notion content.

### User Flow

1. **Land on Workspaces page** — The picker opens to a list of workspaces. The **General Workspace** represents the top-most level of the user's Notion workspace.
2. **Search for content** — Once inside the General Workspace, users search for a file or folder by name.
3. **Navigate and select** — Users can navigate into folders to select sub-files/folders, or pick the folder/file directly from search results.

### Characteristics

* **Files and Folders**: Only databases and pages are returned as files and folders
* **Dual-Role Pages**: A page can be both a file and folder depending on whether it has content or child pages/databases
* **Column List Traversal**: If a page has blocks which are column lists, we traverse these blocks to find child pages and databases and return these as direct children
* **Actual Location**: A file/folder will show in the actual location it resides in, not where it is linked in other files
* **Access Control**: The customer must grant access to each page/database they want to appear in the file picker by going to **Settings → Connections → Share with integration**

***


# Making Your First Request
Source: https://docs.stackone.com/documents/first-request

Make your first Documents API request to list files from a connected storage provider

This guide walks you through making your first API request to retrieve data from a linked account.

<Tip>
  **Prefer a no-code approach?** Use the [Request Tester](/guides/request-tester) in the dashboard to test API endpoints directly against linked accounts without writing any code.
</Tip>

## Prerequisites

1. [**API Key created in StackOne Dashboard**](/guides/api-keys) and copied to a secure location

2. [**Basic Authentication Setup**](/basic-authentication-with-stackone-api) - Learn how to properly authenticate with StackOne API using your API key

3. Required provider integration enabled

4. Account linked successfully

5. (Optional) Use an [SDK or Postman](/guides/stackone-api-sdks)

## Getting Account ID

<Note>
  **Authentication**: When using `curl -u "$API_KEY:"`, encoding is handled automatically. When setting the `Authorization` header manually, you must base64 encode your API key first. See the [Basic Authentication Guide](/basic-authentication-with-stackone-api) for details.
</Note>

1. List your linked accounts to find the account ID:

```bash theme={null}
curl --request GET \
     --url https://api.stackone.com/accounts \
     --header 'accept: application/json' \
     --header 'authorization: Basic {base64_encoded_api_key}'
```

2. From the response, copy the `id` value for your desired provider account.

<Tip>
  Filter by provider using the `providers` query parameter:

  ```bash theme={null}
  curl --request GET \
       --url 'https://api.stackone.com/accounts?providers={provider_name}' \
       --header 'accept: application/json' \
       --header 'authorization: Basic {base64_encoded_api_key}'
  ```
</Tip>

## Making Your First Request

Now you're ready to make your first Documents API call. Let's list the drives available in the connected storage provider:

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl --request GET \
      --url 'https://api.stackone.com/unified/documents/drives' \
      --header 'accept: application/json' \
      --header 'authorization: Basic {base64_encoded_api_key}' \
      --header 'x-account-id: {account_id}'
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { StackOne } from "@stackone/stackone-client-ts";

    const client = new StackOne({ apiKey: "YOUR_API_KEY" });

    const response = await client.documents.listDrives({
      xAccountId: "your-account-id"
    });

    console.log(response.drives);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from stackone_client import StackOne

    client = StackOne(api_key="YOUR_API_KEY")

    response = client.documents.list_drives(
        x_account_id="your-account-id"
    )

    print(response.drives)
    ```
  </Tab>
</Tabs>

### Example Response

```json theme={null}
{
  "data": [
    {
      "id": "drive_123",
      "remote_id": "abc123",
      "name": "My Drive",
      "description": "Personal storage",
      "url": "https://drive.google.com/drive/..."
    }
  ]
}
```

## Next Steps

<CardGroup>
  <Card title="List Files" icon="file" href="/documents/api-reference/files/list-files">
    Retrieve files from a specific folder or drive
  </Card>

  <Card title="File Picker" icon="hand-pointer" href="/documents/file-Picker">
    Let users select files with the embedded picker
  </Card>

  <Card title="Pagination" icon="arrow-right" href="/documents/common-guide/pagination">
    Handle large result sets efficiently
  </Card>

  <Card title="Webhooks" icon="bell" href="/guides/webhooks">
    Get notified when files change
  </Card>
</CardGroup>

## References

* [Basic Authentication with API Keys](/basic-authentication-with-stackone-api)
* [List Accounts](/platform/api-reference/accounts/list-accounts)
* [Libraries & SDKs](/guides/stackone-api-sdks)
* [Connector Profiles](https://app.stackone.com/connector_profiles)


# Unified Documents API
Source: https://docs.stackone.com/documents/introduction

Unified Documents API for file and knowledge management across platforms, with consistent data models for drives, folders, and documents.

## What is a Unified API?

A **unified API** provides a single, standardized interface to interact with multiple third-party providers. Instead of learning each provider's unique API format, authentication scheme, and data model, you write code once, and StackOne handles the differences.

**What StackOne normalizes:**

* **Data models** – Consistent field names and structures across providers (e.g., `files` in Google Drive, SharePoint, and Dropbox all return the same schema; `users` in Google Workspace, Okta, and 1Password all return the same schema)
* **Authentication** – OAuth, API keys, and tokens are managed per-provider; you just pass an `x-account-id` header
* **Pagination** – Cursor-based pagination works the same regardless of whether the provider uses offsets, pages, or cursors
* **Error formats** – Standardized error responses with provider-specific details when available

<Tip>
  **Building AI agents?** Use the [MCP Server](/mcp/quickstart), an [AI Toolset SDK](/agents/typescript/introduction), or the [Actions API (RPC)](/platform/api-reference/actions/make-an-rpc-call-to-an-action) instead — same data, optimized for LLM tool calling.
</Tip>

<Frame>
  <img alt="StackOne Documents API Interface" />
</Frame>

## Benefits of the Documents API

<AccordionGroup>
  <Accordion title="Real-Time File & Folder Sync">
    Built for easily syncing files, in real-time from multiple providers. Use the api to access nested folders & files data in a simple and unified way, regardless of the underlying provider.
  </Accordion>

  <Accordion title="Unified File Picker">
    One File Picker SDK that lets your users pick files from multiple providers, with a single call to the SDK and get back picked files & folders the same way regardless of the provider.
  </Accordion>

  <Accordion title="Real-Time Data Synchronization">
    StackOne's APIs support real-time synchronization, ensuring that content changes are reflected immediately across connected platforms.
  </Accordion>

  <Accordion title="Privacy-First Design Ensuring Compliance">
    With a [focus on security](https://www.stackone.com/blog/why-your-choice-of-unified-api-could-make-or-break-compliance), StackOne ensures secure content storage and maintains compliance with data protection regulations.
  </Accordion>

  <Accordion title="Synthetic and Native Webhooks for Updates">
    The platform provides both [synthetic and native webhooks](/guides/webhooks), delivering real-time notifications for changes in drives, folders, and files.
  </Accordion>

  <Accordion title="Comprehensive File Management and Knowledge Base Integration Coverage">
    StackOne offers [pre-built connectors](https://www.stackone.com/integrations) with leading File Management platforms, simplifying the integration process.
  </Accordion>
</AccordionGroup>

## StackOne SDKs & OpenAPI Specification

<p>Use our official SDKs for faster integration. Build with language-native libraries. Full list [here](/guides/stackone-api-sdks).</p>

<CardGroup>
  <Card title="OpenAPI Specification" icon="link" href="https://api.eu1.stackone.com/oas/documents.json" />

  <Card title="Popular SDKs" icon="download">
    [Node.js](https://www.npmjs.com/package/@stackone/stackone-client-ts)
    [Java (JVM)](https://mvnrepository.com/artifact/com.stackone/stackone-client-java)
    [PHP](https://packagist.org/packages/stackone/client-sdk)
    [Ruby](https://rubygems.org/gems/stackone_client)
  </Card>
</CardGroup>

## Entity Model

The Documents API is built around three entities: drives, folders, and files.

```mermaid theme={null}
erDiagram
    Drive ||--o{ Folder : "contains"
    Drive ||--o{ File : "contains"
    Folder ||--o{ File : "contains"
    Folder ||--o{ Folder : "contains"

    Drive {
        string id
        string remote_id
        string name
        string description
        string url
        datetime created_at
        datetime updated_at
    }

    Folder {
        string id
        string remote_id
        string name
        string description
        string url
        string path
        string owner_id
        string parent_folder_id
        string drive_id
        datetime created_at
        datetime updated_at
    }

    File {
        string id
        string remote_id
        string name
        string description
        string url
        string file_format
        string path
        string owner_id
        string folder_id
        string drive_id
        number size
        array export_formats
        string default_download_format
        datetime created_at
        datetime updated_at
    }
```

| Entity     | Description                                                                                                                                                                                         |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Drive**  | The top-level container — a storage volume, shared drive, or knowledge base space. Each drive can contain folders and files directly.                                                               |
| **Folder** | A named container within a drive. Folders can nest inside other folders and track their parent (`parent_folder_id`) and owning drive (`drive_id`).                                                  |
| **File**   | A document or content item. Files carry metadata about format (`file_format`), available export types (`export_formats`), and the default format used when downloading (`default_download_format`). |

<Note>
  Field availability varies by integration provider. Optional fields may be `null` if the provider's API does not expose them. See your connector's integration guide for coverage details.
</Note>

### File formats

The `file_format` field uses a normalized enum across providers. Common values include `pdf`, `docx`, `xlsx`, `pptx`, `html`, `csv`, `png`, `jpg`, and `unknown`. The `export_formats` array lists the MIME types available when downloading a file, and `default_download_format` is the format used when no export format is specified.


# Request Tester
Source: https://docs.stackone.com/documents/request-tester

Test Documents API requests directly against linked accounts to verify connectivity and debug issues.

The Request Tester lets you execute HTTP requests against any linked account directly from the dashboard. Use it to verify connections, test specific endpoints, and troubleshoot integration issues.

<Note>
  **Unified API Testing**: The Request Tester is the recommended way to test Documents API endpoints against specific accounts. It provides direct access to the API without requiring code or external tools.
</Note>

## Accessing the Request Tester

<Steps>
  <Step title="Navigate to Accounts">
    Go to [Accounts](https://app.stackone.com/accounts) in the StackOne dashboard.
  </Step>

  <Step title="Find your account">
    Locate the linked account you want to test.
  </Step>

  <Step title="Open Request Tester">
    Click the ellipsis menu (⋯) on the account row and select **Request Tester**.
  </Step>
</Steps>

<Tip>
  You can also access the Request Tester from the account detail page by clicking the **Test Request** button.
</Tip>

## Using the Request Tester

### Select an Endpoint

Choose from available Documents endpoints:

| Category      | Example Endpoints                                                      |
| ------------- | ---------------------------------------------------------------------- |
| **Documents** | List Files, Get File, List Folders, Get Folder, List Drives, Get Drive |

### Configure Parameters

Depending on the endpoint, you can configure:

* **Path parameters** – Required IDs like `file_id` or `folder_id`
* **Query parameters** – Pagination, filtering, and expansion options
* **Request body** – For POST/PUT/PATCH requests

<AccordionGroup>
  <Accordion title="Common query parameters">
    | Parameter       | Description                                             |
    | --------------- | ------------------------------------------------------- |
    | `page_size`     | Number of results per page (default varies by endpoint) |
    | `next`          | Pagination cursor for fetching next page                |
    | `updated_after` | Filter by modification date                             |
    | `expand`        | Include related resources in response                   |
  </Accordion>

  <Accordion title="Using the expand parameter">
    Some endpoints support expanding related data. For example, when listing files you might expand related folder or drive information to include those details inline.

    See [Using Expand and Include Parameters](/guides/using-expand-and-include-api-parameters) for details.
  </Accordion>
</AccordionGroup>

### Execute and Inspect

Click **Send Request** to execute. The response panel shows:

* **Status code** – HTTP status (200, 400, 404, etc.)
* **Response body** – JSON data returned by the API
* **Response headers** – Including rate limit information
* **Timing** – Request duration

## Troubleshooting with Request Tester

The Request Tester is particularly useful for debugging:

<AccordionGroup>
  <Accordion title="Connection issues">
    If an account shows an error status, use the Request Tester to execute a simple request (like listing files). The response will reveal:

    * Authentication failures (401/403)
    * Token expiration
    * Permission issues
    * Provider API errors
  </Accordion>

  <Accordion title="Missing data">
    When expected data isn't appearing:

    1. Test the specific endpoint directly
    2. Check if the data exists in the source system
    3. Review field mappings in the response
    4. Verify scopes/permissions in the integration configuration
  </Accordion>

  <Accordion title="Pagination problems">
    To debug pagination:

    1. Make an initial request with a small `page_size`
    2. Copy the `next` cursor from the response
    3. Make a follow-up request with that cursor
    4. Verify data continuity between pages
  </Accordion>

  <Accordion title="Slow responses">
    If requests are slow:

    * Check the response timing in the panel
    * Try smaller `page_size` values
    * Review [Request Logs](/guides/request-logs) for detailed timing breakdown
  </Accordion>
</AccordionGroup>

## Request Tester vs AI Playground

| Feature              | Request Tester          | AI Playground                |
| -------------------- | ----------------------- | ---------------------------- |
| **Purpose**          | Direct API testing      | Natural language exploration |
| **Best for**         | Debugging, verification | Discovery, prototyping       |
| **Input**            | Structured parameters   | Natural language prompts     |
| **Output**           | Raw API response        | AI-interpreted results       |
| **Unified APIs**     | **Recommended**         | Supported                    |
| **Provider actions** | Supported               | Supported                    |

<Tip>
  Use the **Request Tester** when you need precise control over parameters and want to see exact API responses. Use the **AI Playground** when exploring capabilities or testing complex multi-step workflows.
</Tip>

## Related

<CardGroup>
  <Card title="Accounts" icon="users" href="/guides/accounts-section">
    Manage linked accounts
  </Card>

  <Card title="Request Logs" icon="scroll" href="/guides/request-logs">
    View detailed request history
  </Card>

  <Card title="Error Codes" icon="triangle-exclamation" href="/guides/unified-api-error-codes-and-troubleshooting-guide">
    Understand error responses
  </Card>

  <Card title="AI Playground" icon="message" href="/guides/playground">
    Test with natural language
  </Card>
</CardGroup>


# Testing the File Picker
Source: https://docs.stackone.com/documents/testing-the-file-picker

How to test the File Picker and troubleshoot common issues

## Testing the File Picker

You can test the File Picker directly in the StackOne dashboard to verify it's working correctly with your connected accounts.

### Accessing the File Picker Test

1. Navigate to [Accounts](https://app.stackone.com/accounts) in the StackOne dashboard
2. Find the linked account you want to test
3. Click the ellipsis menu (⋯) on the account row
4. Select **Test File Picker** (or similar option)

This opens the File Picker interface for that account, allowing you to:

* Verify the picker loads correctly
* Test navigation through folders/drives
* Confirm file selection works
* Check that selected files return the expected format

***

## Common Issues

<AccordionGroup>
  <Accordion title="File Picker won't open">
    **Possible causes:**

    * Invalid or expired session token
    * Missing or incorrect account ID
    * Provider not properly connected
    * OAuth redirect URI misconfiguration

    **Solutions:**

    1. Verify the account is connected and shows a healthy status
    2. Check that the connect session token was created with the correct `accountId` and `provider` parameters
    3. Ensure OAuth redirect URIs are properly configured (see [OAuth Proxy Redirect](/integration-guides/oauth-proxy-redirect))
    4. Check browser console for error messages
  </Accordion>

  <Accordion title="No files or folders visible">
    **Possible causes:**

    * Insufficient permissions/scopes
    * Account authentication expired
    * Provider-specific access restrictions

    **Solutions:**

    1. Verify OAuth scopes are correctly configured:
       * **SharePoint**: `Files.Read.All`, `Sites.Read.All`
       * **Google Drive**: `https://www.googleapis.com/auth/drive.readonly`
       * **Confluence/Notion**: Read access to spaces/pages/blocks
    2. Re-authenticate the account if tokens have expired
    3. For Notion: Ensure pages/databases are shared with the integration (Settings → Connections → Share with integration)
    4. Check account status in the dashboard
  </Accordion>

  <Accordion title="Picker shows wrong files or structure">
    **Possible causes:**

    * Provider-specific navigation differences
    * Custom picker behavior for knowledge bases (Confluence/Notion)

    **Solutions:**

    1. Review provider-specific picker behavior:
       * **Confluence/Notion**: Pages can act as both files and folders
       * **SharePoint**: Requires site selection before drive/folder navigation
    2. Check the [File Picker documentation](/documents/file-Picker) for provider-specific notes
    3. Verify you're testing with the correct provider type
  </Accordion>

  <Accordion title="Selected files return incorrect IDs">
    **Possible causes:**

    * Using provider-specific IDs instead of StackOne unified IDs
    * Incorrect field selection in configuration

    **Solutions:**

    1. Ensure you're using the `id` field from the picker response (this is the StackOne unified ID)
    2. Use the unified ID with StackOne API endpoints: `GET /unified/documents/files/{id}`
    3. Don't use provider-specific IDs directly with StackOne APIs
    4. Check the [File Picker output format](/documents/file-Picker#developer-integration) documentation
  </Accordion>

  <Accordion title="OAuth redirect errors">
    **Possible causes:**

    * Redirect URI not configured in provider OAuth app
    * Redirect URI mismatch between configuration and actual URL
    * Missing redirect URI for File Picker (required for Google Drive, SharePoint, OneDrive)

    **Solutions:**

    1. For Google Drive: Add File Picker redirect URI to your OAuth app configuration
    2. For SharePoint/OneDrive: Ensure redirect URI includes File Picker support
    3. See [OAuth Proxy Redirect](/integration-guides/oauth-proxy-redirect) for detailed setup
    4. Verify redirect URIs match exactly (including protocol, domain, and path)
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup>
  <Card title="File Picker Guide" icon="hand-pointer" href="/documents/file-Picker">
    Complete File Picker documentation
  </Card>

  <Card title="Integration Errors" icon="triangle-exclamation" href="/documents/integration-errors">
    Documents API error codes
  </Card>

  <Card title="OAuth Setup" icon="key" href="/integration-guides/oauth-proxy-redirect">
    OAuth redirect configuration
  </Card>

  <Card title="Request Tester" icon="flask" href="/documents/request-tester">
    Test Documents API endpoints
  </Card>
</CardGroup>


# Context-aware Agent
Source: https://docs.stackone.com/documents/use-cases/context-aware-agent

How to use the StackOne Documents API and File Picker to create a Document-Aware AI Assistant with access to files and folders from users' documents (picked from cloud storages or knowledge bases).

<Frame>
  <img alt="StackOne Documents API Interface" />
</Frame>

## Overview

**AI agents** are more effective when they can access each user's **specific documents and knowledge bases**. Keeping these documents updated is challenging, but the **StackOne Documents API** makes it easy to access and sync user files for your agent.

<Info>
  **API Reference**: See available operations in the [`documents/api-reference/`](/documents/api-reference).

  Every API endpoint can be provided as a tool within an agent through StackOne's **AI Library** ([nodejs](https://github.com/StackOneHQ/stackone-ai-node), [python](https://github.com/StackOneHQ/stackone-ai-python))
</Info>

This use case demonstrates how to:

* Enable users to select relevant documents from their connected storage (**SharePoint, Google Drive, Notion**, etc.)
* **Index and process** selected documents for AI agent context
* Implement **real-time document synchronization** with webhooks
* Build **low-latency search and retrieval** for agent responses
* Combine **RAG'd document data** with **real-time tool calling**

## Step-by-Step Guide

### Prerequisites

Before implementing this use case, ensure you have:

* **Enabled document integrations** in your StackOne project for the providers you want to support (SharePoint, Google Drive, Confluence, etc.)
* Reviewed the [integration setup guides](/integration-guides/documents/overview) for provider-specific configuration requirements

<Warning>
  Some document providers require additional OAuth application setup beyond the standard StackOne integration configuration. This may include creating custom OAuth apps with specific providers to enable full functionality and avoid rate limits. See the [integration guides overview](/integration-guides/documents/overview) for detailed provider-specific requirements.
</Warning>

***

1. **Set Up Webhook Endpoints**

   Configure webhooks in your StackOne dashboard to receive `account.created` and `documents_files.updated` events.

   API Reference: [Webhooks Guide](/guides/webhooks)

<Accordion title="Webhook Integration Details">
  ### Webhook Integration

  StackOne provides webhook events to keep your AI agent's knowledge base synchronized with changes in connected providers:

  #### Key Webhook Events

  * **`account.created`** - Triggered when users successfully authenticate new document accounts
  * **`documents_files.updated`** - Fired when files are modified, moved, or have metadata changes
  * **`documents_files.deleted`** - Notifies when files are removed or access is revoked

  #### Setting Up Webhooks

  <Note>
    Configure webhooks in your StackOne dashboard to receive real-time notifications about document changes. See the [Webhooks Guide](/guides/webhooks) for detailed setup instructions.
  </Note>

  ### Content Refresh Strategies

  | **Strategy**       | **When to Use**                           | **Implementation**                                        |
  | ------------------ | ----------------------------------------- | --------------------------------------------------------- |
  | **Scheduled Sync** | Batch processing, tolerance for delays    | Cron jobs that re-index files periodically (hourly/daily) |
  | **Webhook-Driven** | Real-time requirements, immediate updates | React to `documents_files.updated` events                 |
  | **Manual Sync**    | User-controlled updates, debugging        | Admin dashboard triggers for specific accounts/files      |
</Accordion>

2. **Generate Connect Session Token**

   Use the [Create Connect Session](/platform/api-reference/connect-sessions/create-connect-session) API with `multiple: true` for per-user account linking.

   Additional API: [List Accounts](/platform/api-reference/accounts/list-accounts) to retrieve connected document provider accounts

3. **Embed Integration Hub**

   Install and configure StackOne React Hub for OAuth flows.

   API Reference: [Embedding StackOne Hub](/guides/embedding-stackone-hub)

4. **Implement File Picker**

   Deploy StackOne File Picker for folder/file selection.

   API Reference: [File Picker Guide](/documents/file-Picker)

<Accordion title="Picker Implementation Details">
  ### File Picker Integration

  The StackOne File Picker provides a unified interface for document selection across providers. Based on the [StackOne File Picker repository](https://github.com/StackOneHQ/file-picker), here are the available callback events and configuration options:

  #### File Picker Configuration Options

  ```javascript theme={null}
  const filePicker = new FilePicker({
    sessionToken: 'your-session-token', // Required
    containerId: 'file-picker-container', // Optional: DOM container ID
    baseUrl: 'https://app.stackone.com', // Optional: API instance
    fields: ['name', 'path', 'driveId'], // Optional: which file fields to return
    showBranding: false, // Optional: show StackOne footer (default: true)
    folderSelectionEnabled: true, // Optional: allow folder selection (default: false)
    driveSelectionEnabled: true, // Optional: allow drive selection (default: false)

    // Callback Events
    onFilesPicked: (files) => {
      console.log('Selected files:', files);
      // Process selected files for indexing
    },
    onOpen: () => {
      console.log('File picker opened');
    },
    onClose: () => {
      console.log('File picker closed');
    },
    onCancel: () => {
      console.log('File selection canceled');
    },
    onError: (error) => {
      console.log('File picker error:', error);
    }
  });
  ```

  #### File Selection Response Format

  When users complete their selection, the `onFilesPicked` callback receives different response formats depending on what was selected:

  <Tabs>
    <Tab title="Files Only">
      ```javascript theme={null}
      // Example response when only files are selected
      {
        "files": [
          {
            "id": "c28xIQaWQ6ODA5MzcyMg", // Unified file ID
            "name": "Project Proposal.pdf", // File name
            "path": "/Projects/2024/Project Proposal.pdf", // File path
            "driveId": "7733268" // Drive identifier
          },
          {
            "id": "d39yJRbXR7PEB6NzY3Ng",
            "name": "Budget Analysis.xlsx",
            "path": "/Projects/2024/Budget Analysis.xlsx",
            "driveId": "7733268"
          }
        ]
      }
      ```
    </Tab>

    <Tab title="Files + Folders">
      ```javascript theme={null}
      // Example response when both files and folders are selected
      {
        "files": [
          {
            "id": "c28xIQaWQ6ODA5MzcyMg", // Individual file
            "name": "Project Proposal.pdf",
            "path": "/Projects/2024/Project Proposal.pdf",
            "driveId": "7733268"
          }
        ],
        "folders": [
          {
            "id": "f84mKLpQS8QFB7NzY4Mg", // Folder ID
            "name": "Marketing Materials",
            "path": "/Projects/2024/Marketing Materials",
            "driveId": "7733268"
          },
          {
            "id": "g95nLMqRT9RGC8NzY5Ng",
            "name": "Legal Documents",
            "path": "/Projects/2024/Legal Documents",
            "driveId": "7733268"
          }
        ]
      }
      ```
    </Tab>
  </Tabs>

  <Note>
    **Folder Selection Handling**: When `folderSelectionEnabled: true` is set, users can select entire folders. The response will include folder IDs in the selection. To retrieve all files within selected folders (including nested subfolders), use the [List Files API](/documents/api-reference/files/list-files) with the `folder_id` parameter and `nested_files: true` option to automatically fetch all nested content.
  </Note>

  **Note**: Only `onFilesPicked` is typically required for document management use cases. Other callbacks (`onOpen`, `onClose`, `onCancel`, `onError`) are optional and depend on specific user actions or error conditions.

  #### Key Providers Supported

  <Warning>
    **OAuth Application Setup Required**: Some providers may require creating OAuth applications and configuring credentials. See the [Documents Integration Guides](/integration-guides/documents/overview) for provider-specific setup instructions, including [Google Drive](/integration-guides/documents/googledrive-partner-oauth), [SharePoint](/integration-guides/documents/sharepoint-oauth), and [OneDrive](/integration-guides/documents/onedrive-oauth) OAuth configurations.
  </Warning>

  | Provider         | Picker Type | Navigation                   | Multi-Select | File Types      |
  | ---------------- | ----------- | ---------------------------- | ------------ | --------------- |
  | **SharePoint**   | Native      | Site → Drive → Folder → File | ✅            | All documents   |
  | **OneDrive**     | Native      | Drive → Folder → File        | ✅            | All documents   |
  | **Google Drive** | Native      | Drive → Folder → File        | ✅            | All documents   |
  | **Confluence**   | Custom      | Space → Page                 | ✅            | Pages/Documents |
  | **Notion**       | Custom      | Workspace → Page             | ✅            | Pages/Blocks    |

  For other providers, you can check support in the [StackOne's integration page](https://www.stackone.com/integrations) or your Dashboard's [field coverage page](https://app.stackone.com/field_coverage) or request a new integration via our in-app, slack or email support.

  #### Picker Output Format

  When users complete their selection, the picker returns different formats based on what was selected and configured:

  <Tabs>
    <Tab title="Single File">
      ```json theme={null}
      {
        "files": [
          {
            "id": "c28xIQaWQ6ODA5MzcyMg",
            "name": "Project Proposal.pdf",
            "path": "/Projects/2024/Project Proposal.pdf",
            "driveId": "7733268",
            "mimeType": "application/pdf",
            "size": 2048000,
            "lastModified": "2024-01-15T10:30:00Z"
          }
        ]
      }
      ```
    </Tab>

    <Tab title="Multiple Files">
      ```json theme={null}
      {
        "files": [
          {
            "id": "c28xIQaWQ6ODA5MzcyMg",
            "name": "Project Proposal.pdf",
            "path": "/Projects/2024/Project Proposal.pdf",
            "driveId": "7733268",
            "mimeType": "application/pdf",
            "size": 2048000,
            "lastModified": "2024-01-15T10:30:00Z"
          },
          {
            "id": "d39yJRbXR7PEB6NzY3Ng",
            "name": "Budget Analysis.xlsx",
            "path": "/Projects/2024/Budget Analysis.xlsx",
            "driveId": "7733268",
            "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
            "size": 1024000,
            "lastModified": "2024-01-10T14:22:00Z"
          },
          {
            "id": "e40zKScYS8RFC7NzY4Og",
            "name": "Meeting Notes.docx",
            "path": "/Projects/2024/Meeting Notes.docx",
            "driveId": "7733268",
            "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
            "size": 512000,
            "lastModified": "2024-01-12T09:15:00Z"
          }
        ]
      }
      ```
    </Tab>

    <Tab title="Limited Fields">
      ```json theme={null}
      {
        "files": [
          {
            "id": "c28xIQaWQ6ODA5MzcyMg",
            "name": "Project Proposal.pdf",
            "driveId": "7733268"
          },
          {
            "id": "d39yJRbXR7PEB6NzY3Ng",
            "name": "Budget Analysis.xlsx",
            "driveId": "7733268"
          }
        ]
      }
      ```
    </Tab>

    <Tab title="Folders Selected">
      ```json theme={null}
      {
        "files": [
          {
            "id": "c28xIQaWQ6ODA5MzcyMg",
            "name": "Project Proposal.pdf",
            "path": "/Projects/2024/Project Proposal.pdf",
            "driveId": "7733268"
          }
        ],
        "folders": [
          {
            "id": "f84mKLpQS8QFB7NzY4Mg",
            "name": "Marketing Materials",
            "path": "/Projects/2024/Marketing Materials",
            "driveId": "7733268"
          },
          {
            "id": "g95nLMqRT9RGC8NzY5Ng",
            "name": "Legal Documents",
            "path": "/Projects/2024/Legal Documents",
            "driveId": "7733268"
          }
        ]
      }
      ```
    </Tab>

    <Tab title="Drives Selected">
      ```json theme={null}
      {
        "drives": [
          {
            "id": "7733268",
            "name": "Company SharePoint",
            "path": "/",
            "type": "sharepoint"
          },
          {
            "id": "8844379",
            "name": "Marketing Drive",
            "path": "/",
            "type": "googledrive"
          }
        ]
      }
      ```
    </Tab>
  </Tabs>
</Accordion>

5. **Index Selected Content**

   Use [Download File](/documents/api-reference/files/download-file) and [Get File](/documents/api-reference/files/get-file) to retrieve file content and metadata. Store content in your data store (vector database, search index, etc.).

   Additional APIs: [List Files](/documents/api-reference/files/list-files), [List Folders](/documents/api-reference/folders/list-folders), [List Drives](/documents/api-reference/drives/list-drives)

6. **Maintain Content Freshness**

   Implement one or more strategies to keep your agent's knowledge base current. These approaches are not mutually exclusive and can be combined:

   | **Strategy**       | **When to Use**                           | **Implementation**                                                      |
   | ------------------ | ----------------------------------------- | ----------------------------------------------------------------------- |
   | **Scheduled Sync** | Batch processing, tolerance for delays    | Cron jobs that re-index files periodically using stored file/folder IDs |
   | **Webhook-Driven** | Real-time requirements, immediate updates | React to `documents_files.updated` events for instant synchronization   |
   | **Manual Sync**    | User-controlled updates, debugging        | Admin dashboard triggers for specific accounts/files                    |

   API Endpoints: Use [Get File](/documents/api-reference/files/get-file) and [Download File](/documents/api-reference/files/download-file) when `documents_files.updated` webhooks are received

   Optional: [Upload File](/documents/api-reference/files/upload-file) for agent-generated content

***

## API Operations & Dataflow

```mermaid theme={null}
sequenceDiagram
    participant User
    participant WebApp as Your Web App
    participant Hub as StackOne Hub&Picker
    participant Backend as Your Backend
    participant StackOneAPI as StackOne API

    %% ========== SECTION 1: SESSION INITIALIZATION ==========
    rect rgb(230, 245, 255)
        note over WebApp, StackOneAPI: 1. Initialize Session
        WebApp->>Backend: Create session
        Backend->>StackOneAPI: POST /connect_sessions
        StackOneAPI-->>Backend: { token }
        Backend-->>WebApp: { token }
    end

    %% ========== SECTION 2: ACCOUNT LINKING ==========
    rect rgb(230, 255, 236)
        note over User, StackOneAPI: 2. Account Linking
        WebApp->>Hub: startConnect(token)
        User->>Hub: Auth provider
        Hub-->>StackOneAPI: Store creds
        StackOneAPI-->>Backend: account.created webhook
        Backend-->>Backend: persist account_id
        Hub-->>WebApp: onSuccess callback
    end

    %% ========== SECTION 3: FILE SELECTION ==========
    rect rgb(255, 245, 230)
        note over User, Hub: 3. File Selection
        User->>WebApp: Pick files
        WebApp->>Hub: open(token, account_id)
        User->>Hub: Select files/folders
        Hub-->>WebApp: Selection callback
        WebApp->>Backend: Store selected IDs
    end

    %% ========== SECTION 4: Initial indexing ==========
    rect rgb(240, 230, 255)
        note over Backend, StackOneAPI: 4. Index Content
        Backend->>Backend: Get picked files
        loop For each file
            Backend->>StackOneAPI: GET /files/{id}
            Backend->>StackOneAPI: Download content
            Backend->>Backend: Index file
        end
    end

    %% ========== SECTION 5: Content Refresh ==========
    rect rgb(230, 255, 236)
        note over Backend, StackOneAPI: 5. Sync Updates
        alt Scheduled sync
            loop Periodic
                Backend->>Backend: Get file IDs
                loop For each file
                    Backend->>StackOneAPI: GET /files/{id}
                    Backend->>StackOneAPI: Download updates
                    Backend->>Backend: Re-index
                end
            end

        else Webhook updates
            StackOneAPI->>Backend: files.updated webhook
            Backend->>Backend: Check if tracked
            Backend->>StackOneAPI: GET /files/{id}
            Backend->>StackOneAPI: Download content
            Backend->>Backend: Re-index
        end
    end

    %% ========== SECTION 6: Agent Use ==========
    rect rgb(255, 245, 230)
        note over User, Backend: 6. AI Response
        User->>Backend: Query agent
        Backend->>Backend: Search indexed data
        Backend->>StackOneAPI: Real-time API calls
        Backend->>User: Context-aware response
    end
```

***

## Additional Use Cases You Can Build with this API

* **Just-in-time file attachment to an AI chatbot**: Add the ability for your users to attach files from SharePoint, Google Drive and more to a conversation, ChatGPT style
* **One-click attachments** to CRM/tickets/training
* **Policy/compliance sync** across approved sources
* **Unified knowledge base** across SharePoint, Confluence, Notion, etc.

***

## Troubleshooting

### Common Issues

| Issue                     | Symptoms                                  | Solution                                                         |
| ------------------------- | ----------------------------------------- | ---------------------------------------------------------------- |
| **Authentication Errors** | 401 Unauthorized responses                | Refresh OAuth tokens through StackOne Connect                    |
| **File Access Denied**    | 403 Forbidden when accessing files        | Verify user permissions in source provider                       |
| **Slow File Listings**    | Timeout errors when listing large folders | Implement pagination and chunked requests                        |
| **Upload Failures**       | Files not appearing after upload          | Check provider-specific upload limits and file type restrictions |

### Support Resources

For persistent issues or advanced integration support:

* Review the [StackOne Error Codes Guide](/guides/unified-api-error-codes-and-troubleshooting-guide)
* Contact StackOne support through the dashboard
* Consult provider-specific documentation for detailed error codes


# Accounts
Source: https://docs.stackone.com/guides/accounts-section

Link new accounts, edit existing ones, and monitor their status - all in one place.

<Note>
  **Linked Account definition**

  An Account represents an end-user's connection with a third-party system.
</Note>

[The Accounts section](https://app.stackone.com/accounts) of the StackOne dashboard allows you to view, link, and manage all the accounts connected by end-users (or yourself, in the case of sandbox accounts).

<Frame>
  <img alt="StackOne Accounts page showing linked accounts for BambooHR, Ashby, Workday, and other integrations" />
</Frame>

* See an exhaustive list of every account linked by end-users.
* Test the connection with an Account by executing requests and viewing results. The request testing interface helps verify that a connection is working as expected and can assist in debugging issues flagged by an end-user.
* Easily access and copy the Account's ID.
* Edit and re-connect an end-user's linked Accounts on their behalf.
* View and manage additional information about each Account.

***

### Accounts Table

The Accounts Table has the following columns:

| Column        | Description                                                 |
| ------------- | ----------------------------------------------------------- |
| **Account**   | The name of the Linked Account                              |
| **Connector** | The name of the connector                                   |
| **Type**      | Indicates whether the Account is **Production** or **Test** |
| **Config**    | The name of the Connector Profile used                      |
| **Status**    | The current status: **Active**, **Suspended**, or **Error** |
| **Connected** | The date when the Account was first connected               |

Each Account row also includes an **ellipses menu (⋯)** with the following actions:

* **[Actions Request Tester](#testing-actions)** – Opens the HTTP Request Tester for testing connector actions.
* **Use in Playground** – Loads the Account in the AI Playground for natural language testing.
* **View Logs** – Opens the Logs view filtered specifically to that Account.
* **Suspend** – Stops all API requests temporarily while refreshing the token.
* **Convert to Test/Production** – Switches the Linked Account type.
* **Edit** – Reopens the Link Account flow and pre-populates the forms with existing data.

***

### Testing Accounts

<Warning>
  The request tester is only available for legacy unified API endpoints.
</Warning>

The **Request Tester** lets you execute API requests directly against any linked account. Use it to verify connectivity, test specific endpoints, and troubleshoot issues reported by end-users.

<Steps>
  <Step title="Open the Request Tester">
    Click the ellipsis menu (⋯) on any account row and select **Request Tester**.
  </Step>

  <Step title="Select an endpoint">
    Choose from available endpoints organized by category (e.g., List Employees, Get User, List Files).
  </Step>

  <Step title="Configure and execute">
    Set any required parameters and click **Send Request** to see the response.
  </Step>
</Steps>

<Tip>
  The Request Tester shows the exact API response, including status codes and headers. Use it to debug authentication issues, verify data availability, and test pagination before implementing in your application.
</Tip>

For complete documentation, see the [Request Tester guide](/guides/request-tester).

***

### Testing Actions

<Snippet />

***

### Linking Accounts

You can link new Accounts by clicking the **"Link Account"** button at the top right of the Accounts page.

There are **three ways to link an Account**:

1. **Request Authentication**
   Generate a secure URL that can be shared with an end-user. They use this link to authenticate the Account themselves using our [Hub](/guides/embedding-stackone-hub).

   <video />

2. **Authenticate Now**
   Generate the Hub and input credentials directly into the dashboard to link an Account immediately. This is typically used during integration development or testing, often with sandbox credentials.

   <video />

3. **Embed the Hub**
   The most scalable option - [embed StackOne's Hub](/guides/embedding-stackone-hub) directly into your own product, allowing end-users to self-authenticate their Accounts without leaving your app.

#### Account Linking Parameters

* **Required**
  * **Type:** Accounts can either be Production or Test,
    * Test Accounts expire after 3 months.
    * Production Accounts remain active indefinitely.
    * This designation (Test or Production) can also be set programmatically when authenticating through the embedded Hub. For example, if you want to ensure that all Accounts linked via your test environment are marked as Test.

  * **Origin Owner ID:** The UUID that your system uses to identify the end-user that you are connecting via StackOne's Hub. This will be used by your system to identify which end-user you should be routing data from or to.

  * **Origin Owner Name:** This will be the name of the Account shown within the Accounts table.
* **Optional**
  * **Origin Username:** You can save the email address or username of the user responsible for linking the account. This can be referenced on the Account specific page if you ever need to reconnect the Account in future.
  * **Multiple Linked Accounts:** If you need to connect multiple Accounts to the same Origin Owner ID for the same integration, set this value == Yes. If it is set == No, we'll rewrite the old Account with the new Integration if you need to reconnect an existing Account.By default this value is set to No.

***

### Access

* **Project Users with Basic permissions** can only view high-level details about the Accounts.
* **Project Admins** can edit, delete, and trigger API requests for any Account linked within that project.


# AI Features
Source: https://docs.stackone.com/guides/ai-features

Learn about StackOne's AI-powered features that enhance your integration experience, including prompt injection protection and intelligent error analysis.

## Overview

StackOne provides AI-powered features to simplify your integration workflows and improve troubleshooting efficiency. These features can be enabled or disabled at the project level through the [AI Settings](/guides/managing-projects#ai-settings) in your project configuration.

## Error Explainer

The **Error Explainer** is a built-in AI-powered feature designed to help you quickly understand and resolve errors that appear when connecting to or using connectors in StackOne. Instead of leaving you to decode raw logs or cryptic provider messages, the explainer surfaces the most important details and suggests practical steps you can take to fix the issue.

***

### Where You Can Use the Error Explainer

You can invoke the Error Explainer in three main places:

* **Provider request logs**
  * Run the explainer across all underlying requests to identify and fix broken ones.
* **Individual requests**
  * On each request, generate tailored suggestions to solve the error.

<Frame>
  <img alt="Error Explainer in Request Logs" />
</Frame>

* **Account status page**
  * If an account has connection issues, use the explainer directly from its account page.

<Frame>
  <img alt="Error Explainer on Account Page" />
</Frame>

***

### How It Works (High-Level)

Think of the Error Explainer as a smart resolution agent:

* **Extracts key information** from error logs automatically (so you don't have to read through raw JSON or HTTP dumps).
* **Looks up context** from multiple sources:
  * Provider documentation
  * StackOne documentation
  * Unified API error guides
* **Generates resolution steps** that are specific to your integration and the problem at hand, typically in **3 clear, actionable steps**.

The explainer is designed to prioritize provider-specific errors as the root cause, ensuring the resolution is relevant.

***

### Example Workflow

```mermaid theme={null}
flowchart TD
    A[Connection Error] -->|Click to Generate| B(Extract Error Information)
    B --> C{Resolve Error}
    C --> D[Check Error Codes]
    C --> E[Search StackOne Docs]
    C --> F[Search Provider Docs]
    D --> G[Generate Resolution Steps]
    E --> G
    F --> G
```

***

### Key Features

* **AI-Driven Analysis**

  Uses large language models to parse unstructured logs into something readable and actionable.

* **Multi-Source Knowledge**

  Draws on StackOne documentation, common error guides, and provider documentation.

* **Concise Resolution Steps**

  Always outputs no more than three clear, prioritized steps to fix the issue.

* **Customer-Scoped Data**

  Training and evaluation data never contains PII. Your logs are only used to generate answers for your own account.

* **Feedback Loop**

  You can leave feedback on:

  * General usability and usefulness of the feature
  * Accuracy of suggested steps compared to the actual solution you applied

    This helps continuously improve the Error Explainer.

***

### Objective

The goal of the Error Explainer is to act as your **connection resolution agent**:

* Simplify debugging of provider errors
* Reduce support back-and-forth
* Help you resolve issues directly in the platform

***

### When to Use It

* **During setup**: If an integration fails at the connection stage.
* **During operations**: When specific API calls return unexpected errors.
* **During troubleshooting**: If account status flags persistent issues.

***

### FAQ

**Do I need to use the Error Explainer?**

No. It's a quality-of-life feature. You can still use the platform without it.

**How do I use the Error Explainer?**

Enable AI features and advanced logs in your project settings then, you can invoke it by clicking the ***Click to Generate*** button wherever you see it in the UI (e.g., request logs, account status page).

**Will my data be used to train the AI?**

No. Your logs are only used to generate explanations for your account. No PII is used in training or evaluation.

**What kind of output should I expect?**

A short set of up to three steps, focused on what to check or fix next (e.g., "Refresh your access token with the correct scope," or "Verify that the API key has permissions to call this endpoint").

## Defender

**Defender** protects your AI agents from prompt injection attacks by scanning tool call responses before they reach your LLM. For full configuration options and details, see the [Defender guide](/guides/defender).


# API Keys
Source: https://docs.stackone.com/guides/api-keys

Steps to generate and manage API keys

To connect your application with StackOne securely, you need to generate API keys. These keys authenticate your application and protect your data.

## Step-by-Step Guide to Generating an API Key

<Steps>
  <Step title="Access the API Key Management Section">
    Log in to StackOne and go to the **API Keys** section in the left navigation menu. This is where you can generate and manage your API keys.

    <Frame>
      <img alt="API Keys management page" />
    </Frame>
  </Step>

  <Step title="Generate a New API Key">
    Click the **Create API Key** button. In the popup dialog, enter a name for your key (e.g., `my-agent-key` or `production-hris-sync`). This name is a label and cannot be changed later.

    <Frame>
      <img alt="Create API key dialog with scopes" />
    </Frame>
  </Step>

  <Step title="Configure API Key Scopes (optional)">
    By default, API keys are created with full permissions. Expand the **Scopes** section to restrict access based on your application's needs.

    ### Available Scopes

    | Scope            | Access Level | Description                                                                                                                                                                                                                                                                    |
    | ---------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | **Platform API** | Read / Write | Access to account management, session tokens, and integration configs. Required for StackOne Connect and account operations.                                                                                                                                                   |
    | **Credentials**  | Read         | Retrieve stored credentials for direct provider access. Required for StackOne CLI and running actions outside the platform.                                                                                                                                                    |
    | **Unified API**  | Read / Write | Access to all unified endpoints (HRIS, ATS, CRM, LMS, etc.) for reading and writing data across connected providers.                                                                                                                                                           |
    | **Actions**      | Execute      | Allows you to interact with actions via RPC and MCP.                                                                                                                                                                                                                           |
    | **Connectors**   | Read / Write | Access to custom connector management. **Read** (`connectors:read`) allows downloading connectors from the registry. **Write** (`connectors:write`) allows pushing and deleting connectors. Required for [Connector Engine](/guides/connector-engine/introduction) operations. |

    <Tip>
      For AI agents, you typically need:

      * **Platform API Read**: to list connected accounts
      * **Actions Execute**: to interact with actions via RPC and MCP
      * **Connectors Read**: to download connectors from the registry
      * **Credentials Read**: to retrieve stored credentials for direct provider access
    </Tip>
  </Step>

  <Step title="Copy and Store the API Key">
    After clicking **Generate**, the API key is displayed on-screen. Copy it immediately and store it securely. This is the only time it will be shown. If you lose the key, you'll need to generate a new one.

    <Warning>
      Store the key in a secure location such as a password manager or secrets vault. Never commit API keys to source control.
    </Warning>
  </Step>

  <Step title="Manage Your API Keys">
    Your new API key appears in the **API Keys** table. From here you can:

    * **Enable/Disable** keys using the toggle switch
    * **View scopes** for each key
    * **Delete** keys that are no longer needed

    The **Last used** column helps you identify stale keys that should be revoked.
  </Step>
</Steps>

## Using the generated API Key

Once you've [generated your API key](#step-by-step-guide-to-generating-an-api-key), it’s essential to know how to use it for authentication.

You will need to include the API key for every API call. For basic authentication, you can use the API key in the username or password field when calling any API endpoint, such as the [List Accounts endpoint](/platform/api-reference/accounts/list-accounts).

The use of API keys is tracked, allowing you to monitor their activity and revoke them if necessary. The **Last used** column on the API keys table indicates the last call made with each key. For security reasons, you are encouraged to regularly review your API keys list and revoke any that are no longer needed.


# Auth Link
Source: https://docs.stackone.com/guides/auth-link

Get end-users to connect their tools with only a link!

## Overview

Auth Links let you deliver a secure URL to your end users for a secure, in-browser connection experience without embedding the StackOne Hub in your web app.

## How to generate a link

An Auth Link can be generated directly from the StackOne dashboard. Here's how:

<Steps>
  <Step title="Navigate to Accounts">
    Log in to the [StackOne dashboard](https://app.stackone.com/) and select [Accounts](https://app.stackone.com/accounts) from the left menu.
  </Step>

  <Step title="Click the + Link Account button">
    <Frame>
      <img alt="Accounts page with Link Account button" />
    </Frame>
  </Step>

  <Step title="Fill in the required fields">
    * **Origin owner ID** - This should be the end-user identifier you use in your own system(s) (most likely, a UUID or integer)

    * **Origin owner name** - This is the end-user name in your own system(s)

    * **Origin username** (optional) - The end-user's username (eg: an email address) that will connect or be responsible for the connection

    * **Category** (optional) - If you have enabled connectors across multiple categories, you can filter the list of connectors displayed. Make sure that the information you enter matches your system precisely.

    Then click **Next** and **Generate**.

    <Frame>
      <img alt="Auth Link form" />
    </Frame>
  </Step>

  <Step title="Copy and send the link to the end-user">
    <Frame>
      <img alt="Auth Link generated" />
    </Frame>

    <Note>
      Note: This link expires after 30 days.
    </Note>

    The end-user will now be able to connect their accounts using the link.
  </Step>
</Steps>

### Generating the link programmatically

To support a more scalable solution, you can programmatically generate links for end-users.

Call the [Create Connect Session Endpoint](/platform/api-reference/connect-sessions/create-connect-session) and the `auth_link_url` property in the response contains the link for the end-user.

<Info>
  Set `expires_in` (in seconds) to give end-users enough time to complete the connection.
  (eg. 5 days is 432000, 7 days is 604800)
</Info>

## What the end-user sees

When the user navigates to the **Auth Link**, they will see the **StackOne Hub** with a list of all connectors enabled on your project. The user can then select and connect to the provider they need.

<Frame>
  <img alt="StackOne Hub Connector Listing" />
</Frame>

## Verifying the connection

After the user has connected an integration successfully, StackOne will fire a `account.created` [webhook event](/guides/webhooks) containing the Account ID (which is required to make a [unified API request](/guides/making-your-first-api-request)). The linked account will also be displayed in the [Accounts](https://app.stackone.com/accounts) page and it will also be visible via the [Accounts API endpoint](/platform/api-reference/accounts/list-accounts).


# Calling Actions
Source: https://docs.stackone.com/guides/calling-stackone-actions

Choose how to invoke StackOne actions: direct API, MCP, A2A, or SDKs

StackOne provides multiple ways to call actions. Whether you're building an AI agent, a traditional application, or orchestrating multi-agent systems, there's a protocol that fits your needs.

## Why Multiple Protocols?

StackOne's **Falcon Connector Engine** handles authentication, rate limiting, data transformation, and error recovery for every action. All protocols (direct API, MCP, A2A, and SDKs) route through this same engine, so you get the same reliability regardless of how you call actions.

<Info>
  **Actions** are the atomic operations in StackOne: `salesforce_list_contacts`, `gmail_send_message`, `google_drive_list_files`, etc. Every protocol is just a different way to invoke the same underlying actions.
</Info>

## Quick Decision Guide

<CardGroup>
  <Card title="Actions API" icon="code">
    **Direct RPC calls** for traditional applications, scripts, or when you need full control

    [Jump to Actions API →](#actions-api)
  </Card>

  <Card title="AI Toolset (SDK)" icon="microchip">
    **Native TypeScript/Python** with framework integrations (LangChain, CrewAI, OpenAI)

    [Jump to SDKs →](#ai-toolset-sdks)
  </Card>

  <Card title="MCP Servers" icon={<svg fill="currentColor" fillRule="evenodd" height="1em" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><path d="M15.688 2.343a2.588 2.588 0 00-3.61 0l-9.626 9.44a.863.863 0 01-1.203 0 .823.823 0 010-1.18l9.626-9.44a4.313 4.313 0 016.016 0 4.116 4.116 0 011.204 3.54 4.3 4.3 0 013.609 1.18l.05.05a4.115 4.115 0 010 5.9l-8.706 8.537a.274.274 0 000 .393l1.788 1.754a.823.823 0 010 1.18.863.863 0 01-1.203 0l-1.788-1.753a1.92 1.92 0 010-2.754l8.706-8.538a2.47 2.47 0 000-3.54l-.05-.049a2.588 2.588 0 00-3.607-.003l-7.172 7.034-.002.002-.098.097a.863.863 0 01-1.204 0 .823.823 0 010-1.18l7.273-7.133a2.47 2.47 0 00-.003-3.537z"></path><path d="M14.485 4.703a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a4.115 4.115 0 000 5.9 4.314 4.314 0 006.016 0l7.12-6.982a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a2.588 2.588 0 01-3.61 0 2.47 2.47 0 010-3.54l7.12-6.982z"></path></svg>}>
    **Open standard** for AI tools. Works with Claude, Cursor, Vercel AI, n8n

    [Jump to MCP →](#mcp-servers)
  </Card>

  <Card title="A2A Protocol" icon={<svg width="1em" height="1em" viewBox="0 0 860 860" fill="none" xmlns="http://www.w3.org/2000/svg"><circle cx="544" cy="307" r="27" fill="currentColor"/><circle cx="154" cy="307" r="27" fill="currentColor"/><circle cx="706" cy="307" r="27" fill="currentColor"/><circle cx="316" cy="307" r="27" fill="currentColor"/><path d="M336.5 191.003H162C97.6588 191.003 45.5 243.162 45.5 307.503C45.5 371.844 97.6442 424.003 161.985 424.003C206.551 424.003 256.288 424.003 296.5 424.003C487.5 424.003 374 191.005 569 191.001C613.886 191 658.966 191 698.025 191C762.366 191.001 814.5 243.16 814.5 307.501C814.5 371.843 762.34 424.003 697.998 424.003H523.5" stroke="currentColor" strokeWidth="48" strokeLinecap="round"/><path d="M256 510.002C270.359 510.002 282 521.643 282 536.002C282 550.361 270.359 562.002 256 562.002H148C133.641 562.002 122 550.361 122 536.002C122 521.643 133.641 510.002 148 510.002H256ZM712 510.002C726.359 510.002 738 521.643 738 536.002C738 550.361 726.359 562.002 712 562.002H360C345.641 562.002 334 550.361 334 536.002C334 521.643 345.641 510.002 360 510.002H712Z" fill="currentColor"/><path d="M444 628.002C458.359 628.002 470 639.643 470 654.002C470 668.361 458.359 680.002 444 680.002H100C85.6406 680.002 74 668.361 74 654.002C74 639.643 85.6406 628.002 100 628.002H444ZM548 628.002C562.359 628.002 574 639.643 574 654.002C574 668.361 562.359 680.002 548 680.002C533.641 680.002 522 668.361 522 654.002C522 639.643 533.641 628.002 548 628.002ZM760 628.002C774.359 628.002 786 639.643 786 654.002C786 668.361 774.359 680.002 760 680.002H652C637.641 680.002 626 668.361 626 654.002C626 639.643 637.641 628.002 652 628.002H760Z" fill="currentColor"/></svg>}>
    **Agent-to-agent** communication for multi-agent orchestration

    [Jump to A2A →](#a2a-protocol)
  </Card>
</CardGroup>

## Comparison Table

| Feature           | Actions API               | AI Toolset (SDK)          | MCP Servers               | A2A Protocol         |
| ----------------- | ------------------------- | ------------------------- | ------------------------- | -------------------- |
| **Use case**      | Traditional apps, scripts | AI agents with frameworks | MCP-compatible clients    | Multi-agent systems  |
| **Requires code** | Yes                       | Yes                       | No (config only)          | Yes                  |
| **Best for**      | Full control, non-agentic | Production AI apps        | Quick setup, IDE agents   | Agent orchestration  |
| **Works with**    | Any HTTP client           | LangChain, CrewAI, OpenAI | Claude, Cursor, Vercel AI | Any A2A orchestrator |

***

## Actions API

The Actions API is the foundational protocol: a direct RPC endpoint to invoke any StackOne action programmatically. MCP and A2A both use this API internally.

<Tabs>
  <Tab title="When to Use">
    * Building **traditional applications** (not AI agents)
    * Writing **scripts or automation** that call connectors
    * Need **direct HTTP calls** without SDK dependencies
    * Want **full control** over request/response handling
    * Integrating from languages without SDK support
  </Tab>

  <Tab title="Example">
    ```bash theme={null}
    curl -X POST "https://api.stackone.com/actions/rpc" \
      -u "$STACKONE_API_KEY:" \
      -H "x-account-id: customer-hubspot" \
      -H "Content-Type: application/json" \
      -d '{
        "action": "hubspot_list_contacts",
        "query": { "page_size": 50 }
      }'
    ```
  </Tab>
</Tabs>

<Card title="Execute Actions API →" href="/platform/api-reference/actions/make-an-rpc-call-to-an-action" />

***

## AI Toolset SDKs

Native TypeScript and Python libraries with framework integrations for OpenAI, LangChain, CrewAI, Vercel AI SDK, and more.

<Tabs>
  <Tab title="When to Use">
    * Building a **custom AI agent** or product
    * Need **programmatic control** over which tools to load
    * Using **LangChain, CrewAI, OpenAI SDK**, or similar frameworks
    * Need to **dynamically select tools** based on context or user
    * Want **type safety** and IDE autocomplete
    * Building **production applications** with custom error handling
  </Tab>

  <Tab title="When NOT to Use">
    * You just want to use StackOne tools in Claude Desktop or Cursor
    * You don't want to write code
    * Your use case is fully handled by MCP configuration
  </Tab>
</Tabs>

<CardGroup>
  <Card title="TypeScript SDK →" href="/agents/typescript/introduction" />

  <Card title="Python SDK →" href="/agents/python/introduction" />
</CardGroup>

***

## MCP Servers

Model Context Protocol (MCP) is an open standard for connecting AI models to external tools. StackOne hosts MCP servers that expose all actions. These servers call the same Actions API.

<Tabs>
  <Tab title="When to Use">
    * Using an **MCP-compatible client**: Claude SDK, Vercel AI SDK, Cursor, Windsurf, n8n
    * Want **zero-code setup**: just configure and go
    * Building with **frameworks that support MCP natively**
    * Adding StackOne tools to **existing MCP setups**
    * Using **IDEs or agent builders** like Cursor or Flowise
    * Need to **switch between accounts** dynamically (just change `x-account-id`)
  </Tab>

  <Tab title="When NOT to Use">
    * Need **fine-grained programmatic control** over tool loading
    * Building a **production app** that requires custom error handling
    * Your framework doesn't support MCP
  </Tab>
</Tabs>

<Card title="MCP Quickstart →" href="/mcp/quickstart" />

***

## A2A Protocol

Agent-to-Agent (A2A) is Google's open protocol for autonomous agent communication. StackOne exposes A2A-compatible agents for each integration. These agents invoke the same underlying Actions API.

<Tabs>
  <Tab title="When to Use">
    * Building **multi-agent systems** with specialized agents
    * Want **autonomous agent communication** (agents talking to agents)
    * Need **context isolation** to protect your top-level agent's context window
    * Using an **A2A-compatible orchestrator**
    * Need **long-running tasks** with async completion
  </Tab>

  <Tab title="When NOT to Use">
    * Just need to call a few tools from your agent
    * Need **synchronous, immediate responses**
    * Your stack doesn't support A2A protocol
    * Building simple, single-agent applications
  </Tab>
</Tabs>

<Card title="A2A Quickstart →" href="/a2a/quickstart" />

***

## Can I Use Multiple?

Yes! Many production setups combine protocols:

* **Actions API for backend jobs** (scheduled syncs, data pipelines)
* **AI Toolset (SDK) for your product** (customer-facing AI features)
* **MCP for internal tools** (Cursor, Claude Desktop for your team)
* **A2A for complex workflows** (multi-agent orchestration)

All protocols use the same actions and authentication, so you can mix and match.

## Next Steps

<CardGroup>
  <Card title="Execute Actions" icon="code" href="/api/execute-actions">
    Direct RPC calls
  </Card>

  <Card title="TypeScript SDK" icon="js" href="/agents/typescript/introduction">
    Native TypeScript integration
  </Card>

  <Card title="MCP Quickstart" icon={<svg fill="currentColor" fillRule="evenodd" height="1em" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><path d="M15.688 2.343a2.588 2.588 0 00-3.61 0l-9.626 9.44a.863.863 0 01-1.203 0 .823.823 0 010-1.18l9.626-9.44a4.313 4.313 0 016.016 0 4.116 4.116 0 011.204 3.54 4.3 4.3 0 013.609 1.18l.05.05a4.115 4.115 0 010 5.9l-8.706 8.537a.274.274 0 000 .393l1.788 1.754a.823.823 0 010 1.18.863.863 0 01-1.203 0l-1.788-1.753a1.92 1.92 0 010-2.754l8.706-8.538a2.47 2.47 0 000-3.54l-.05-.049a2.588 2.588 0 00-3.607-.003l-7.172 7.034-.002.002-.098.097a.863.863 0 01-1.204 0 .823.823 0 010-1.18l7.273-7.133a2.47 2.47 0 00-.003-3.537z"></path><path d="M14.485 4.703a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a4.115 4.115 0 000 5.9 4.314 4.314 0 006.016 0l7.12-6.982a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a2.588 2.588 0 01-3.61 0 2.47 2.47 0 010-3.54l7.12-6.982z"></path></svg>} href="/mcp/quickstart">
    Zero-code MCP setup
  </Card>

  <Card title="A2A Introduction" icon={<svg width="1em" height="1em" viewBox="0 0 860 860" fill="none" xmlns="http://www.w3.org/2000/svg"><circle cx="544" cy="307" r="27" fill="currentColor"/><circle cx="154" cy="307" r="27" fill="currentColor"/><circle cx="706" cy="307" r="27" fill="currentColor"/><circle cx="316" cy="307" r="27" fill="currentColor"/><path d="M336.5 191.003H162C97.6588 191.003 45.5 243.162 45.5 307.503C45.5 371.844 97.6442 424.003 161.985 424.003C206.551 424.003 256.288 424.003 296.5 424.003C487.5 424.003 374 191.005 569 191.001C613.886 191 658.966 191 698.025 191C762.366 191.001 814.5 243.16 814.5 307.501C814.5 371.843 762.34 424.003 697.998 424.003H523.5" stroke="currentColor" strokeWidth="48" strokeLinecap="round"/><path d="M256 510.002C270.359 510.002 282 521.643 282 536.002C282 550.361 270.359 562.002 256 562.002H148C133.641 562.002 122 550.361 122 536.002C122 521.643 133.641 510.002 148 510.002H256ZM712 510.002C726.359 510.002 738 521.643 738 536.002C738 550.361 726.359 562.002 712 562.002H360C345.641 562.002 334 550.361 334 536.002C334 521.643 345.641 510.002 360 510.002H712Z" fill="currentColor"/><path d="M444 628.002C458.359 628.002 470 639.643 470 654.002C470 668.361 458.359 680.002 444 680.002H100C85.6406 680.002 74 668.361 74 654.002C74 639.643 85.6406 628.002 100 628.002H444ZM548 628.002C562.359 628.002 574 639.643 574 654.002C574 668.361 562.359 680.002 548 680.002C533.641 680.002 522 668.361 522 654.002C522 639.643 533.641 628.002 548 628.002ZM760 628.002C774.359 628.002 786 639.643 786 654.002C786 668.361 774.359 680.002 760 680.002H652C637.641 680.002 626 668.361 626 654.002C626 639.643 637.641 628.002 652 628.002H760Z" fill="currentColor"/></svg>} href="/a2a/introduction">
    Multi-agent orchestration
  </Card>
</CardGroup>


# Connection Methods
Source: https://docs.stackone.com/guides/connect-tools-overview

Choose the right method to connect your end-users' accounts

StackOne offers three ways to let end-users connect their accounts to your application.

| Method                              | Best For           | User Experience |
| ----------------------------------- | ------------------ | --------------- |
| **[Embedded Hub](#embedded-hub)**   | Production apps    | In-app, branded |
| **[Auth Link](#auth-link)**         | Email flows, demos | Standalone page |
| **[Dashboard](#dashboard-linking)** | Internal testing   | Admin-only      |

## Embedded Hub

Embed the StackOne Hub directly in your app. End-users select a connector and authenticate without leaving your application.

<Tabs>
  <Tab title="Use Cases">
    * Production applications with custom UX
    * Branded, in-app connection experience
    * Full control over the integration flow
  </Tab>

  <Tab title="How It Works">
    1. Backend generates a [Connect Session token](/platform/api-reference/connect-sessions/create-connect-session)
    2. Frontend initializes the Hub with the token
    3. End-user selects provider and authenticates
    4. StackOne creates linked account and fires webhook
  </Tab>
</Tabs>

<Card title="Embedding Guide →" icon="window" href="/guides/embedding-stackone-hub">
  Complete guide for React and non-React implementations
</Card>

## Auth Link

Secure URLs that open the StackOne Hub in a standalone browser tab. Generate from the dashboard or via API.

<Tabs>
  <Tab title="Use Cases">
    * Onboarding emails asking end-users to connect their HRIS
    * Quick demos without frontend integration work
    * Sales-led onboarding flows
  </Tab>

  <Tab title="How It Works">
    1. Generate link from [dashboard](https://app.stackone.com/accounts) or [API](/platform/api-reference/connect-sessions/create-connect-session)
    2. Send link to end-user (valid 5 days by default)
    3. End-user clicks, authenticates
    4. StackOne creates linked account and fires webhook
  </Tab>
</Tabs>

<Card title="Auth Links Guide →" href="/guides/auth-link" />

<Tip>
  To trigger a workflow when an account is linked via Auth Link, subscribe to [account webhooks](#webhooks) since there's no frontend callback available.
</Tip>

## Dashboard Linking

Connect accounts directly from the StackOne dashboard for internal testing.

<Tabs>
  <Tab title="Use Cases">
    * Testing API integration during development
    * Debugging connection issues
    * Internal demos
  </Tab>

  <Tab title="How It Works">
    1. Go to [Accounts](https://app.stackone.com/accounts)
    2. Click **Link Account**
    3. Select provider and enter credentials
    4. Use resulting `account_id` in API calls
  </Tab>
</Tabs>

<Warning>
  Dashboard linking is for internal use only. End-users should use the Embedded Hub or Auth Links.
</Warning>

***

## Connection Events

Get notified when accounts are connected, updated, or disconnected.

### Frontend Callbacks (Embedded Hub)

When using the Embedded Hub, handle connection events directly in your frontend:

<Tabs>
  <Tab title="Hub">
    ```tsx theme={null}
    import { StackOneHub } from "@stackone/hub";

    function App() {
      return (
        <StackOneHub
          onSuccess={(account) => {
            console.log('Account linked:', account.id);
            // Trigger your onboarding flow
          }}
          onCancel={() => console.log('User cancelled')}
          onClose={() => console.log('Hub closed')}
        />
      );
    }
    ```
  </Tab>

  <Tab title="Legacy Hub">
    ```tsx theme={null}
    import { useStackOneHub } from '@stackone/react-hub';

    const LinkAccountButton = () => {
      const { startConnect } = useStackOneHub();

      const startFlow = async () => {
        const { token } = await retrieveConnectSessionToken();
        startConnect({
          sessionToken: token,
          onSuccess: (account) => {
            console.log('Account linked:', account.id);
          },
          onCancel: () => console.log('User cancelled'),
        });
      };

      return <button onClick={startFlow}>Connect Account</button>;
    };
    ```
  </Tab>
</Tabs>

### Webhooks

For backend notifications (required for Auth Links, recommended for all methods), subscribe to account webhooks:

| Event             | Triggered When                            |
| ----------------- | ----------------------------------------- |
| `account.created` | New account linked                        |
| `account.updated` | Account credentials refreshed or modified |
| `account.deleted` | Account disconnected                      |

```json Example webhook payload theme={null}
{
  "event": "account.created",
  "data": {
    "id": "acme-corp-bamboohr",
    "provider": "bamboohr",
    "origin_owner_id": "cust_12345",
    "status": "active"
  }
}
```

<CardGroup>
  <Card title="Webhooks Guide" icon="bell" href="/guides/webhooks">
    Full setup and event reference
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Embed the Hub" icon="window" href="/guides/embedding-stackone-hub">
    Full guide for React and script embedding
  </Card>

  <Card title="Auth Links" icon="link" href="/guides/auth-link">
    Generate and send connection links
  </Card>

  <Card title="Managing Accounts" icon="users" href="/guides/accounts-section">
    View and manage connected accounts
  </Card>

  <Card title="Backend Setup" icon="server" href="/platform/connect-your-backend-with-stackone">
    Generate session tokens securely
  </Card>
</CardGroup>


# Build Your First Connector
Source: https://docs.stackone.com/guides/connector-engine/building-first-connector

Step-by-step guide to building, testing, and deploying your first StackOne connector

A StackOne connector is a YAML configuration that turns a third-party API into a set of agent-ready actions. By the end of this guide, you'll have a working connector pushed to your StackOne project — built with the StackOne CLI, an AI assistant, and the [connectors-template](https://github.com/StackOneHQ/connectors-template).

You'll set up your environment, generate an API key, build and test authentication against a provider, then add and validate your first actions.

<Warning>
  Custom connectors require Enterprise access — contact [support@stackone.com](mailto:support@stackone.com) to enable.
</Warning>

***

## Setup

<Steps>
  <Step title="Generate a StackOne API key">
    1. In the [StackOne dashboard](https://app.stackone.com/), go to **Project Settings → API keys**.
    2. Click **Create API key**.
    3. Ensure the following **Scopes** are enabled (some are not selected by default):
       * `connectors:read` — download connectors from registry
       * `connectors:write` — push and delete connectors
       * `credentials:read` — use linked account credentials with `stackone run`
    4. Copy the key (format: `v1.{region}.xxxxx`) and store it somewhere safe — you won't be able to view it again.

    See [API Keys](/guides/api-keys#configure-api-key-scopes-optional) for more on scopes.
  </Step>

  <Step title="Open a Terminal & Install the StackOne CLI">
    You'll run all StackOne CLI commands from a terminal window.

    <Tabs>
      <Tab title="macOS">
        1. Press `Cmd + Space` to open Spotlight, type **Terminal**, and press Enter.
        2. Confirm Node.js 18+ is installed by running:
           ```bash theme={null}
           node --version
           ```
           If the command isn't found or the version is below 18, install Node.js from [nodejs.org](https://nodejs.org/).
        3. Confirm Git is installed:
           ```bash theme={null}
           git --version
           ```
           If the command isn't found, install the Xcode Command Line Tools (`xcode-select --install`) or download Git from [git-scm.com](https://git-scm.com/downloads/mac).
        4. Install the StackOne CLI globally via npm:
           ```bash theme={null}
           npm install -g @stackone/cli
           ```
           The `-g` flag installs the CLI globally so the `stackone` command is available in any directory.
        5. Verify the install:
           ```bash theme={null}
           stackone --version
           ```
      </Tab>

      <Tab title="Windows">
        1. Open **Command Prompt** or **PowerShell** from the Start menu.
        2. Confirm Node.js 18+ is installed (`node --version`). If missing, install from [nodejs.org](https://nodejs.org/).
        3. Confirm Git is installed (`git --version`). If missing, install [Git for Windows](https://git-scm.com/downloads/win).
        4. Install the StackOne CLI: `npm install -g @stackone/cli`
        5. Verify with `stackone --version`.
      </Tab>

      <Tab title="Linux">
        1. Open your terminal application.
        2. Confirm Node.js 18+ is installed (`node --version`). Install via your package manager if needed.
        3. Confirm Git is installed (`git --version`). If missing, install via your package manager (e.g., `sudo apt install git` on Debian/Ubuntu, `sudo dnf install git` on Fedora).
        4. Install the StackOne CLI: `npm install -g @stackone/cli`
        5. Verify with `stackone --version`.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Set Up Your Working Directory">
    Create your own private GitHub repository by following the [connectors-template setup guide](https://github.com/StackOneHQ/connectors-template#set-up-your-private-repository).

    Clone your new private repo into a `my-connector` folder and install dependencies:

    ```bash theme={null}
    git clone https://github.com/<your-org>/<your-repo>.git my-connector
    cd my-connector
    npm install
    ```

    All subsequent CLI commands run from inside `my-connector`.

    <Tip>
      The template ships with agent skills (including `/on-boarding`), CI/CD workflows, a pre-configured `CLAUDE.md`, and example connector structures.
    </Tip>

    <Accordion title="Starting without connectors-template">
      <Warning>
        You can build connectors without the template, but you'll skip the bundled agent skills (like `/on-boarding`), pre-configured `CLAUDE.md`, and CI/CD workflows.
      </Warning>

      Create an empty folder, move into it, then pull an existing connector as a reference:

      ```bash theme={null}
      mkdir my-connector
      cd my-connector
      stackone pull --connector provider --output ./connectors/
      ```
    </Accordion>
  </Step>

  <Step title="Configure the StackOne CLI">
    From inside your working directory, authenticate the StackOne CLI:

    ```bash theme={null}
    # Authenticate globally (stores credentials in ~/.stackone)
    stackone agent setup --global

    # Or scope to current project only
    stackone agent setup --local
    ```

    This configures MCP tools for AI-assisted development and stores your access token.
  </Step>

  <Step title="Create a StackOne CLI Profile">
    Create a named profile so deployment commands like `stackone push` can authenticate without you pasting your API key each time:

    ```bash theme={null}
    stackone init
    ```

    You'll be prompted for a profile label and an API key — paste the StackOne API key you generated in [Step 1](#generate-a-stackone-api-key). Create separate profiles for staging vs. production and reference them later with `--profile <profile-label>`.
  </Step>
</Steps>

***

## Starting the Build

The connectors-template includes agent skills and a pre-configured `CLAUDE.md`, so the recommended path is to open your project in an AI coding assistant and start a chat from inside the `my-connector` directory.

<Tabs>
  <Tab title="Claude Code">
    From inside `my-connector`, launch Claude Code:

    ```bash theme={null}
    claude
    ```

    The template's `CLAUDE.md` and bundled skills (including `/on-boarding`) load automatically.
  </Tab>

  <Tab title="Cursor / VS Code">
    Open the `my-connector` folder in Cursor or VS Code with the Claude extension, then open the AI chat panel.
  </Tab>
</Tabs>

Once the chat is open, run the onboarding skill:

```
/on-boarding
```

This launches an interactive flow that guides you through:

1. **Connector type selection** — Agentic Actions (raw provider data) vs Schema-Based (unified output)
2. **Provider details** — Name, API version, and pulling any existing connector
3. **Authentication setup** — Configuring and validating auth before building actions
4. **Schema definition** (for unified connectors) — Defining your target output format
5. **Endpoint research** — Discovering available API endpoints and their trade-offs
6. **Action building** — Implementing and testing each action

The onboarding flow ensures you complete each step before moving to the next, reducing errors and rework.

<Tip>
  **Experienced users:** Skip onboarding and tell the agent directly what you need:

  * "Build a connector for \[Provider] with employee management actions"
  * "Start unified build for \[Provider]" (for schema-based connectors)
</Tip>

***

## Build Workflow

The recommended workflow ensures you validate each step before moving to the next:

```mermaid theme={null}
flowchart LR
    A[Fork/Pull] --> B[Build Auth]
    B --> C[Connect Account]
    C --> D[Build Actions]
    D --> E[Test & Debug]
    E --> F[Iterate]
    F --> D
```

### Step 1: Fork or Pull Existing Connector

Always start by checking if a connector already exists:

```bash theme={null}
# Pull existing connector from StackOne registry
stackone pull --connector provider --output ./connectors/

# Check what was downloaded
ls connectors/provider/
```

If the pull succeeds, you have a foundation to build on. If it fails, create a new connector structure:

```
connectors/provider/
├── provider.connector.s1.yaml       # Main file (auth, metadata)
└── provider.employees.s1.partial.yaml  # Actions by resource
```

### Step 2: Build Authentication

<Warning>
  **Do not proceed until authentication works.** All other work depends on valid auth.
</Warning>

Configure authentication in the main connector file:

<Tabs>
  <Tab title="API Key (Bearer)">
    ```yaml theme={null}
    authentication:
      - custom:
          type: custom
          label: API Key
          authorization:
            type: bearer
            token: $.credentials.apiKey
          configFields:
            - key: apiKey
              label: API Key
              type: password
              required: true
              secret: true
          testActionsIds:
            - list_users  # Simple action to test auth
    ```
  </Tab>

  <Tab title="API Key (Header)">
    ```yaml theme={null}
    authentication:
      - custom:
          type: custom
          label: API Key
          authorization:
            type: none
          customHeaders:
            X-API-Key: $.credentials.apiKey
          configFields:
            - key: apiKey
              label: API Key
              type: password
              required: true
              secret: true
    ```
  </Tab>

  <Tab title="Basic Auth">
    ```yaml theme={null}
    authentication:
      - custom:
          type: custom
          label: Basic Auth
          authorization:
            type: basic
            username: $.credentials.username
            password: $.credentials.password
          configFields:
            - key: username
              label: Username
              type: text
              required: true
            - key: password
              label: Password
              type: password
              required: true
              secret: true
    ```
  </Tab>
</Tabs>

Create a simple test action (e.g., `list_users`) and verify auth works before building more actions.

### Step 3: Connect Account & Test Auth

Most providers offer sandbox or developer accounts for testing — check the provider's developer portal for signup, then generate API credentials (API key, OAuth app, etc.). Note any rate limits or restrictions on sandbox accounts.

Create test files for local development:

```bash theme={null}
# Create account config
echo '{"environment": "production", "provider": "provider"}' > account.json

# Create credentials (gitignore this!)
echo '{"apiKey": "your_sandbox_api_key"}' > credentials.json
```

<Tip>
  Keep sandbox credentials separate from production. Store them in a `credentials.json` file that's gitignored.
</Tip>

Test authentication:

```bash theme={null}
stackone run \
  --connector connectors/provider/provider.connector.s1.yaml \
  --account account.json \
  --credentials credentials.json \
  --action-id list_users \
  --debug
```

<Accordion title="Alternative: push and link an account">
  If you prefer, push the connector and create a linked account in the StackOne dashboard (see [Getting Started](/guides/introduction) guide). Then use `--account-id` instead of local credential files:

  ```bash theme={null}
  stackone push connectors/provider/ --profile <profile-label>
  # Create the linked account in the dashboard, then:
  stackone run \
    --connector connectors/provider/provider.connector.s1.yaml \
    --account-id your-linked-account-id \
    --action-id list_users
  ```

  `<profile-label>` is the name you set when running `stackone init` (see [Setup](#setup)).
</Accordion>

### Step 4: Build Actions

With auth working, build out your actions. See [Common Step Functions](#common-step-functions) for patterns.

### Step 5: Iterate

1. Validate syntax: `stackone validate connectors/provider/`
2. Test actions: `stackone run --debug ...`
3. Fix issues and repeat

***

## Common Step Functions

### `request` - Single HTTP Request

Use for GET single resource, POST create, PUT update operations:

```yaml theme={null}
steps:
  - stepId: get_user
    stepFunction:
      functionName: request
      parameters:
        url: /users/${inputs.id}
        method: get
        response:
          collection: false
          dataKey: data.user  # Extract nested response
```

### `paginated_request` - Cursor Pagination

Use for list endpoints with cursor-based pagination:

```yaml theme={null}
steps:
  - stepId: list_users
    stepFunction:
      functionName: paginated_request
      parameters:
        url: /users
        method: get
        response:
          dataKey: data.users      # Path to data array
          nextKey: meta.next_cursor # Path to pagination cursor
          indexField: id            # Unique ID field in each record
        iterator:
          key: cursor              # Parameter name API expects
          in: query                # Send cursor as query param
        args:
          - name: limit
            value: "100"
            in: query
```

<Warning>
  **Verify paths with `--debug`** before assuming response structure. Common mistake: using `dataKey: users` when the actual path is `dataKey: data.users`.
</Warning>

### `map_fields` - Transform Data (Unified Connectors)

Transform provider response to your schema:

```yaml theme={null}
steps:
  - stepId: map_data
    stepFunction:
      functionName: map_fields
      version: "2"
      parameters:
        dataSource: $.steps.get_users.output.data
        fields:
          - targetFieldKey: id
            expression: $.user_id
            type: string
          - targetFieldKey: email
            expression: $.email_address
            type: string
          - targetFieldKey: full_name
            expression: "{{$.first_name + ' ' + $.last_name}}"
            type: string
          - targetFieldKey: status
            expression: $.account_status
            type: enum
            enumMapper:
              matcher:
                - matchExpression: '{{$.account_status == "ACTIVE"}}'
                  value: active
                - matchExpression: '{{$.account_status == "INACTIVE"}}'
                  value: inactive
```

<Note>
  Always use `version: "2"` for `map_fields` and `typecast` steps.
</Note>

### `typecast` - Apply Type Conversions

Apply after `map_fields` to ensure correct types:

```yaml theme={null}
steps:
  - stepId: typecast_data
    stepFunction:
      functionName: typecast
      version: "2"
      parameters:
        dataSource: $.steps.map_data.output.data
        fields:
          - targetFieldKey: id
            type: string
          - targetFieldKey: created_at
            type: datetime_string
          - targetFieldKey: is_active
            type: boolean
```

### Cursor Pagination with Dynamic Page Size

For list actions where callers can specify page size, use the dual-condition pattern:

```yaml theme={null}
inputs:
  - name: page_size
    type: number
    in: query
    required: false
    description: Results per page (max 100)
  - name: cursor
    type: string
    in: query
    required: false
    description: Pagination cursor

cursor:
  enabled: true
  pageSize: 50

steps:
  - stepId: get_data
    stepFunction:
      functionName: request
      parameters:
        url: /items
        method: get
        args:
          # Use page_size if provided
          - name: limit
            value: $.inputs.page_size
            in: query
            condition: "{{present(inputs.page_size)}}"
          # Otherwise use default
          - name: limit
            value: 50
            in: query
            condition: "{{!present(inputs.page_size)}}"
          # Pass cursor when present
          - name: cursor
            value: $.inputs.cursor
            in: query
            condition: "{{present(inputs.cursor)}}"

result:
  data: $.steps.get_data.output.data.items
  next: $.steps.get_data.output.data.meta.next_cursor
```

***

## StackOne CLI Examples

For the full command list, see the [CLI Reference](/guides/connector-engine/cli-reference). The examples below cover the patterns you'll use most while iterating on your first connector.

### Validate as you build

Watch mode re-runs validation on every save:

```bash theme={null}
stackone validate connectors/provider/ --watch
```

### Test actions with parameters

`--params` accepts a structured JSON object with these top-level keys, each corresponding to an input's `in:` location in the action's YAML:

* `path` — `in: path` inputs (URL path parameters)
* `queryParams` — `in: query` inputs
* `header` — `in: headers` inputs (note: singular `header`)
* `body` — `in: body` inputs

Place every value under the key that matches the input's `in:` location:

```bash theme={null}
stackone run \
  --connector connectors/provider/provider.connector.s1.yaml \
  --account-id linked-account-id \
  --action-id get_employee \
  --params '{"path": {"id": "emp_123"}, "queryParams": {"include": "manager"}}'
```

### Push when ready

```bash theme={null}
stackone push connectors/provider/ --profile <profile-label>
```

`<profile-label>` is the name you set when running `stackone init` (see the [setup section](#setup)). Create separate profiles for staging vs. production and swap the label as needed.

***

## Debugging

### Enable Debug Mode

Add `--debug` to any `stackone run` command to surface:

* The raw HTTP request sent to the provider (URL, method, headers, body)
* The full response body before any mapping is applied
* The inputs and outputs of each step in the connector
* The resolved values of any JSONPath or JEXL expressions

```bash theme={null}
stackone run \
  --connector connectors/provider/provider.connector.s1.yaml \
  --account-id linked-account-id \
  --action-id list_employees \
  --debug
```

### Debug Empty or Incorrect Results

When mapping produces unexpected results:

<Steps>
  <Step title="Test raw response first">
    Temporarily modify your `result` block to return raw data:

    ```yaml theme={null}
    result:
      data: $.steps.get_employees.output.data  # Raw, before map_fields
    ```
  </Step>

  <Step title="Verify response structure">
    Run with `--debug` and examine the actual paths:

    ```bash theme={null}
    stackone run --debug ... | jq '.steps.get_employees.output'
    ```
  </Step>

  <Step title="Add fields incrementally">
    Start with one field in `map_fields`, verify it works, then add more.
  </Step>

  <Step title="Check expression context">
    For inline fields in `map_fields`, expressions reference fields directly (`$.email`), not with step prefix (`$.get_employees.email`).
  </Step>
</Steps>

### Common Issues

| Symptom                      | Likely Cause                    | Fix                                               |
| ---------------------------- | ------------------------------- | ------------------------------------------------- |
| 401 Unauthorized             | Invalid credentials             | Check API key, regenerate if needed               |
| Empty data array             | Wrong `dataKey` path            | Use `--debug` to verify actual response structure |
| Null field values            | Incorrect expression path       | Verify nested paths match actual response         |
| Pagination returns same data | Wrong `iterator.key`            | Check API docs for expected cursor parameter name |
| Enum not translated          | `matchExpression` case mismatch | Provider might return `"ACTIVE"` not `"Active"`   |

***

## Error Mapping

Map provider-specific errors to meaningful responses using error handlers:

```yaml theme={null}
errorHandlers:
  - condition: '{{response.status == 404}}'
    message: "Resource not found"
    code: NOT_FOUND
  - condition: '{{response.status == 429}}'
    message: "Rate limit exceeded. Retry after {{response.headers.retry-after}} seconds"
    code: RATE_LIMITED
  - condition: '{{response.status == 403}}'
    message: "Insufficient permissions for this operation"
    code: FORBIDDEN
```

For unified connectors, map provider error codes to standard error responses:

```yaml theme={null}
errorHandlers:
  - condition: '{{response.body.error.code == "INVALID_TOKEN"}}'
    message: "Authentication failed - token may be expired"
    code: UNAUTHORIZED
  - condition: '{{response.body.error.code == "MISSING_SCOPE"}}'
    message: "Missing required permission: {{response.body.error.required_scope}}"
    code: FORBIDDEN
```

***

## Manual Testing Methods

Beyond `stackone run`, you have additional testing options:

### Action Request Tester (Dashboard)

The StackOne dashboard includes an Action Request Tester for testing deployed connectors:

1. Navigate to your project in the dashboard
2. Select a linked account
3. Choose an action and provide parameters
4. Execute and view results

This tests the deployed connector version against real credentials.

### RPC Calls via API

Test actions programmatically using the StackOne API:

```bash theme={null}
curl -X POST "https://api.stackone.com/unified/actions/execute" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-account-id: your-linked-account-id" \
  -d '{
    "action_id": "provider_list_employees",
    "params": {
      "page_size": 10
    }
  }'
```

<Warning>
  Actions only appear in the Request Tester if they're enabled in your connector profile. If you don't see an action, edit your connector profile and enable it.
</Warning>

### MCP Testing (AI Agents)

If using Claude Code or similar, test actions conversationally:

```
Test the list_employees action for the provider connector.
Use page_size of 5 and verify the response includes id, name, and email fields.
```

The AI agent will execute the action and validate results.

***

## Unified Connector Checklist

For schema-based connectors, verify:

<AccordionGroup>
  <Accordion title="Schema Definition">
    * [ ] Target schema documented before building
    * [ ] All required fields identified
    * [ ] Field types specified (string, number, enum, datetime\_string)
    * [ ] Enum values defined with mappings
  </Accordion>

  <Accordion title="Field Mapping">
    * [ ] `fieldConfigs` map all schema fields
    * [ ] `targetFieldKey` uses YOUR schema names (not provider names)
    * [ ] Nested paths verified against actual response
    * [ ] Enum mappings handle all provider values + default case
  </Accordion>

  <Accordion title="Pagination">
    * [ ] `cursor.enabled: true` for list actions
    * [ ] `dataKey` path verified with `--debug`
    * [ ] `nextKey` path verified with `--debug`
    * [ ] `result.next` returns cursor for next page
    * [ ] Tested: first page, next page, last page, empty results
  </Accordion>

  <Accordion title="Steps">
    * [ ] `map_fields` step with `version: "2"`
    * [ ] `typecast` step with `version: "2"`
    * [ ] Correct `dataSource` references between steps
  </Accordion>
</AccordionGroup>

***

## Optimizing Agent Performance

The connector building agent starts with baseline capabilities. As you build connectors, you can improve agent performance by creating **custom skills** that encode your specific use cases and schemas.

### The Optimization Workflow

```mermaid theme={null}
flowchart LR
    A[Build First Connectors] --> B[Identify Patterns]
    B --> C[Create Skills]
    C --> D[Agent Uses Skills]
    D --> E[Faster, More Accurate Builds]
```

### Why Create Custom Skills?

| Without Skills                         | With Skills                                   |
| -------------------------------------- | --------------------------------------------- |
| Agent asks for schema every time       | Agent auto-loads your schema skill            |
| Generic action structures              | Actions match your specific requirements      |
| Manual field mapping decisions         | Consistent mapping patterns across connectors |
| Repeated explanations of your use case | Agent understands context immediately         |

### Creating Schema Skills

After building your first few connectors, extract your schema into a reusable skill:

```
.claude/skills/schemas/
└── my-use-case-schema.md
```

**Example schema skill:**

```markdown theme={null}
---
name: Employee Sync Schema
description: Target schema for employee data synchronization
category: hris
---

# Employee Sync Schema

## Target Schema

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| id | string | yes | Unique identifier |
| email | string | yes | Primary email |
| first_name | string | yes | |
| last_name | string | yes | |
| status | enum | yes | Values: active, inactive, terminated |
| department | string | no | |
| hire_date | datetime_string | no | ISO 8601 format |

## Enum Mappings

### status
| Provider Value | Schema Value |
|----------------|--------------|
| Active, active, ACTIVE | active |
| Inactive, inactive, INACTIVE | inactive |
| Terminated, terminated, TERMINATED | terminated |
| * (default) | unknown |
```

Once created, the agent automatically uses this schema for future unified builds — no questions needed.

### Recommended Progression

<Steps>
  <Step title="Build 2-3 Connectors">
    Use the baseline agent to build your first connectors. Note patterns in your requirements.
  </Step>

  <Step title="Create Schema Skills">
    Extract your target schemas into `.claude/skills/schemas/`. Include field definitions, types, and enum mappings.
  </Step>

  <Step title="Document Use-Case Patterns">
    Create skills that describe your specific integration patterns, endpoint preferences, or data transformation rules.
  </Step>

  <Step title="Iterate and Refine">
    As you build more connectors, update skills based on edge cases and lessons learned.
  </Step>
</Steps>

<Tip>
  Skills are stored in `.claude/skills/` in the connectors-template repository. The agent reads these automatically when relevant to the current task.
</Tip>

***

## Next Steps

<CardGroup>
  <Card title="Connector Structure" icon="book" href="/guides/connector-engine/connector-structure">
    Detailed YAML structure reference
  </Card>

  <Card title="Expression Language" icon="function" href="/guides/connector-engine/expression-language">
    JSONPath, JEXL, and string interpolation
  </Card>

  <Card title="YAML Reference" icon="file-code" href="/guides/connector-engine/connector-yaml-reference">
    Complete property documentation
  </Card>

  <Card title="CI/CD Setup" icon="github" href="/guides/connector-engine/github-workflow">
    Automated deployment with GitHub Actions
  </Card>
</CardGroup>


# CLI Reference
Source: https://docs.stackone.com/guides/connector-engine/cli-reference

StackOne CLI commands for building, validating, testing, and deploying connectors

The StackOne CLI (`@stackone/cli`) provides commands for building, validating, testing, and deploying custom connectors.

<Card title="Full Documentation" icon="npm" href="https://www.npmjs.com/package/@stackone/cli">
  Complete CLI documentation on npm
</Card>

## Installation

```bash theme={null}
npm install -g @stackone/cli
```

***

## Command Reference

### Agent Commands

Configure the StackOne MCP server for AI coding assistants like Claude, Cursor, and Windsurf.

| Command                         | Description                                   |
| ------------------------------- | --------------------------------------------- |
| `stackone agent setup --global` | Configure MCP tools globally in `~/.stackone` |
| `stackone agent setup --local`  | Configure MCP tools for current project only  |
| `stackone agent cleanup`        | Remove stored credentials and configuration   |

```bash theme={null}
# Global setup - configures MCP server for all projects (recommended)
stackone agent setup --global

# Project-scoped setup - configures MCP server for current directory
stackone agent setup --local

# Remove all API keys and credentials
stackone agent cleanup
```

<Tip>
  Use `--global` setup when you want the StackOne MCP tools available across all your projects. Use `--local` for project-specific configurations.
</Tip>

***

### Connector Development

| Command                    | Description                                    |
| -------------------------- | ---------------------------------------------- |
| `stackone validate <path>` | Validate connector YAML syntax and structure   |
| `stackone run`             | Execute a connector action locally for testing |

```bash theme={null}
# Validate with watch mode
stackone validate ./my-connector/ --watch

# Run an action with local credentials
stackone run \
  --connector my-connector.connector.s1.yaml \
  --account account.json \
  --credentials credentials.json \
  --action-id list_employees \
  --debug

# Run with parameters
stackone run \
  --connector my-connector.connector.s1.yaml \
  --account account.json \
  --credentials credentials.json \
  --action-id get_employee \
  --params params.json

# Run custom action code (for testing action definitions)
stackone run \
  --connector my-connector.connector.s1.yaml \
  --account-id acme-corp-provider \
  --action ./custom-action.yaml

# Save output to file
stackone run \
  --connector my-connector.connector.s1.yaml \
  --account-id acme-corp-provider \
  --action-id list_employees \
  --output-file results.json
```

**Test file formats:**

<CodeGroup>
  ```json account.json theme={null}
  {
    "environment": "production",
    "provider": "provider"
  }
  ```

  ```json credentials.json (API Key) theme={null}
  {
    "apiKey": "your_api_key"
  }
  ```

  ```json credentials.json (OAuth2) theme={null}
  {
    "accessToken": "token",
    "refreshToken": "refresh_token",
    "clientId": "client_id",
    "clientSecret": "client_secret"
  }
  ```

  ```json params.json theme={null}
  {
    "employee_id": "12345"
  }
  ```
</CodeGroup>

<Tip>
  **Faster iteration:** Once your connector is pushed or an account is already linked, skip the credentials file and use `--account-id` instead:

  ```bash theme={null}
  stackone run \
    --connector my-connector.connector.s1.yaml \
    --account-id acme-corp-provider \
    --action-id list_employees
  ```

  This uses stored credentials from the linked account, making it easier to iterate on action logic without managing local credential files.

  **Note:** Using `--account-id` requires an API key with `connectors:read` scope.
</Tip>

### Deployment

<Note>
  Deployment commands require an API key with **Connectors** scopes. See [API Keys](/guides/api-keys#configure-api-key-scopes-optional) to generate one.
</Note>

| Command                            | Description                                            | Required Scope     |
| ---------------------------------- | ------------------------------------------------------ | ------------------ |
| `stackone push <path>`             | Upload connector to StackOne registry                  | `connectors:write` |
| `stackone pull`                    | Download connector files to local filesystem           | `connectors:read`  |
| `stackone drop <provider@version>` | Delete a connector version from registry               | `connectors:write` |
| `stackone get`                     | Retrieve connector configuration (YAML or JSON output) | `connectors:read`  |

```bash theme={null}
# Push using saved profile
stackone push ./my-connector/ --profile prod

# Push with API key directly
stackone push ./my-connector/ --api-key v1.eu1.xxxxx

# Pull connector files to local directory
stackone pull --connector my_provider --output ./connectors/

# Pull specific version
stackone pull --connector my_provider@1.0.0 --output ./connectors/

# Get connector config as YAML (default)
stackone get --connector my_provider

# Get connector config from a linked account
stackone get --account-id acme-corp-provider --format json --output-file config.json
```

***

### Configuration

| Command            | Description                                     |
| ------------------ | ----------------------------------------------- |
| `stackone init`    | Configure authentication profiles interactively |
| `stackone version` | Show version with update check                  |
| `stackone update`  | Update CLI to latest version                    |

```bash theme={null}
# Interactive setup (prompts for profile name and API key)
stackone init

# Setup for different environments
stackone init --env staging
stackone init --env production

# Check version and available updates
stackone version

# Update to latest version
stackone update
```

***

## Environment Variables

| Variable                   | Description                                    |
| -------------------------- | ---------------------------------------------- |
| `STACKONE_AGENT_MCP_TOKEN` | MCP server access token (set by `agent setup`) |

<Note>
  API keys are passed via `--api-key` flag or stored in your profile configuration, not as environment variables.
</Note>

***

## Next Steps

<CardGroup>
  <Card title="Build Connectors" icon="rocket" href="/guides/connector-engine/introduction">
    Get started building connectors
  </Card>

  <Card title="CI/CD Setup" icon="github" href="/guides/connector-engine/github-workflow">
    Automated deployment with GitHub Actions
  </Card>
</CardGroup>


# Connector Structure
Source: https://docs.stackone.com/guides/connector-engine/connector-structure

Learn how Falcon connectors are structured — file organization, authentication, actions, step functions, and expressions

This guide walks through the structure of StackOne's Falcon connectors — how files are organized, how authentication works, how actions and steps fit together, and how expressions let you wire data between them. For detailed property-by-property documentation, see the [YAML Reference](/guides/connector-engine/connector-yaml-reference). For working examples, see the [connectors-template repository](https://github.com/StackOneHQ/connectors-template).

***

## File Structure

Connectors are organized into a main connector file and (optionally) partial files for each resource:

```
connectors/{provider}/
├── {provider}.connector.s1.yaml           # Main connector (auth, metadata)
└── {provider}.{resource}.s1.partial.yaml  # Actions for each resource
```

**Naming conventions:**

* Use kebab-case for file names
* Reference partials in the main file using `$ref: provider.resource`
* Add references in alphabetical order (not required, but recommended for readability)

***

## Main Connector File

The main connector file defines metadata, authentication, and references to action partials.

```yaml theme={null}
StackOne: 1.0.0
info:
  title: Provider Name
  key: provider
  version: 1.0.0
  assets:
    icon: https://stackone-logos.com/api/provider/filled/png
  description: Brief description of the provider

baseUrl: https://api.provider.com/v1

rateLimit:
  mainRatelimit: 10  # Requests per second

context: "Provider API documentation: https://api.provider.com/docs"

authentication:
  - custom:
      # ... authentication config

actions:
  - $ref: provider.users
  - $ref: provider.files
```

### Info Section

| Field         | Required | Description                                                                        |
| ------------- | -------- | ---------------------------------------------------------------------------------- |
| `title`       | Yes      | Display name shown in the StackOne Hub and dashboard                               |
| `key`         | Yes      | Unique lowercase identifier used in action names (e.g., `bamboohr_list_employees`) |
| `version`     | Yes      | Semantic version for tracking connector changes                                    |
| `assets.icon` | No       | URL to provider logo (displayed in Hub and dashboard)                              |
| `description` | No       | Brief description for documentation and AI context                                 |

<Accordion title="When to use each field">
  * **`title`**: User-facing name. Use the official provider name (e.g., "BambooHR" not "Bamboo HR")
  * **`key`**: Machine-readable identifier. Must be lowercase with underscores. Cannot be changed after deployment without breaking existing integrations
  * **`version`**: Increment when making changes. Use semantic versioning: major.minor.patch
  * **`assets.icon`**: Use `https://stackone-logos.com/api/{key}/filled/png` for consistent styling
  * **`description`**: Keep concise. Used by AI agents for context when discovering connectors
</Accordion>

### Base URL

The `baseUrl` defines the root URL for all API requests. It supports credential interpolation for providers with dynamic domains.

```yaml theme={null}
# Static base URL
baseUrl: https://api.provider.com/v1

# Dynamic subdomain from credentials
baseUrl: https://${credentials.subdomain}.api.provider.com/v2

# Region-specific endpoint
baseUrl: https://api.${credentials.region}.provider.com/v1
```

<Accordion title="When to use dynamic baseUrl">
  Use credential interpolation when the provider requires:

  * **Customer-specific subdomains**: Many B2B SaaS products use `{company}.provider.com` URLs
  * **Region selection**: Some providers have separate endpoints per region (US, EU, APAC)
  * **Environment switching**: Sandbox vs production endpoints

  The interpolated values come from `configFields` in your authentication config. These are fields your customer fills in when connecting their account.
</Accordion>

***

## Authentication

Authentication is defined once in the main connector file. All actions inherit it.

### Setup vs Config Fields

| Field Type     | Who Fills It        | When                         | Example                          |
| -------------- | ------------------- | ---------------------------- | -------------------------------- |
| `setupFields`  | You (the developer) | Dashboard integration config | Client ID, Client Secret, Scopes |
| `configFields` | Your customer       | Hub account connection       | API Token, Subdomain             |

<Accordion title="Choosing between setupFields and configFields">
  **Use `setupFields` for:**

  * OAuth client credentials (Client ID, Client Secret)
  * Scopes that you control
  * API keys that belong to your app, not the end user
  * Values you configure once in the StackOne dashboard

  **Use `configFields` for:**

  * Customer's own API tokens or keys
  * Customer-specific identifiers (subdomain, account ID, workspace ID)
  * Any value that differs per customer connection
  * Values the customer enters in the Hub when linking their account

  **Field properties:**

  * `secret: true`: Masks the field value and encrypts storage (use for tokens, keys, passwords)
  * `required: true`: Field must be filled before connection can complete
  * `placeholder`: Shows example format without exposing real values
  * `tooltip`: Additional help text shown on hover
</Accordion>

### Example: API Key Authentication

```yaml theme={null}
authentication:
  - custom:
      type: custom
      label: API Key
      support:
        link: https://your-connection-guide-url-here.com
        description: Steps require Admin privileges
      authorization:
        type: bearer
        token: $.credentials.apiKey
      configFields:
        - key: apiKey
          label: API Key
          type: password
          required: true
          secret: true
          placeholder: sk_live_xxxxx
          description: Generate in Settings > API Keys
      environments:
        - key: production
          name: Production
      testActionsIds:
        - list_users
```

### Other Authentication Types

The Falcon engine supports several authorization types:

| Type               | `authorization.type`     | Use Case                                                            |
| ------------------ | ------------------------ | ------------------------------------------------------------------- |
| **Bearer token**   | `bearer`                 | API key or OAuth access token in `Authorization: Bearer` header     |
| **Basic auth**     | `basic`                  | Username/password encoded as `Authorization: Basic` header          |
| **Custom headers** | `none` + `customHeaders` | Provider-specific header-based auth                                 |
| **OAuth 2.0**      | `oauth2`                 | Full OAuth flow with authorization URL, token exchange, and refresh |

<Tip>
  For complete authentication examples including OAuth 2.0 with token refresh, see the [YAML Reference — Authentication](/guides/connector-engine/connector-yaml-reference#authentication).
</Tip>

***

## Actions

Actions define the operations your connector can perform. Each action consists of metadata, inputs, steps, and result configuration.

### Action Structure

```yaml theme={null}
- actionId: list_users
  categories:
    - hris
  actionType: list
  schema: users
  label: List Users
  description: Get all users with pagination
  context: https://api.provider.com/docs/users/list
  entrypointUrl: /users
  entrypointHttpMethod: get
  inputs:
    - name: page_size
      type: number
      in: query
      required: false
      description: Results per page (max 100)
  steps:
    - stepId: fetch_users
      stepFunction:
        functionName: request
        parameters:
          url: /users
          method: get
  result:
    data: $.steps.fetch_users.output.data
```

| Field                  | Required    | Description                                                                                                                                                |
| ---------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `actionId`             | Yes         | Unique identifier within the connector. Forms the action name: `{connector_key}_{actionId}`                                                                |
| `categories`           | Yes         | Array of verticals this action belongs to (e.g., `hris`, `ats`, `crm`). See [YAML Reference](/guides/connector-engine/connector-yaml-reference#categories) |
| `actionType`           | Yes         | Identifies the type of the action (`list`, `get`, `create`, `update`, `delete`, `custom`)                                                                  |
| `schema`               | Conditional | Required for unified actions. Specifies which StackOne schema to map to                                                                                    |
| `label`                | Yes         | Human-readable name shown in Actions Explorer and AI tool descriptions                                                                                     |
| `description`          | Yes         | Explains what the action does. Used by AI agents for tool selection                                                                                        |
| `context`              | No          | URL to provider API docs. Helps AI agents understand the action                                                                                            |
| `entrypointUrl`        | No          | Alternative to defining URL in steps. The main endpoint path                                                                                               |
| `entrypointHttpMethod` | No          | Alternative to defining method in steps. HTTP method to use                                                                                                |

<Accordion title="How these fields affect your action">
  * **`actionId`**: Keep it descriptive and follow the pattern `{verb}_{resource}` (e.g., `list_users`, `get_employee`, `create_candidate`). Cannot be changed after deployment.
  * **`categories`**: Determines where the action appears in the Actions Explorer. An action can belong to multiple categories.
  * **`actionType`**: Choosing `custom` is fastest since no schema mapping is needed. Use unified types (`list`, `get`, etc.) when you want cross-provider compatibility.
  * **`schema`**: Must match a StackOne schema name (e.g., `users`, `employees`, `candidates`). Only required when `actionType` is unified.
  * **`label` + `description`**: These appear in the Actions Explorer and are sent to AI agents. Write them for humans, not machines.
  * **`context`**: Adding the provider's API doc URL helps the Builder Agent and AI tools understand edge cases.
</Accordion>

### Action Types

| Type            | Description                                                         |
| --------------- | ------------------------------------------------------------------- |
| `list`          | Retrieve multiple records, typically with pagination                |
| `get`           | Retrieve a single record by identifier                              |
| `create`        | Create a new resource                                               |
| `update`        | Modify an existing resource                                         |
| `delete`        | Remove a resource                                                   |
| `custom`        | Provider-specific operation that doesn't fit standard CRUD patterns |
| `refresh_token` | Internal OAuth token refresh (use with `internal` category)         |

Add a `schema` field to map provider data to StackOne's standardized schemas (e.g., `schema: employees`). Without `schema`, the action returns provider data as-is. See [Field Configs](#field-configs-unified-actions) for mapping details.

### Inputs

Inputs define the parameters your action accepts. Each input specifies a `name`, `type`, location (`in`), and whether it's `required`:

```yaml theme={null}
inputs:
  - name: id
    type: string
    in: path           # URL path parameter (/users/${inputs.id})
    required: true
  - name: status
    type: string
    in: query          # Query string (?status=active)
    required: false
  - name: email
    type: string
    in: body           # Request body field
    required: true
```

**Input types:** `string`, `number`, `boolean`, `datetime_string`, `object`
**Input locations:** `path`, `query`, `body`, `headers`

For full input property documentation including nested objects, see the [YAML Reference — Inputs](/guides/connector-engine/connector-yaml-reference#inputs).

***

## Step Functions

Step functions are the building blocks of actions. Each step performs one operation.

<Accordion title="Choosing the right step function">
  | Scenario                                      | Use                                                     |
  | --------------------------------------------- | ------------------------------------------------------- |
  | Single API call (get user, create record)     | `request`                                               |
  | List endpoint with cursor pagination          | `paginated_request`                                     |
  | List endpoint with offset/page pagination     | `request` + manual cursor handling                      |
  | Per-item API calls (detail fetch for each ID) | `request` with [iterator step](#iterator-steps-foreach) |
  | Transform provider data to output schema      | `map_fields`                                            |
  | Convert field types after mapping             | `typecast`                                              |
  | Merge results from multiple API calls         | `group_data`                                            |
  | Return hardcoded enum values                  | `static_values`                                         |
  | Combine static + dynamic data                 | `merge_collections`                                     |
  | Upload a file                                 | `upload_file`                                           |
  | Download a file                               | `download_file`                                         |
  | SOAP/XML API call                             | `soap_request`                                          |
  | Invoke an AWS Lambda function                 | `code_execution_lambda`                                 |

  **Common patterns:**

  * **GET single resource**: `request` → `result`
  * **LIST with pagination**: `paginated_request` → `result`
  * **Unified action**: `request` → `map_fields` → `typecast` → `result`
  * **Multi-source data**: `request` (x2) → `group_data` → `result`
  * **Per-item enrichment**: `request` → iterator `request` → `group_data` → `result`
  * **Static + dynamic merge**: `static_values` + `request` → `merge_collections` → `result`
</Accordion>

### `request` - HTTP Requests

Make a single HTTP request to the provider API. Use `args` to pass headers, query parameters, and body fields. Use `response.dataKey` to extract nested data from the response.

```yaml theme={null}
steps:
  - stepId: get_user
    description: Fetch user by ID
    stepFunction:
      functionName: request
      parameters:
        url: /users/${inputs.id}
        method: get
        args:
          - name: include_details
            value: "{{inputs.include_details}}"
            in: query
            condition: "{{present(inputs.include_details)}}"
        response:
          collection: false
          dataKey: user
```

<Warning>
  Always use `args` for request parameters. Never use a direct `body` field.
</Warning>

### `paginated_request` - Cursor Pagination

Automatically fetches all pages using cursor-based pagination. StackOne handles cursor tracking, page assembly, and continuation logic.

```yaml theme={null}
steps:
  - stepId: list_users
    stepFunction:
      functionName: paginated_request
      parameters:
        url: /users
        method: get
        response:
          dataKey: results       # Where to find the data array
          nextKey: nextCursor    # Where to find the next cursor
        iterator:
          key: cursor            # Parameter name to pass cursor
          in: query              # Where to send it (query or body)
        args:
          - name: limit
            value: "100"
            in: query
```

**How it works:** Makes the initial request, extracts results from `response.dataKey`, checks `response.nextKey` for a continuation cursor, and repeats until no cursor is returned. All pages are combined automatically.

<Warning>
  **Only use `paginated_request` for cursor-based pagination.** For offset or page-based pagination, use a regular `request` step with manual cursor handling.
</Warning>

### `map_fields` - Transform Data

Transform provider response data into your output schema. Takes a `dataSource` (typically a previous step's output), evaluates an `expression` per field against each record, and converts to the specified `type`.

```yaml theme={null}
steps:
  - stepId: map_data
    description: Map user data
    stepFunction:
      functionName: map_fields
      version: "2"
      parameters:
        dataSource: $.steps.fetch_users.output.data
        fields:
          - targetFieldKey: id
            expression: $.user_id
            type: string
          - targetFieldKey: full_name
            expression: "{{$.first_name + ' ' + $.last_name}}"
            type: string
          - targetFieldKey: is_active
            expression: $.status == 'active'
            type: boolean
```

Supports enum mapping, nested objects, and JEXL expressions for complex transformations. See [YAML Reference — map\_fields](/guides/connector-engine/connector-yaml-reference#map_fields) for the full list of field config options.

### `typecast` - Type Conversion

Apply type conversions to data. Used for unified actions.

```yaml theme={null}
steps:
  - stepId: typecast_data
    description: Apply types
    stepFunction:
      functionName: typecast
      version: "2"
      parameters:
        dataSource: $.steps.map_data.output.data
        fields:
          - targetFieldKey: created_at
            type: datetime_string
          - targetFieldKey: salary
            type: number
          - targetFieldKey: is_manager
            type: boolean
```

### `group_data` - Combine Results

Merge data from multiple steps into a single dataset.

```yaml theme={null}
steps:
  - stepId: combine_data
    stepFunction:
      functionName: group_data
      parameters:
        stepsDataToGroup:
          - fetch_employees
          - fetch_contractors
        isSingleRecord: false
```

### `static_values` - Return Static Data

Return predefined values without making an API request. Useful for enum lookups or constant data.

```yaml theme={null}
steps:
  - stepId: ticket_types
    stepFunction:
      functionName: static_values
      parameters:
        values:
          - id: question
            name: Question
          - id: incident
            name: Incident
```

### `merge_collections` - Merge Arrays

Merge multiple data collections into a single array.

```yaml theme={null}
steps:
  - stepId: all_types
    stepFunction:
      functionName: merge_collections
      parameters:
        collections:
          - $.steps.static_types.output.data
          - $.steps.api_types.output.data
```

### `upload_file` / `download_file` - File Operations

Handle file uploads (multipart form) and downloads (with encoding options).

```yaml theme={null}
# Upload
- stepId: upload_document
  stepFunction:
    functionName: upload_file
    parameters:
      url: /files/upload
      method: post
      file:
        fieldName: file
        content: $.inputs.file_content
        filename: $.inputs.filename

# Download
- stepId: download_document
  stepFunction:
    functionName: download_file
    parameters:
      url: /files/${inputs.file_id}/content
      method: get
      encoding: base64
```

### `soap_request` - SOAP API

Make SOAP (XML) requests. Used for enterprise providers like Workday.

```yaml theme={null}
steps:
  - stepId: get_workers
    stepFunction:
      functionName: soap_request
      parameters:
        url: /Human_Resources
        method: post
        soapOperation: Get_Workers
        soapAction: http://example.com/Get_Workers
        namespaces:
          - namespaceIdentifier: bsvc
            namespace: urn:com.workday/bsvc
```

### `code_execution_lambda` - AWS Lambda Invocation

Invoke an AWS Lambda function and use its response as the step output. Use for custom transformations or provider-specific logic that doesn't fit other step functions. The `args` array is assembled into the JSON payload sent to the Lambda.

```yaml theme={null}
steps:
  - stepId: enrich_user
    stepFunction:
      functionName: code_execution_lambda
      parameters:
        lambdaName: my-lambda-function
        region: us-east-1
        invocationType: RequestResponse
        args:
          - name: userId
            value: $.inputs.user_id
          - name: count
            value: $.inputs.count
```

See [YAML Reference — code\_execution\_lambda](/guides/connector-engine/connector-yaml-reference#code_execution_lambda) for all parameters, invocation types, and output fields.

<Tip>
  For full parameter documentation on all step functions, see the [YAML Reference — Steps](/guides/connector-engine/connector-yaml-reference#steps).
</Tip>

***

## Iterator Steps (Foreach)

Iterator steps execute one or more step functions for each item in a collection. Use them when you need to make per-item API calls — for example, fetching detailed data for each record returned by a list endpoint.

### Structure

An iterator step is defined by adding the `iterator` property to a step. The `iterator` value is a JSONPath expression that resolves to an array.

```yaml theme={null}
steps:
  - stepId: get_employee_details
    description: Fetch detailed data for each employee
    iterator: $.steps.list_employees.output.data.employees[*].id
    stepFunction:
      functionName: request
      parameters:
        url: /employees/${iterator.item}
        method: get
        response:
          collection: false
```

### How It Works

1. The `iterator` expression is evaluated to produce an array
2. For each item in the array, the step function(s) execute
3. Inside the step, you can access:
   * `$.iterator.item` — the current array element
   * `$.iterator.index` — the current iteration index (0-based)
   * `$.iterator.current` — the output of the previous step function in the same iteration (when using `stepFunctions`)
4. All iteration outputs are collected into an array at `$.steps.{stepId}.output.data`

### Single Step Function

The most common pattern — make one API call per item:

```yaml theme={null}
steps:
  - stepId: list_employees
    description: Get all employee IDs
    stepFunction:
      functionName: request
      parameters:
        url: /employees
        method: get
        response:
          collection: true
          dataKey: employees

  - stepId: get_employee_details
    description: Fetch details for each employee
    iterator: $.steps.list_employees.output.data.employees[*].id
    stepFunction:
      functionName: request
      parameters:
        url: /employees/${iterator.item}
        method: get
        response:
          collection: false
```

### Multiple Step Functions

Use `stepFunctions` (plural) to execute a sequence of functions per iteration. Each function can access the output of the previous one via `$.iterator.current`:

```yaml theme={null}
steps:
  - stepId: enrich_employees
    description: Fetch and transform data for each employee
    iterator: $.steps.list_employees.output.data.employees[*].id
    stepFunctions:
      - functionName: request
        parameters:
          url: /employees/${iterator.item}/details
          method: get
          response:
            collection: false
      - functionName: request
        parameters:
          url: /employees/${iterator.item}/compensation
          method: get
          response:
            collection: false
```

<Warning>
  You must provide either `stepFunction` (singular) or `stepFunctions` (plural) — not both. The YAML validator enforces this.
</Warning>

### Conditional Iterator

Like regular steps, iterator steps support the `condition` and `ignoreError` properties:

```yaml theme={null}
steps:
  - stepId: get_employee_managers
    description: Fetch manager data if employees have managers
    iterator: $.steps.list_employees.output.data.employees[*]
    condition: '{{present(steps.list_employees.output.data.employees)}}'
    ignoreError: true
    stepFunction:
      functionName: request
      parameters:
        url: /employees/${iterator.item.managerId}
        method: get
        condition: '{{present(iterator.item.managerId)}}'
```

### Iterator Context Reference

| Expression                   | Description                                               |
| ---------------------------- | --------------------------------------------------------- |
| `$.iterator.item`            | Current item from the iterated array                      |
| `$.iterator.index`           | Current iteration index (0-based)                         |
| `$.iterator.current`         | Output from the previous step function in `stepFunctions` |
| `${iterator.item}`           | String interpolation of current item (for URLs)           |
| `${iterator.item.fieldName}` | Nested field from current item                            |

***

## Expression Syntax

The Falcon engine supports three expression formats for dynamic values. For the **complete expression language reference** including all built-in functions, operators, and detailed examples, see the [Expression Language](/guides/connector-engine/expression-language) page.

### JSONPath (Preferred)

Direct data access. **Use for any direct reference.**

```yaml theme={null}
# Credentials
token: $.credentials.apiKey

# Inputs
value: $.inputs.userId

# Step output
dataSource: $.steps.fetch_users.output.data
```

### String Interpolation (`${...}`)

Use for **embedding values within strings**.

```yaml theme={null}
# URL path parameters
url: /users/${inputs.id}

# Dynamic domains
baseUrl: https://${credentials.subdomain}.api.provider.com
```

### JEXL Expressions (`'{{...}}'`)

Use for **conditional logic and transformations**. Must be in single quotes.

```yaml theme={null}
# Conditionals
condition: '{{present(inputs.filter)}}'

# Default values
value: '{{inputs.limit ?? 100}}'

# Ternary operations
value: '{{$.count > 0 ? $.count : 0}}'
```

**Common functions:** `present()`, `missing()`, `includes()`, `join()`, `capitalize()`, `truncate()`, `regexMatch()`, `now()` — see [full reference](/guides/connector-engine/expression-language#built-in-functions).

***

## Conditional Arguments

Include arguments only when conditions are met:

```yaml theme={null}
args:
  - name: filter
    value: '{{inputs.filter}}'
    in: query
    condition: '{{present(inputs.filter)}}'

  - name: updated_since
    value: $.inputs.updated_after
    in: query
    condition: '{{present(inputs.updated_after)}}'

  - name: include_inactive
    value: "true"
    in: query
    condition: '{{inputs.include_inactive == true}}'
```

***

## Result

Define the action's response output.

**Read operations:**

```yaml theme={null}
result:
  data: $.steps.fetch_users.output.data
```

**Write operations:**

```yaml theme={null}
result:
  message: User created successfully
  data:
    id: '{{inputs.id}}'
```

**With pagination info:**

```yaml theme={null}
result:
  data: $.steps.list_users.output.data
  next: $.steps.list_users.output.next
```

***

## Field Configs (Unified Actions)

For unified actions (those with a `schema` field), `fieldConfigs` map provider response fields to StackOne's standardized schema:

```yaml theme={null}
- actionId: list_users
  actionType: list
  schema: users
  fieldConfigs:
    - targetFieldKey: id
      expression: $.accountId
      type: string
    - targetFieldKey: email
      expression: $.emailAddress
      type: string
    - targetFieldKey: status
      expression: $.userStatus
      type: enum
      enumMapper:
        matcher:
          - matchExpression: '{{$.userStatus == "ACTIVE"}}'
            value: active
          - matchExpression: '{{$.userStatus == "SUSPENDED"}}'
            value: inactive
```

For built-in enum matchers and full field config options, see the [YAML Reference — map\_fields](/guides/connector-engine/connector-yaml-reference#map_fields).

***

## Rate Limiting

Configure request throttling:

```yaml theme={null}
rateLimit:
  mainRatelimit: 10    # Max requests per second
```

***

## Validation

Validate connector files using the CLI:

```bash theme={null}
npm install -g @stackone/cli

stackone validate path/to/connector.s1.yaml
```

***

## Complete Example

```yaml theme={null}
# provider.connector.s1.yaml
StackOne: 1.0.0
info:
  title: Acme HR
  key: acme_hr
  version: 1.0.0
  assets:
    icon: https://stackone-logos.com/api/acme_hr/filled/png
  description: HR management platform

baseUrl: https://api.acme.com/v2

rateLimit:
  mainRatelimit: 10

authentication:
  - custom:
      type: custom
      label: API Key
      authorization:
        type: bearer
        token: $.credentials.apiKey
      configFields:
        - key: apiKey
          label: API Key
          type: password
          required: true
          secret: true
      environments:
        - key: production
          name: Production
      testActionsIds:
        - list_employees

actions:
  - $ref: acme_hr.employees
```

```yaml theme={null}
# provider.employees.s1.partial.yaml
- actionId: list_employees
  categories:
    - hris
  actionType: custom
  label: List Employees
  description: Get all employees with pagination
  context: https://api.acme.com/docs/employees
  inputs:
    - name: page_size
      type: number
      in: query
      required: false
      description: Results per page (max 100)
    - name: status
      type: string
      in: query
      required: false
      description: Filter by status (active, inactive)
  steps:
    - stepId: fetch_employees
      stepFunction:
        functionName: paginated_request
        parameters:
          url: /employees
          method: get
          response:
            dataKey: data
            nextKey: pagination.next_cursor
          iterator:
            key: cursor
            in: query
          args:
            - name: limit
              value: '{{inputs.page_size || 100}}'
              in: query
            - name: status
              value: '{{inputs.status}}'
              in: query
              condition: '{{present(inputs.status)}}'
  result:
    data: $.steps.fetch_employees.output.data

- actionId: get_employee
  categories:
    - hris
  actionType: custom
  label: Get Employee
  description: Get employee by ID
  context: https://api.acme.com/docs/employees/{id}
  inputs:
    - name: id
      type: string
      in: path
      required: true
      description: Employee ID
  steps:
    - stepId: fetch_employee
      stepFunction:
        functionName: request
        parameters:
          url: /employees/${inputs.id}
          method: get
  result:
    data: $.steps.fetch_employee.output.data
```

***

## Next Steps

<CardGroup>
  <Card title="Expression Language" icon="function" href="/guides/connector-engine/expression-language">
    Full reference for JSONPath, JEXL, and string interpolation
  </Card>

  <Card title="YAML Reference" icon="file-code" href="/guides/connector-engine/connector-yaml-reference">
    Complete property reference with impact analysis
  </Card>

  <Card title="Browse Examples" icon="code" href="https://github.com/StackOneHQ/connectors-template/">
    See real connector implementations
  </Card>

  <Card title="StackOne Agent" icon="robot" href="/guides/connector-engine/stackone-agent">
    Generate connectors with AI assistance
  </Card>
</CardGroup>


# Connector YAML Reference
Source: https://docs.stackone.com/guides/connector-engine/connector-yaml-reference

Complete reference for all connector YAML properties with examples and impact analysis

This reference documents every property available in connector YAML files. Each property includes its purpose, allowed values, real-world examples, and whether it affects the **UI** (Hub, Dashboard), **MCP** (tool declarations), or **both**.

<Note>
  **Impact Legend:**

  * 🖥️ **UI** - Affects StackOne Hub, Dashboard, or Connect flows
  * 🤖 **MCP** - Used in MCP tool declarations (`list tools`)
  * ⚙️ **Runtime** - Affects API request execution
</Note>

***

## File Structure

Connectors use a modular file structure:

```
connectors/
└── {provider}/
    ├── {provider}.connector.s1.yaml      # Main connector file
    ├── {provider}.{resource1}.s1.partial.yaml  # Actions partial
    └── {provider}.{resource2}.s1.partial.yaml  # Actions partial
```

<Accordion title="Why use partial files?">
  Partial files keep connectors maintainable by splitting actions into logical groups. The main connector file handles authentication and metadata, while partials contain resource-specific actions.

  **How it works:** The CLI merges all partials into a single connector definition during `stackone push`. The `$ref` syntax tells the merger which partials to include. File naming must follow the pattern `{provider}.{resource}.s1.partial.yaml` for auto-discovery.

  **Example from BambooHR:**

  * `bamboohr.connector.s1.yaml` - Auth config
  * `bamboohr.employees.s1.partial.yaml` - Employee actions
  * `bamboohr.timeoff.s1.partial.yaml` - Time-off actions
</Accordion>

***

## Root Properties

### `StackOne`

**Impact:** ⚙️ Runtime

The schema version for the connector file format.

| Value   | Description                        |
| ------- | ---------------------------------- |
| `1.0.0` | Current and only supported version |

```yaml theme={null}
StackOne: 1.0.0
```

<Accordion title="How version affects processing">
  The version determines which parser and validator the runtime uses. Currently only `1.0.0` is supported. Future versions may introduce new properties or change behavior. Always use `1.0.0` for new connectors.
</Accordion>

***

## `info` Section

Metadata about the connector displayed in the UI and used for identification.

### `info.title`

**Impact:** 🖥️ UI

Human-readable provider name displayed in the Hub and Dashboard.

```yaml theme={null}
info:
  title: BambooHR
```

<Accordion title="UI display locations">
  The title appears in:

  * Integration Hub provider list
  * Dashboard connector cards
  * Account connection screens
  * Logs and audit trails

  Use the official product name with proper capitalization (e.g., "BambooHR" not "Bamboo HR" or "bamboohr").
</Accordion>

### `info.key`

**Impact:** 🖥️ UI | 🤖 MCP | ⚙️ Runtime

Unique identifier for the connector. Used in API calls, MCP tool names, and internal routing.

```yaml theme={null}
info:
  key: bamboohr
```

| Constraint | Description                                          |
| ---------- | ---------------------------------------------------- |
| Format     | Lowercase alphanumeric with underscores              |
| Uniqueness | Must be unique across all connectors                 |
| Stability  | Cannot change once deployed (breaks linked accounts) |

<Accordion title="How key is used throughout the system">
  The key is the primary identifier:

  **MCP:** Prefixes all action IDs → `bamboohr_list_employees`

  **API:** Used in account connections:

  ```bash theme={null}
  POST /accounts
  { "provider": "bamboohr", ... }
  ```

  **Runtime:** Routes requests to correct connector configuration.

  **Warning:** Changing a key after deployment breaks all existing linked accounts and API integrations.
</Accordion>

<Accordion title="Forking connectors and inheriting updates">
  When forking an existing StackOne connector, you can customize the connector name (`info.title`). However, if you want to inherit future StackOne updates to that connector, the `info.key` field must match the StackOne connector key.

  **Example:**
  If you fork StackOne's BambooHR connector:

  * ✅ You can change `info.title` to "Custom BambooHR"
  * ⚠️ Keep `info.key: bamboohr` to receive future updates from StackOne
  * ❌ Changing `info.key` to `custom_bamboohr` prevents automatic update inheritance

  **Recommendation:** When forking existing StackOne connectors, keep `info.key` identical to the original StackOne connector key if you want to inherit future improvements and bug fixes.
</Accordion>

### `info.version`

**Impact:** 🖥️ UI | ⚙️ Runtime

Connector version following semver format.

```yaml theme={null}
info:
  version: 1.0.0
```

<Accordion title="Version management best practices">
  Use semantic versioning:

  * **Major (1.x.x):** Breaking changes — auth changes, removed/renamed actions, changed response or request shape, or behavioural changes consumers may have relied on
  * **Minor (x.1.x):** New actions, new optional parameters, or new optional response fields
  * **Patch (x.x.1):** Bug fixes, description updates, internal refactors

  The version is displayed in the Dashboard and helps track deployed changes. Auth configs resolve to a connector version when linked accounts make requests — see [Connector Versioning](/guides/connector-versioning) for selection rules, pinning, and immutable versioning.
</Accordion>

### `info.assets.icon`

**Impact:** 🖥️ UI

URL to the provider's logo image. Displayed throughout the UI.

```yaml theme={null}
info:
  assets:
    icon: https://stackone-logos.com/api/bamboohr/filled/png
```

<Accordion title="Logo requirements and hosting">
  **Recommended:** Use StackOne's logo service at `https://stackone-logos.com/api/{provider}/filled/png`

  **Requirements:**

  * 24x24 pixels minimum
  * PNG or SVG format
  * Transparent background preferred
  * Hosted on HTTPS

  The logo appears in Hub listings, Dashboard cards, and account connection flows.
</Accordion>

### `info.description`

**Impact:** 🖥️ UI | 🤖 MCP

Brief description of the connector's purpose.

```yaml theme={null}
info:
  description: BambooHR connector for HRIS actions including employee data, time-off, and reporting
```

<Accordion title="Where description appears">
  **UI:** Shown in connector details panels and Hub listings.

  **MCP:** Included in connector metadata when clients query available integrations. Helps AI agents understand what the connector does.

  **Best practices:**

  * Keep under 200 characters
  * Mention key capabilities
  * Include category context (HRIS, CRM, etc.)
</Accordion>

***

## `baseUrl`

**Impact:** ⚙️ Runtime

The root URL for all API requests. Supports static URLs and dynamic interpolation.

### Static URL

```yaml theme={null}
baseUrl: 'https://api.bamboohr.com/api/gateway.php'
```

### Dynamic URL with credentials

```yaml theme={null}
baseUrl: 'https://api.bamboohr.com/api/gateway.php/${credentials.subdomain}/v1'
```

### Dynamic URL with config

```yaml theme={null}
baseUrl: 'https://${config.region}.api.provider.com/v2'
```

<Accordion title="URL interpolation and runtime resolution">
  Dynamic URLs use `${...}` string interpolation:

  **Available contexts:**

  * `${credentials.*}` - Values from setupFields/configFields
  * `${config.*}` - Configuration values
  * `${env.*}` - Environment variables (limited)

  **Example from BambooHR:**

  ```yaml theme={null}
  baseUrl: 'https://api.bamboohr.com/api/gateway.php/${credentials.subdomain}/v1'
  ```

  When a user enters subdomain `acme-corp`, the runtime resolves to:

  ```
  https://api.bamboohr.com/api/gateway.php/acme-corp/v1
  ```

  **Important:** Individual actions can override baseUrl in their step parameters for different API endpoints.
</Accordion>

***

## `rateLimit`

**Impact:** ⚙️ Runtime

Configure rate limiting to respect provider API limits.

```yaml theme={null}
rateLimit:
  mainRatelimit: 10
```

| Property        | Type   | Description             |
| --------------- | ------ | ----------------------- |
| `mainRatelimit` | number | Max requests per second |

<Accordion title="Rate limiting behavior">
  The runtime tracks requests per linked account and throttles when limits are reached. Requests exceeding the limit are queued and retried with exponential backoff.

  **Best practices:**

  * Set slightly below provider's documented limit
  * Check provider API docs for per-endpoint limits
  * Some providers have different limits for different endpoints

  **Note:** Rate limits apply per account, not globally across all accounts.
</Accordion>

***

## `resources`

**Impact:** 🖥️ UI

URL to the provider's API documentation. Displayed as a help link in the UI.

```yaml theme={null}
resources: https://documentation.bamboohr.com/reference
```

<Accordion title="Resource link usage">
  The link appears in:

  * Connector configuration screens
  * Troubleshooting guides
  * Developer documentation references

  Use the most relevant documentation URL (API reference preferred over marketing pages).
</Accordion>

***

## `documentation`

**Impact:** 🖥️ UI · 🤖 Agent context

Structured external references for the connector. Each entry has a required `title` and `url`, and an optional `description`. Rendered as a card grid on the connector's docs page and surfaced in the `/actions` API response.

```yaml theme={null}
documentation:
  references:
    - title: Microsoft Graph API
      url: https://learn.microsoft.com/en-us/graph/api/overview?view=graph-rest-1.0
      description: Full REST API reference for Microsoft Graph.
    - title: Build a bot for Microsoft Teams
      url: https://learn.microsoft.com/en-us/microsoftteams/platform/bots/what-are-bots
      description: Guide for building bots to leverage the messaging API for agentic use cases.
```

<Accordion title="documentation.references fields">
  | Field         | Required | Description                                  |
  | ------------- | -------- | -------------------------------------------- |
  | `title`       | Yes      | Display name for the link                    |
  | `url`         | Yes      | Full URL to the external resource            |
  | `description` | No       | One-sentence summary shown beneath the title |

  Use `documentation.references` for links that benefit both developers reading the docs and agents consuming the `/actions` API. The `resources` field (plain string URL) remains valid for a single legacy link; use `documentation.references` for structured, multi-link documentation.
</Accordion>

***

## `authentication` Section

Defines how end-users authenticate with the provider. Supports multiple auth methods per connector.

### Authentication Array Structure

```yaml theme={null}
authentication:
  - oauth2:
      type: oauth2
      label: OAuth 2.0
      # ... oauth config
  - api_key:
      type: custom
      label: API Key
      # ... api key config
```

<Accordion title="Multiple auth methods">
  When a connector has multiple authentication options:

  1. Users see all options in the Hub during connection
  2. Each method has independent credentials and setup flows
  3. Linked accounts store which method was used
  4. Runtime uses the appropriate auth handler based on account config

  **Example:** Slack offers both OAuth 2.0 (for apps) and Bot Token (for direct API access).
</Accordion>

<Tabs>
  <Tab title="OAuth 2.0">
    ## OAuth 2.0 Authentication

    **Impact:** 🖥️ UI | ⚙️ Runtime

    ```yaml theme={null}
    authentication:
      - oauth2:
          type: oauth2
          label: OAuth 2.0
          support:
            description: Login to your BambooHR account to connect.
            link: https://documentation.bamboohr.com/docs/getting-started
          authorization:
            type: oauth2
            authorizationUrl: 'https://bamboohr.com/oauth/authorize'
            authorizationParams:
              scope: '{{$.credentials.scopes ?? "employees:read"}}'
              client_id: $.credentials.clientId
              redirect_uri: '${apiHostUri}/connect/oauth2/bamboohr/callback'
            tokenUrl: 'https://bamboohr.com/oauth/token'
            token: $.credentials.accessToken
            includeBearer: true
            pkce: true
          setupFields:
            - key: clientId
              label: Client ID
              type: text
              required: true
              secret: false
          configFields:
            - key: subdomain
              label: Subdomain
              type: text
              required: true
          refreshAuthentication:
            action: # embedded refresh action
          environments:
            - key: production
              name: Production
          testActions:
            - action: list_employees
              required: true
    ```

    #### `type`

    | Value    | Description                             |
    | -------- | --------------------------------------- |
    | `oauth2` | OAuth 2.0 authorization code flow       |
    | `custom` | API Key, Basic Auth, or other non-OAuth |

    #### `label`

    **Impact:** 🖥️ UI

    Display name for this auth method in the Hub.

    ```yaml theme={null}
    label: OAuth 2.0
    ```

    #### `support`

    **Impact:** 🖥️ UI

    Help text and links shown during connection flow.

    ```yaml theme={null}
    support:
      description: Login to your BambooHR account to connect your data.
      link: https://documentation.bamboohr.com/docs/getting-started
    ```

    <Accordion title="Support section display">
      The support section helps users during the connection flow:

      * `description` appears as instructional text
      * `link` creates a "Learn more" button

      Use this to guide users who may not know how to set up the integration or where to find credentials.
    </Accordion>

    #### `authorization`

    **Impact:** ⚙️ Runtime

    OAuth flow configuration.

    ```yaml theme={null}
    authorization:
      type: oauth2
      authorizationUrl: 'https://provider.com/oauth/authorize'
      authorizationParams:
        scope: '{{$.credentials.scopes ?? "default:scope"}}'
        client_id: $.credentials.clientId
        redirect_uri: '${apiHostUri}/connect/oauth2/provider/callback'
      tokenUrl: 'https://provider.com/oauth/token'
      token: $.credentials.accessToken
      includeBearer: true
      pkce: true
    ```

    | Property              | Type     | Description                                  |
    | --------------------- | -------- | -------------------------------------------- |
    | `authorizationUrl`    | string   | Provider's OAuth authorize endpoint          |
    | `authorizationParams` | object   | Query params for authorization request       |
    | `tokenUrl`            | string   | Provider's token exchange endpoint           |
    | `token`               | JSONPath | Path to access token in credentials          |
    | `includeBearer`       | boolean  | Add "Bearer " prefix to Authorization header |
    | `pkce`                | boolean  | Enable PKCE (Proof Key for Code Exchange)    |

    <Accordion title="OAuth flow internals">
      **Authorization Flow:**

      1. User clicks "Connect" in Hub
      2. Runtime builds authorization URL with `authorizationParams`
      3. User redirects to provider, logs in, grants permissions
      4. Provider redirects back with authorization code
      5. Runtime exchanges code for tokens via `tokenUrl`
      6. Tokens stored in credentials for linked account

      **Expression types in authorizationParams:**

      * `$.credentials.*` - JSONPath to credential values
      * `${apiHostUri}` - StackOne callback URL base
      * `'{{expression ?? default}}'` - JEXL with fallback

      **PKCE:** Required by many providers for security. Generates `code_verifier` and `code_challenge` automatically.

      **Scopes:** The example `'{{$.credentials.scopes ?? "default:scope"}}'` lets users customize scopes in setupFields while providing sensible defaults.
    </Accordion>

    #### `setupFields`

    **Impact:** 🖥️ UI | ⚙️ Runtime

    Fields collected when configuring the connector (T1 - your app's credentials).

    ```yaml theme={null}
    setupFields:
      - key: clientId
        label: Client ID
        type: text
        required: true
        secret: false
        placeholder: 'your-client-id'
        description: Found in your app's OAuth settings.
        tooltip: Navigate to Settings > API > OAuth to find this.
      - key: clientSecret
        label: Client Secret
        type: password
        required: true
        secret: true
    ```

    | Property      | Type    | Description                                                  |
    | ------------- | ------- | ------------------------------------------------------------ |
    | `key`         | string  | Credential storage key (referenced as `$.credentials.{key}`) |
    | `label`       | string  | 🖥️ Field label in UI                                        |
    | `type`        | enum    | `text`, `password`, `url`                                    |
    | `required`    | boolean | Field must have a value                                      |
    | `secret`      | boolean | Encrypt at rest, mask in UI                                  |
    | `placeholder` | string  | 🖥️ Example value shown in empty field                       |
    | `description` | string  | 🖥️ Help text below field                                    |
    | `tooltip`     | string  | 🖥️ Hover/info icon text                                     |

    <Accordion title="setupFields vs configFields">
      **setupFields** - Credentials your team enters once when enabling the connector:

      * OAuth Client ID/Secret
      * API keys for your platform
      * Application-level settings

      **configFields** - Credentials each end-user enters during connection:

      * Their API keys
      * Account-specific settings (subdomain, region)
      * Personal access tokens

      **Storage:**

      * setupFields → Stored per connector profile
      * configFields → Stored per linked account

      **Security:**

      * `secret: true` → Encrypted at rest, never exposed in API responses
      * `type: password` → Masked in UI during entry
    </Accordion>

    #### `configFields`

    **Impact:** 🖥️ UI | ⚙️ Runtime

    Fields collected from end-users during connection (T2 - their credentials).

    ```yaml theme={null}
    configFields:
      - key: subdomain
        label: Company Subdomain
        type: text
        required: true
        placeholder: 'acme-corp'
        description: Your BambooHR subdomain (from your login URL)
    ```

    Same property options as `setupFields`.

    #### `refreshAuthentication`

    **Impact:** ⚙️ Runtime

    Embedded action for refreshing expired OAuth tokens.

    ```yaml theme={null}
    refreshAuthentication:
      action:
        actionId: refresh_token_bamboohr
        categories:
          - internal
        actionType: refresh_token
        label: Refresh Token
        description: Refresh BambooHR OAuth2 token
        steps:
          - stepId: refresh_request
            stepFunction:
              functionName: request
              parameters:
                url: '/oauth/token'
                method: post
                args:
                  - name: grant_type
                    value: refresh_token
                    in: body
                  - name: refresh_token
                    value: $.credentials.refreshToken
                    in: body
          - stepId: map_response
            stepFunction:
              functionName: map_fields
              version: '2'
              parameters:
                fields:
                  - targetFieldKey: accessToken
                    expression: $.access_token
                  - targetFieldKey: refreshToken
                    expression: $.refresh_token
                dataSource: $.steps.refresh_request.output.data
        result:
          data: $.steps.map_response.output.data
    ```

    <Accordion title="Token refresh mechanics">
      **When refresh happens:**

      1. An action fails with 401 Unauthorized
      2. Runtime checks if refreshAuthentication is configured
      3. Executes the embedded refresh action
      4. Updates stored credentials with new tokens
      5. Retries the original action

      **The refresh action must:**

      * Call the provider's token refresh endpoint
      * Map the response to credential format (accessToken, refreshToken, expiresIn)
      * Return data in `result.data`

      **Note:** The `categories: [internal]` hides this from MCP tool listings.
    </Accordion>

    #### `environments`

    **Impact:** 🖥️ UI

    Available deployment environments for this auth method.

    ```yaml theme={null}
    environments:
      - key: production
        name: Production
      - key: sandbox
        name: Sandbox
    ```

    <Accordion title="Multi-environment support">
      Environments let you offer sandbox/production toggles in the Hub. Some providers (like Salesforce) have separate OAuth apps and endpoints for sandbox vs production.

      The selected environment is available in expressions as `$.environment.key`.
    </Accordion>

    #### `testActions`

    **Impact:** 🖥️ UI | ⚙️ Runtime

    Actions executed to validate a connection after OAuth completes.

    ```yaml theme={null}
    testActions:
      - action: list_employees
        required: true
    ```

    | Property   | Type    | Description                      |
    | ---------- | ------- | -------------------------------- |
    | `action`   | string  | Action ID to execute             |
    | `required` | boolean | Connection fails if action fails |

    <Accordion title="Connection validation flow">
      After OAuth token exchange:

      1. Runtime executes each testAction in order
      2. If `required: true` and action fails → connection marked as failed
      3. If `required: false` and action fails → warning logged but connection succeeds

      **Best practices:**

      * Use a simple read action (list, get)
      * Test the most common use case
      * Avoid actions that modify data
    </Accordion>
  </Tab>

  <Tab title="Custom Auth (API Key, Basic)">
    ## Custom Authentication

    **Impact:** 🖥️ UI | ⚙️ Runtime

    ```yaml theme={null}
    authentication:
      - api_key:
          type: custom
          label: API Key
          support:
            description: Enter your BambooHR API key to connect.
          authorization:
            type: bearer
            token: $.credentials.apiKey
          configFields:
            - key: subdomain
              label: Subdomain
              type: text
              required: true
            - key: apiKey
              label: API Key
              type: password
              required: true
              secret: true
          environments:
            - key: production
              name: Production
          testActions:
            - action: list_employees
              required: true
    ```

    #### Authorization Types for Custom Auth

    ```yaml theme={null}
    # Bearer token
    authorization:
      type: bearer
      token: $.credentials.apiKey

    # Basic auth
    authorization:
      type: basic
      username: $.credentials.username
      password: $.credentials.password

    # Custom header
    authorization:
      type: bearer
      token: $.credentials.apiKey
      includeBearer: false  # Sends raw token without "Bearer " prefix
      customHeaders:
        X-Api-Key: $.credentials.apiKey
    ```

    | Type                              | Header Format                                        |
    | --------------------------------- | ---------------------------------------------------- |
    | `bearer`                          | `Authorization: Bearer {token}`                      |
    | `bearer` + `includeBearer: false` | `Authorization: {token}`                             |
    | `basic`                           | `Authorization: Basic base64({username}:{password})` |
    | `none`                            | No Authorization header                              |

    <Accordion title="Custom header injection">
      Use `customHeaders` for providers with non-standard auth:

      ```yaml theme={null}
      authorization:
        type: bearer
        token: $.credentials.accessToken
        customHeaders:
          Authorization: 'Bearer {{$.credentials.accessToken}}'
          X-Custom-Auth: '{{$.credentials.apiKey}}'
      ```

      Headers support both JSONPath (`$.credentials.*`) and JEXL (`'{{...}}'`) expressions.
    </Accordion>
  </Tab>
</Tabs>

***

## `actions` Section

Actions define the operations available through the connector. Use `$ref` to include partials.

### Action References

```yaml theme={null}
actions:
  $ref: bamboohr.employees
  $ref: bamboohr.timeoff
  $ref: bamboohr.reports
```

<Accordion title="How $ref resolution works">
  The CLI resolves `$ref` at build time:

  1. `$ref: bamboohr.employees` looks for `bamboohr.employees.s1.partial.yaml`
  2. Partial file must be in same directory as main connector
  3. Actions from partial are merged into main connector
  4. Multiple `$ref` statements combine all partials

  **Partial file structure:**

  ```yaml theme={null}
  # bamboohr.employees.s1.partial.yaml
  - actionId: list_employees
    # ... action config
  - actionId: get_employee
    # ... action config
  ```

  Note: Partials start with `-` (array items), not `actions:`.
</Accordion>

***

## Action Properties

Each action defines a single operation.

### `actionId`

**Impact:** 🤖 MCP | ⚙️ Runtime

Unique identifier for the action. Becomes the MCP tool name with provider prefix.

```yaml theme={null}
actionId: list_employees
```

**MCP tool name:** `bamboohr_list_employees`

| Constraint | Description                                          |
| ---------- | ---------------------------------------------------- |
| Format     | snake\_case, lowercase                               |
| Uniqueness | Must be unique within connector                      |
| Convention | `{verb}_{resource}` or `{verb}_{resource}_{variant}` |

<Accordion title="Action ID naming conventions">
  **Standard verbs:**

  * `list_*` - Get multiple records (paginated)
  * `get_*` - Get single record by ID
  * `create_*` - Create new record
  * `update_*` - Modify existing record
  * `delete_*` - Remove record
  * `search_*` - Query with filters

  **Examples:**

  * `list_employees` - List all employees
  * `get_employee` - Get employee by ID
  * `create_employee` - Create new employee
  * `search_employees_by_department` - Filtered search

  **MCP impact:** The full tool name is `{provider_key}_{actionId}`, so `bamboohr` + `list_employees` = `bamboohr_list_employees`.
</Accordion>

### `categories`

**Impact:** 🖥️ UI

Categories for filtering in the UI. Does not affect MCP.

```yaml theme={null}
categories:
  - hris
  - employees
```

| Category      | Description                              |
| ------------- | ---------------------------------------- |
| `hris`        | HR Information Systems                   |
| `ats`         | Applicant Tracking Systems               |
| `crm`         | Customer Relationship Management         |
| `lms`         | Learning Management Systems              |
| `marketing`   | Marketing automation                     |
| `filestorage` | File storage and documents               |
| `ticketing`   | Support ticketing                        |
| `messaging`   | Chat and messaging                       |
| `internal`    | Hidden from UI (used for refresh tokens) |

<Accordion title="Category filtering behavior">
  Categories enable filtering in:

  * Actions Explorer in Dashboard
  * AI Playground action selection
  * SDK `fetchTools({ categories: ['hris'] })`

  **Multiple categories:** An action can belong to multiple categories. It appears when any matching filter is applied.

  **`internal` category:** Actions with `categories: [internal]` are:

  * Hidden from UI listings
  * Not returned in MCP `list tools`
  * Still executable via direct API calls
  * Used for token refresh and internal operations
</Accordion>

### `actionType`

**Impact:** 🤖 MCP | ⚙️ Runtime

Determines the action's behavior pattern and response schema.

```yaml theme={null}
actionType: list
```

| Type            | Description              | Response Schema              |
| --------------- | ------------------------ | ---------------------------- |
| `custom`        | Provider-specific action | Raw provider response        |
| `list`          | Paginated list (unified) | `{ data: [], next: string }` |
| `get`           | Single record (unified)  | `{ data: object }`           |
| `create`        | Create record (unified)  | `{ data: object }`           |
| `update`        | Update record (unified)  | `{ data: object }`           |
| `delete`        | Delete record (unified)  | `{ success: boolean }`       |
| `refresh_token` | Token refresh (internal) | Credential object            |

<Accordion title="Unified vs Custom action types">
  **Unified types (list, get, create, update, delete):**

  * Enforce consistent response schemas across providers
  * Enable cross-provider compatibility
  * Support automatic pagination handling
  * Normalize error responses

  **Custom type:**

  * Returns raw provider response
  * Use for provider-specific features
  * No schema normalization
  * Full flexibility for unique endpoints

  **Example:** A `list` action always returns:

  ```json theme={null}
  {
    "data": [...],
    "next": "cursor_token_or_null"
  }
  ```

  While a `custom` action returns whatever the provider returns.
</Accordion>

### `label`

**Impact:** 🖥️ UI

Human-readable name displayed in the UI.

```yaml theme={null}
label: List Employees
```

<Accordion title="Label display locations">
  The label appears in:

  * Actions Explorer
  * AI Playground action selector
  * Request logs
  * Error messages

  **Best practices:**

  * Use title case
  * Start with verb (List, Get, Create, etc.)
  * Keep concise (under 30 characters)
</Accordion>

### `description`

**Impact:** 🖥️ UI | 🤖 MCP

Short description of what the action does. Used in both UI and MCP tool descriptions.

```yaml theme={null}
description: List all employees from BambooHR with optional filtering
```

<Accordion title="Description in MCP tool declarations">
  When MCP clients call `list tools`, the description becomes the tool's description:

  ```json theme={null}
  {
    "name": "bamboohr_list_employees",
    "description": "List all employees from BambooHR with optional filtering",
    "inputSchema": { ... }
  }
  ```

  **AI agent impact:** LLMs use this description to decide when to invoke the tool. A good description helps agents:

  * Understand the action's purpose
  * Know what data it returns
  * Decide which action fits the user's request

  **Best practices:**

  * Keep under 200 characters
  * Mention key capabilities
  * Be specific about what's returned
</Accordion>

### `details`

**Impact:** 🤖 MCP

Extended description with full context. Used as the complete tool description in MCP.

```yaml theme={null}
details: |
  Retrieves a paginated list of all employees from BambooHR.

  Returns employee profiles including:
  - Personal information (name, email, phone)
  - Employment details (department, job title, hire date)
  - Custom fields configured in your BambooHR account

  Use the 'fields' parameter to specify which fields to include.
  Supports filtering by employment status and department.
```

<Accordion title="Details vs Description in MCP">
  When both are present, MCP tool declarations use:

  * `description` as a brief summary
  * `details` as the full tool description

  **When only description exists:** It's used for both.

  **Recommended approach:**

  * `description`: One-line summary (\~100 chars)
  * `details`: Full context for AI agents (\~500 chars)

  The details help AI agents understand nuances like:

  * What fields are returned
  * How pagination works
  * What filters are available
  * Edge cases and limitations
</Accordion>

### `resources`

**Impact:** 🖥️ UI

Link to provider documentation for this specific action.

```yaml theme={null}
resources: https://documentation.bamboohr.com/reference/get-employees-directory
```

<Accordion title="Action-level resources">
  Override or supplement the connector-level resources link with action-specific documentation. Displayed in the Actions Explorer and helps developers understand the underlying API.
</Accordion>

***

## `inputs`

**Impact:** 🤖 MCP | ⚙️ Runtime

Define parameters the action accepts. Become MCP tool input schema.

```yaml theme={null}
inputs:
  - name: employee_id
    type: string
    description: The unique identifier of the employee
    required: true
    in: path
  - name: fields
    type: string
    description: Comma-separated list of fields to include
    required: false
    default: 'firstName,lastName,email'
    in: query
  - name: page_size
    type: number
    description: Number of results per page (max 100)
    required: false
    default: 25
    in: query
```

### Input Properties

| Property      | Type    | Description                                                |
| ------------- | ------- | ---------------------------------------------------------- |
| `name`        | string  | Parameter name (used in expressions as `$.inputs.{name}`)  |
| `type`        | enum    | Data type (see below)                                      |
| `description` | string  | 🤖 MCP - Shown in tool schema                              |
| `required`    | boolean | Whether parameter is mandatory                             |
| `default`     | any     | Default value if not provided                              |
| `in`          | enum    | Where to send: `path`, `query`, `body`, `header`           |
| `array`       | boolean | Parameter accepts array of values                          |
| `properties`  | array   | Nested properties for `type: object` (see accordion below) |

### Input Types

| Type              | Description        | Example                  |
| ----------------- | ------------------ | ------------------------ |
| `string`          | Text value         | `"john@example.com"`     |
| `number`          | Numeric value      | `42`, `3.14`             |
| `boolean`         | True/false         | `true`, `false`          |
| `datetime_string` | ISO 8601 date/time | `"2024-01-15T10:30:00Z"` |
| `object`          | JSON object        | `{ "key": "value" }`     |
| `enum`            | Predefined options | See below                |

### Enum Type

```yaml theme={null}
inputs:
  - name: status
    type: enum
    description: Filter by employment status
    required: false
    values:
      - key: active
        label: Active
        description: Currently employed
      - key: inactive
        label: Inactive
        description: Former employees
    default: active
    in: query
```

<Accordion title="MCP input schema generation">
  Inputs are converted to JSON Schema for MCP:

  ```yaml theme={null}
  inputs:
    - name: employee_id
      type: string
      description: Employee unique identifier
      required: true
    - name: include_terminated
      type: boolean
      description: Include terminated employees
      required: false
      default: false
  ```

  Becomes:

  ```json theme={null}
  {
    "inputSchema": {
      "type": "object",
      "properties": {
        "employee_id": {
          "type": "string",
          "description": "Employee unique identifier"
        },
        "include_terminated": {
          "type": "boolean",
          "description": "Include terminated employees",
          "default": false
        }
      },
      "required": ["employee_id"]
    }
  }
  ```

  **AI impact:** LLMs use this schema to:

  * Generate valid tool calls
  * Understand parameter types
  * Apply default values
  * Validate inputs before calling
</Accordion>

<Accordion title="Array inputs">
  Use `array: true` for parameters accepting multiple values:

  ```yaml theme={null}
  inputs:
    - name: employee_ids
      type: string
      array: true
      description: List of employee IDs to fetch
      in: query
  ```

  In MCP schema: `"type": "array", "items": { "type": "string" }`
</Accordion>

<Accordion title="Object type with nested properties">
  For complex inputs, use `type: object` with a nested `properties` array to define the object's structure:

  ```yaml theme={null}
  inputs:
    - name: filter
      type: object
      description: Filter criteria for the query
      required: false
      in: body
      properties:
        - name: status
          type: string
          description: Filter by status
        - name: created_after
          type: datetime_string
          description: Filter by creation date
        - name: assignee
          type: object
          description: Filter by assignee
          properties:
            - name: id
              type: string
              description: Assignee user ID
  ```

  **Properties array:** Each item in `properties` supports the same fields as top-level inputs (`name`, `type`, `description`, `required`, `default`, `properties` for deeper nesting).

  This generates proper JSON Schema for MCP, helping AI agents understand the expected object structure:

  ```json theme={null}
  {
    "filter": {
      "type": "object",
      "properties": {
        "status": { "type": "string", "description": "Filter by status" },
        "created_after": { "type": "string", "description": "Filter by creation date" },
        "assignee": {
          "type": "object",
          "properties": {
            "id": { "type": "string", "description": "Assignee user ID" }
          }
        }
      }
    }
  }
  ```
</Accordion>

***

## `steps`

**Impact:** ⚙️ Runtime

Define the execution flow for the action. Steps run sequentially.

```yaml theme={null}
steps:
  - stepId: fetch_employees
    description: Fetch employee data from API
    stepFunction:
      functionName: request
      parameters:
        url: '/employees/directory'
        method: get
        args:
          - name: fields
            value: '{{$.inputs.fields ?? "firstName,lastName"}}'
            in: query
  - stepId: transform_response
    stepFunction:
      functionName: map_fields
      version: '2'
      parameters:
        fields:
          - targetFieldKey: employees
            expression: $.employees
        dataSource: $.steps.fetch_employees.output.data
```

### Step Properties

| Property        | Type     | Description                                                                         |
| --------------- | -------- | ----------------------------------------------------------------------------------- |
| `stepId`        | string   | Unique identifier within action                                                     |
| `description`   | string   | What this step does (for debugging)                                                 |
| `condition`     | JEXL     | Skip step if condition is false                                                     |
| `ignoreError`   | boolean  | Continue execution if this step fails (default: `false`)                            |
| `stepFunction`  | object   | Function to execute (for simple steps)                                              |
| `iterator`      | JSONPath | Array expression — makes this a foreach step. See [Iterator Steps](#iterator-steps) |
| `stepFunctions` | array    | Multiple functions to execute per iteration (use with `iterator`)                   |

### Conditional Steps

```yaml theme={null}
steps:
  - stepId: fetch_with_filter
    condition: '{{present(inputs.department)}}'
    stepFunction:
      functionName: request
      parameters:
        url: '/employees'
        args:
          - name: department
            value: $.inputs.department
            in: query
```

<Accordion title="Condition expressions">
  Conditions use JEXL syntax with helper functions:

  | Function     | Description                        | Example                  |
  | ------------ | ---------------------------------- | ------------------------ |
  | `present(x)` | Value exists and not null          | `present(inputs.filter)` |
  | `blank(x)`   | Value is null, undefined, or empty | `blank(inputs.cursor)`   |

  **Common patterns:**

  ```yaml theme={null}
  # Only run if parameter provided
  condition: '{{present(inputs.employee_id)}}'

  # Only run on first page
  condition: '{{blank(inputs.cursor)}}'

  # Multiple conditions
  condition: '{{present(inputs.start_date) && present(inputs.end_date)}}'
  ```
</Accordion>

***

## Step Functions

### `request`

**Impact:** ⚙️ Runtime

Make an HTTP request to the provider API.

```yaml theme={null}
stepFunction:
  functionName: request
  parameters:
    url: '/employees/{employee_id}'
    method: get
    args:
      - name: employee_id
        value: $.inputs.employee_id
        in: path
      - name: fields
        value: '{{$.inputs.fields ?? "all"}}'
        in: query
      - name: Content-Type
        value: application/json
        in: headers
```

| Parameter             | Type    | Description                                    |
| --------------------- | ------- | ---------------------------------------------- |
| `baseUrl`             | string  | Override connector baseUrl                     |
| `url`                 | string  | Endpoint path (appended to baseUrl)            |
| `method`              | enum    | `get`, `post`, `put`, `patch`, `delete`        |
| `authorization`       | object  | Override connector auth                        |
| `args`                | array   | Request parameters                             |
| `response.collection` | boolean | Whether response is an array (default: `true`) |
| `response.dataKey`    | string  | Extract data from this key in response         |
| `response.indexField` | string  | Field to use as index for keyed results        |
| `customErrors`        | array   | Remap provider error responses (see below)     |

#### Args Location (`in`)

| Value     | Description                           |
| --------- | ------------------------------------- |
| `path`    | URL path parameter: `/employees/{id}` |
| `query`   | Query string: `?field=value`          |
| `body`    | Request body (JSON)                   |
| `headers` | HTTP header                           |

<Accordion title="Request construction internals">
  The runtime builds requests as follows:

  1. **URL:** `baseUrl` + `url` with path params interpolated
  2. **Query:** All `in: query` args joined with `&`
  3. **Body:** All `in: body` args merged into JSON object
  4. **Headers:** Connector auth headers + custom headers + `in: headers` args

  **Path parameter example:**

  ```yaml theme={null}
  url: '/employees/{employee_id}/time-off/{request_id}'
  args:
    - name: employee_id
      value: $.inputs.employee_id
      in: path
    - name: request_id
      value: $.inputs.request_id
      in: path
  ```

  Resolves to: `/employees/123/time-off/456`

  **Body construction:**

  ```yaml theme={null}
  args:
    - name: firstName
      value: $.inputs.first_name
      in: body
    - name: lastName
      value: $.inputs.last_name
      in: body
  ```

  Sends: `{ "firstName": "John", "lastName": "Doe" }`
</Accordion>

<Accordion title="Custom error handling">
  Use `customErrors` to remap provider error responses. This is useful for:

  * GraphQL APIs that return errors with 200 status codes
  * Provider-specific error formats that need normalization
  * Custom error messages for better AI agent understanding

  ```yaml theme={null}
  stepFunction:
    functionName: request
    parameters:
      url: /graphql
      method: post
      customErrors:
        - receivedStatus: 200
          targetStatus: 400
          condition: '{{present(data.errors)}}'
          message: GraphQL query failed
        - receivedStatus: 404
          targetStatus: 400
          message: Resource not found
        - receivedStatus: 200
          targetStatus: 401
          condition: '{{data.ok == false}}'
          message: '{{data.error}}'
  ```

  **customErrors properties:**

  | Property         | Type   | Description                                                                                                                                                                                                                                                                   |
  | ---------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `receivedStatus` | number | HTTP status to match from provider                                                                                                                                                                                                                                            |
  | `targetStatus`   | number | HTTP status to return instead                                                                                                                                                                                                                                                 |
  | `condition`      | string | JEXL expression (only trigger error if true)                                                                                                                                                                                                                                  |
  | `message`        | string | Error message. Pass a plain string for a static message, or a JEXL expression like `{{data.error}}` to pull the value from the response body. If the expression resolves to null or undefined, the message falls back to the standard HTTP status text (e.g. `Unauthorized`). |

  The `condition` property is useful for GraphQL APIs where errors are returned in the response body with a 200 status code.
</Accordion>

### `paginated_request`

**Impact:** ⚙️ Runtime

Automatically handle pagination for list endpoints.

```yaml theme={null}
stepFunction:
  functionName: paginated_request
  parameters:
    url: '/employees'
    method: get
    args:
      - name: page_size
        value: '{{$.inputs.page_size ?? 25}}'
        in: query
    pagination:
      type: cursor
      request:
        cursor_field: cursor
        cursor_position: query
      response:
        cursor_path: $.next_cursor
        data_path: $.employees
```

#### Pagination Types

```yaml theme={null}
# Cursor-based
pagination:
  type: cursor
  request:
    cursor_field: cursor
    cursor_position: query
  response:
    cursor_path: $.next_cursor
    data_path: $.data

# Offset-based
pagination:
  type: offset
  request:
    offset_field: offset
    limit_field: limit
    offset_position: query
  response:
    data_path: $.results
    total_path: $.total_count

# Page number
pagination:
  type: page_number
  request:
    page_field: page
    page_position: query
  response:
    data_path: $.items
    total_pages_path: $.total_pages
```

<Accordion title="Pagination handling mechanics">
  The runtime handles pagination automatically:

  **Cursor pagination:**

  1. Make initial request without cursor
  2. Read `cursor_path` from response
  3. If cursor exists, make next request with cursor in `cursor_position`
  4. Repeat until no cursor returned
  5. Aggregate all `data_path` results

  **Result format:**

  ```json theme={null}
  {
    "data": [...all records...],
    "next": "cursor_for_next_page_or_null"
  }
  ```

  **MCP behavior:** When an agent calls a list action, they receive the first page. The `next` cursor allows fetching subsequent pages by passing it back as an input parameter.
</Accordion>

### `map_fields`

**Impact:** ⚙️ Runtime

Transform data between formats.

```yaml theme={null}
stepFunction:
  functionName: map_fields
  version: '2'
  parameters:
    fields:
      - targetFieldKey: id
        expression: $.employeeId
        type: string
      - targetFieldKey: full_name
        expression: $.firstName + ' ' + $.lastName
        type: string
      - targetFieldKey: is_active
        expression: $.status == 'Active'
        type: boolean
      - targetFieldKey: hire_date
        expression: $.hireDate
        type: datetime_string
    dataSource: $.steps.fetch_employees.output.data
```

| Parameter                 | Type     | Description              |
| ------------------------- | -------- | ------------------------ |
| `fields`                  | array    | Mapping definitions      |
| `dataSource`              | JSONPath | Source data to transform |
| `fields[].targetFieldKey` | string   | Output field name        |
| `fields[].expression`     | JEXL     | Value expression         |
| `fields[].type`           | enum     | Output type              |

<Accordion title="Field mapping expressions">
  Expressions support JEXL syntax with the source object as context:

  **Simple path:**

  ```yaml theme={null}
  expression: $.employeeId
  ```

  **Concatenation:**

  ```yaml theme={null}
  expression: $.firstName + ' ' + $.lastName
  ```

  **Conditional:**

  ```yaml theme={null}
  expression: $.status == 'Active' ? 'employed' : 'terminated'
  ```

  **Null coalescing:**

  ```yaml theme={null}
  expression: $.middleName ?? ''
  ```

  **Nested access:**

  ```yaml theme={null}
  expression: $.department.name
  ```

  **Array operations:**

  ```yaml theme={null}
  expression: $.tags|join(',')
  ```

  **Type coercion:**
  The `type` field ensures output matches expected type:

  * `string` - Converts to string
  * `number` - Converts to number
  * `boolean` - Converts to boolean
  * `datetime_string` - Formats as ISO 8601
</Accordion>

### `group_data`

**Impact:** ⚙️ Runtime

Group array data by a field.

```yaml theme={null}
stepFunction:
  functionName: group_data
  parameters:
    groupByField: department_id
    dataSource: $.steps.fetch_employees.output.data
```

<Accordion title="Group data usage">
  Transforms flat array into grouped structure:

  **Input:**

  ```json theme={null}
  [
    { "name": "John", "department_id": "eng" },
    { "name": "Jane", "department_id": "eng" },
    { "name": "Bob", "department_id": "sales" }
  ]
  ```

  **Output:**

  ```json theme={null}
  {
    "eng": [
      { "name": "John", "department_id": "eng" },
      { "name": "Jane", "department_id": "eng" }
    ],
    "sales": [
      { "name": "Bob", "department_id": "sales" }
    ]
  }
  ```

  Useful for restructuring provider responses into more usable formats.
</Accordion>

### `typecast`

**Impact:** ⚙️ Runtime

Convert data types.

```yaml theme={null}
stepFunction:
  functionName: typecast
  parameters:
    type: number
    dataSource: $.steps.previous.output.data.count
```

| Type      | Description                 |
| --------- | --------------------------- |
| `string`  | Convert to string           |
| `number`  | Parse as number             |
| `boolean` | Convert to boolean          |
| `json`    | Parse JSON string to object |

### `soap_request`

**Impact:** ⚙️ Runtime

Make SOAP API requests. Used primarily for enterprise providers like Workday.

```yaml theme={null}
stepFunction:
  functionName: soap_request
  parameters:
    baseUrl: 'https://${credentials.workday_host}'
    url: '/ccx/service/${credentials.tenant}/Human_Resources'
    method: post
    authorization:
      type: bearer
      token: ${credentials.accessToken}
      includeBearer: true
    soapOperation: Get_Workers
    useSoapContext: false
    namespaces:
      - namespaceIdentifier: bsvc
        namespace: 'urn:com.workday/bsvc'
    args:
      - name: '@_bsvc:version'
        in: body
        value: v45.1
      - name: bsvc:Request_Criteria
        in: body
        value:
          'bsvc:Transaction_Log_Criteria_Data':
            - 'bsvc:Transaction_Date_Range_Data':
                'bsvc:Updated_From': '{{$.inputs.updated_after}}'
```

| Parameter        | Type    | Description                         |
| ---------------- | ------- | ----------------------------------- |
| `baseUrl`        | string  | SOAP service base URL               |
| `url`            | string  | SOAP endpoint path                  |
| `method`         | enum    | HTTP method (typically `post`)      |
| `authorization`  | object  | Auth config (same as `request`)     |
| `soapOperation`  | string  | SOAP operation name                 |
| `useSoapContext` | boolean | Use SOAP context (default: `false`) |
| `namespaces`     | array   | XML namespace definitions           |
| `args`           | array   | Request parameters                  |

<Accordion title="SOAP namespace configuration">
  Namespaces map XML prefixes to URIs:

  ```yaml theme={null}
  namespaces:
    - namespaceIdentifier: bsvc
      namespace: 'urn:com.workday/bsvc'
    - namespaceIdentifier: wd
      namespace: 'urn:com.workday/bsvc/wd'
  ```

  Reference namespaces in field names with the identifier prefix:

  ```yaml theme={null}
  args:
    - name: 'bsvc:Worker_Reference'
      in: body
      value:
        'bsvc:ID':
          '@_bsvc:type': 'Employee_ID'
          '#text': '{{$.inputs.employee_id}}'
  ```

  **XML attribute syntax:** Use `@_` prefix for XML attributes and `#text` for text content.
</Accordion>

### `static_values`

**Impact:** ⚙️ Runtime

Return predefined static values without making an API request. Useful for enum lookups or constant data.

```yaml theme={null}
stepFunction:
  functionName: static_values
  parameters:
    values:
      - id: question
        name: Question
      - id: incident
        name: Incident
      - id: problem
        name: Problem
      - id: task
        name: Task
```

| Parameter | Type  | Description                       |
| --------- | ----- | --------------------------------- |
| `values`  | array | Array of static objects to return |

<Accordion title="Static values use cases">
  Use `static_values` when:

  1. **Provider doesn't have an API endpoint** for enum values:

  ```yaml theme={null}
  # Ticket types are hardcoded in Zendesk
  stepFunction:
    functionName: static_values
    parameters:
      values:
        - id: question
          name: Question
        - id: incident
          name: Incident
  ```

  2. **Combining with dynamic data** via multi-step actions:

  ```yaml theme={null}
  steps:
    static_types:
      stepFunction:
        functionName: static_values
        parameters:
          values:
            - id: default
              name: Default Type

    api_types:
      stepFunction:
        functionName: request
        parameters:
          url: /custom-types

    merge_types:
      stepFunction:
        functionName: merge_collections
        parameters:
          collections:
            - $.steps.static_types.output.data
            - $.steps.api_types.output.data
  ```
</Accordion>

### `merge_collections`

**Impact:** ⚙️ Runtime

Merge multiple data collections into a single array.

```yaml theme={null}
stepFunction:
  functionName: merge_collections
  parameters:
    collections:
      - $.steps.static_defaults.output.data
      - $.steps.api_results.output.data
```

| Parameter     | Type  | Description                            |
| ------------- | ----- | -------------------------------------- |
| `collections` | array | JSONPath references to arrays to merge |

<Accordion title="Merge collections example">
  Combine static defaults with API-fetched data:

  ```yaml theme={null}
  steps:
    default_statuses:
      stepFunction:
        functionName: static_values
        parameters:
          values:
            - id: open
              name: Open
            - id: closed
              name: Closed

    custom_statuses:
      stepFunction:
        functionName: request
        parameters:
          url: /custom-statuses

    all_statuses:
      stepFunction:
        functionName: merge_collections
        parameters:
          collections:
            - $.steps.default_statuses.output.data
            - $.steps.custom_statuses.output.data

  result:
    outputDataPath: $.steps.all_statuses.output.data
  ```

  Collections are merged in order—items from the first collection appear first in the result.
</Accordion>

### `code_execution_lambda`

**Impact:** ⚙️ Runtime

Invoke an AWS Lambda function and use the response as the step output. Useful for offloading custom transformations, provider-specific logic, or computation that doesn't fit other step functions.

```yaml theme={null}
stepFunction:
  functionName: code_execution_lambda
  parameters:
    lambdaName: my-lambda-function
    region: us-east-1
    invocationType: RequestResponse
    args:
      - name: userId
        value: $.inputs.user_id
      - name: count
        value: $.inputs.count
```

| Parameter          | Type   | Description                                                                |
| ------------------ | ------ | -------------------------------------------------------------------------- |
| `lambdaName`       | string | Name or ARN of the Lambda function to invoke                               |
| `region`           | string | AWS region of the Lambda function (optional)                               |
| `endpoint`         | string | Custom Lambda endpoint URL (optional)                                      |
| `invocationType`   | enum   | `RequestResponse`, `Event`, or `DryRun` (default: `RequestResponse`)       |
| `qualifier`        | string | Function version or alias (optional)                                       |
| `args`             | array  | Key/value pairs combined into the JSON payload sent to the Lambda function |
| `args[].name`      | string | Payload field name                                                         |
| `args[].value`     | any    | Payload field value (supports expressions)                                 |
| `args[].condition` | string | JEXL expression — only include this arg when true (optional)               |
| `dataKey`          | string | Extract data from this key in the Lambda response (optional)               |

#### Invocation Types

| Value             | Description                                                       |
| ----------------- | ----------------------------------------------------------------- |
| `RequestResponse` | Synchronous — wait for the Lambda to return a response            |
| `Event`           | Asynchronous — fire-and-forget, no response body returned         |
| `DryRun`          | Validate parameters and permissions without invoking the function |

#### Output

| Field             | Type   | Description                                                 |
| ----------------- | ------ | ----------------------------------------------------------- |
| `data`            | any    | Parsed Lambda response (after `dataKey` extraction if set)  |
| `raw`             | any    | Full Lambda response payload                                |
| `statusCode`      | number | HTTP status code returned by the Lambda invocation          |
| `message`         | string | Error or status message (optional)                          |
| `executedVersion` | string | Version of the Lambda function that was executed (optional) |

<Accordion title="Payload construction and response handling">
  The `args` array is assembled into a single JSON object and sent as the Lambda payload:

  **Input args:**

  ```yaml theme={null}
  args:
    - name: userId
      value: $.inputs.user_id
    - name: count
      value: $.inputs.count
  ```

  **Sent payload:**

  ```json theme={null}
  { "userId": "abc123", "count": 5 }
  ```

  **Conditional args:**

  ```yaml theme={null}
  args:
    - name: filter
      value: ${inputs.filter}
      condition: '{{present(inputs.filter)}}'
  ```

  **Extracting a nested response:**

  ```yaml theme={null}
  stepFunction:
    functionName: code_execution_lambda
    parameters:
      lambdaName: enrich-user
      region: us-east-1
      dataKey: result
      args:
        - name: userId
          value: ${inputs.user_id}
  ```

  If the Lambda returns `{ "result": { "score": 0.9 }, "meta": {...} }`, then `$.steps.{stepId}.output.data` is `{ "score": 0.9 }`.
</Accordion>

### Iterator Steps

**Impact:** ⚙️ Runtime

Iterator steps (foreach) execute step function(s) for each item in an array. Define by adding the `iterator` property to a step.

```yaml theme={null}
- stepId: get_employee_details
  description: Fetch detailed data for each employee
  iterator: $.steps.list_employees.output.data.employees[*].id
  stepFunction:
    functionName: request
    parameters:
      url: /employees/${iterator.item}
      method: get
```

| Property        | Type     | Description                                                                     |
| --------------- | -------- | ------------------------------------------------------------------------------- |
| `iterator`      | JSONPath | Expression that evaluates to an array                                           |
| `stepFunction`  | object   | Single function to execute per item                                             |
| `stepFunctions` | array    | Multiple functions to execute per item (mutually exclusive with `stepFunction`) |

<Accordion title="Iterator context variables">
  Inside an iterator step, these additional variables are available:

  | Variable             | Description                                                    |
  | -------------------- | -------------------------------------------------------------- |
  | `$.iterator.item`    | Current array element                                          |
  | `$.iterator.index`   | Current iteration index (0-based)                              |
  | `$.iterator.current` | Output from previous step function in `stepFunctions` sequence |
  | `${iterator.item}`   | String interpolation of current item (for URLs)                |

  **Multiple step functions per iteration:**

  ```yaml theme={null}
  - stepId: enrich_employees
    iterator: $.steps.list.output.data[*].id
    stepFunctions:
      - functionName: request
        parameters:
          url: /employees/${iterator.item}/details
          method: get
      - functionName: request
        parameters:
          url: /employees/${iterator.item}/compensation
          method: get
  ```

  Each iteration collects the final step function output. All iteration results are combined into `$.steps.{stepId}.output.data` as an array.
</Accordion>

***

## `result`

**Impact:** 🤖 MCP | ⚙️ Runtime

Define the action's output. Becomes the tool's return value.

```yaml theme={null}
result:
  data: $.steps.transform_response.output.data
  rawRequest: $.steps.fetch_employees.output.request
  rawResponse: $.steps.fetch_employees.output.response
```

| Property      | Description                                |
| ------------- | ------------------------------------------ |
| `data`        | Primary response data (returned to caller) |
| `rawRequest`  | Original HTTP request (for debugging)      |
| `rawResponse` | Original HTTP response (for debugging)     |

<Accordion title="Result in MCP responses">
  When an MCP client calls a tool, the result determines the response:

  ```yaml theme={null}
  result:
    data: $.steps.map_employees.output.data
  ```

  The tool returns:

  ```json theme={null}
  {
    "content": [
      {
        "type": "text",
        "text": "{ \"data\": [...employees...] }"
      }
    ]
  }
  ```

  For list actions with pagination:

  ```json theme={null}
  {
    "data": [...],
    "next": "cursor_token"
  }
  ```

  **rawRequest/rawResponse:** Included for debugging when enabled. Helps troubleshoot API issues without diving into logs.
</Accordion>

***

## Expression Formats

Three expression formats are available throughout connector YAML. For the complete reference including all built-in functions, see the [Expression Language](/guides/connector-engine/expression-language) page.

### JSONPath (`$.path`)

Access data from context objects.

```yaml theme={null}
value: $.credentials.apiKey
value: $.inputs.employee_id
value: $.steps.fetch_data.output.data.employees
```

| Context                   | Description             |
| ------------------------- | ----------------------- |
| `$.credentials`           | Auth credentials        |
| `$.inputs`                | Action input parameters |
| `$.config`                | Connector configuration |
| `$.steps.{stepId}.output` | Previous step output    |

### String Interpolation (`${...}`)

Embed values in strings.

```yaml theme={null}
url: '/employees/${inputs.employee_id}/profile'
baseUrl: 'https://api.${credentials.subdomain}.provider.com'
```

### JEXL (`'{{...}}'`)

Complex expressions with logic.

```yaml theme={null}
value: '{{$.inputs.status ?? "active"}}'
value: '{{present(inputs.filter) ? inputs.filter : "all"}}'
condition: '{{$.inputs.page_size > 100}}'
```

<Accordion title="Expression format selection guide">
  **Use JSONPath when:**

  * Simple value access
  * No transformation needed
  * Used alone (not in string)

  **Use String Interpolation when:**

  * Building URLs or strings
  * Concatenating with static text
  * Simple variable substitution

  **Use JEXL when:**

  * Default values needed (`??` operator)
  * Conditional logic required
  * Complex transformations
  * In `condition` fields

  **Examples:**

  ```yaml theme={null}
  # JSONPath - direct value
  token: $.credentials.accessToken

  # String interpolation - URL building
  url: '/api/v1/users/${inputs.user_id}'

  # JEXL - default value
  value: '{{$.inputs.limit ?? 25}}'

  # JEXL - conditional
  value: '{{present(inputs.filter) ? inputs.filter : "*"}}'
  ```
</Accordion>

***

## GraphQL Actions

For GraphQL APIs, use the `request` function with POST method and query in body.

```yaml theme={null}
steps:
  - stepId: graphql_query
    stepFunction:
      functionName: request
      parameters:
        url: '/graphql'
        method: post
        args:
          - name: query
            value: |
              query ListUsers($first: Int, $after: String) {
                users(first: $first, after: $after) {
                  nodes {
                    id
                    name
                    email
                  }
                  pageInfo {
                    hasNextPage
                    endCursor
                  }
                }
              }
            in: body
          - name: variables
            value:
              first: '{{$.inputs.page_size ?? 50}}'
              after: '{{$.inputs.cursor ?? null}}'
            in: body
```

<Accordion title="GraphQL best practices">
  **Query structure:**

  * Define variables for all dynamic values
  * Use fragments for reusable field selections
  * Keep queries focused (request only needed fields)

  **Pagination:**
  GraphQL often uses cursor-based pagination:

  ```graphql theme={null}
  query {
    users(first: 50, after: "cursor") {
      nodes { ... }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
  ```

  **Error handling:**
  GraphQL returns 200 even for errors. Check `errors` field in response:

  ```yaml theme={null}
  - stepId: check_errors
    condition: '{{present(steps.graphql_query.output.data.errors)}}'
    stepFunction:
      # Handle error case
  ```

  **Variables:**
  Pass variables as separate `variables` object, not inline in query:

  ```yaml theme={null}
  args:
    - name: query
      value: 'query GetUser($id: ID!) { user(id: $id) { name } }'
      in: body
    - name: variables
      value:
        id: $.inputs.user_id
      in: body
  ```
</Accordion>

***

## Complete Action Example

Here's a full action demonstrating all concepts:

```yaml theme={null}
- actionId: list_employees
  categories:
    - hris
    - employees
  actionType: list
  label: List Employees
  description: Retrieve a paginated list of employees from BambooHR
  details: |
    Fetches employee records with optional filtering by status and department.

    Returns:
    - Employee ID and display name
    - Email and phone
    - Department and job title
    - Employment status and dates

    Pagination: Returns 25 records per page by default. Use 'next' cursor for more.
  resources: https://documentation.bamboohr.com/reference/get-employees-directory
  inputs:
    - name: status
      type: enum
      description: Filter by employment status
      required: false
      values:
        - key: active
          label: Active
          description: Currently employed
        - key: inactive
          label: Inactive
          description: Former employees
      default: active
      in: query
    - name: department
      type: string
      description: Filter by department name
      required: false
      in: query
    - name: page_size
      type: number
      description: Number of results per page (max 100)
      required: false
      default: 25
      in: query
    - name: cursor
      type: string
      description: Pagination cursor from previous response
      required: false
      in: query
  steps:
    - stepId: fetch_employees
      description: Fetch employee directory from BambooHR API
      stepFunction:
        functionName: paginated_request
        parameters:
          url: '/employees/directory'
          method: get
          args:
            - name: status
              value: '{{$.inputs.status ?? "active"}}'
              in: query
            - name: department
              value: $.inputs.department
              in: query
              condition: '{{present(inputs.department)}}'
            - name: page_size
              value: '{{$.inputs.page_size ?? 25}}'
              in: query
            - name: cursor
              value: $.inputs.cursor
              in: query
              condition: '{{present(inputs.cursor)}}'
          pagination:
            type: cursor
            request:
              cursor_field: cursor
              cursor_position: query
            response:
              cursor_path: $.paging.next
              data_path: $.employees
    - stepId: transform_employees
      description: Map BambooHR fields to standard format
      stepFunction:
        functionName: map_fields
        version: '2'
        parameters:
          fields:
            - targetFieldKey: id
              expression: $.id
              type: string
            - targetFieldKey: display_name
              expression: $.displayName
              type: string
            - targetFieldKey: email
              expression: $.workEmail
              type: string
            - targetFieldKey: department
              expression: $.department
              type: string
            - targetFieldKey: job_title
              expression: $.jobTitle
              type: string
            - targetFieldKey: status
              expression: $.status
              type: string
            - targetFieldKey: hire_date
              expression: $.hireDate
              type: datetime_string
          dataSource: $.steps.fetch_employees.output.data
  result:
    data: $.steps.transform_employees.output.data
    rawRequest: $.steps.fetch_employees.output.request
    rawResponse: $.steps.fetch_employees.output.response
```

***

## Next Steps

<CardGroup>
  <Card title="Expression Language" icon="function" href="/guides/connector-engine/expression-language">
    Full reference for JSONPath, JEXL, and built-in functions
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/guides/connector-engine/cli-reference">
    Validate and deploy connectors
  </Card>

  <Card title="StackOne Agent" icon="robot" href="/guides/connector-engine/stackone-agent">
    AI-assisted connector development
  </Card>

  <Card title="Connector Examples" icon="code" href="https://github.com/StackOneHQ/connectors-template">
    Browse real connector implementations
  </Card>
</CardGroup>


# Connector Documentation
Source: https://docs.stackone.com/guides/connector-engine/creating-connector-documentation

Add setup guides to your connector configuration that users can access programmatically

When you build a custom connector, you can embed step-by-step setup guides directly in the connector YAML configuration. These guides are exposed through the StackOne API's `/actions` endpoint and can be rendered in your own documentation, dashboards, or integration hubs.

***

## Overview

Connector documentation consists of two types of guides:

<CardGroup>
  <Card title="Account Link Guides" icon="link">
    **For end-users** - Instructions to connect their account via Integration Hub. Covers finding credentials like API keys, domains, and OAuth authorization.
  </Card>

  <Card title="Auth Setup Guides" icon="key">
    **For application setup** - Instructions to register OAuth applications and obtain client credentials before users can connect.
  </Card>
</CardGroup>

**Where guides go:**

* Account link guides → `authentication[].{method}.support.guides.config`
* Auth setup guides → `authentication[].{method}.support.guides.setup`

***

## Guide Structure in YAML

Guides are added to the `authentication` block in your connector YAML configuration.

### Basic Example

```yaml theme={null}
authentication:
  - custom:
      type: custom
      label: API Key
      support:
        guides:
          config:                          # Account linking guide (for end-users/resource owners)
            warning: "Admin access required to generate an API key."
            sections:
              - title: Generating an API Key
                content: |
                  Instructions for finding the API key.
                steps:
                  - title: Navigate to Settings
                    content: |
                      Go to Settings > API in your account.
                  - title: Create Key
                    content: |
                      Click Generate API Key and copy it.
      authorization:
        type: bearer
        token: $.credentials.apiKey
      configFields:
        - key: apiKey
          label: API Key
          type: password
          required: true
          secret: true
```

### When to Use Each Guide Type

| Guide Type      | Field Dependency        | Purpose                                                  | Audience                    |
| --------------- | ----------------------- | -------------------------------------------------------- | --------------------------- |
| `guides.config` | Requires `configFields` | How end-users get their credentials                      | End-users (resource owners) |
| `guides.setup`  | Requires `setupFields`  | How to register OAuth apps and obtain client credentials | Application owners          |

<Warning>
  Only include `guides.config` if `configFields` exists. Only include `guides.setup` if `setupFields` exists.
</Warning>

### The support.link Field

<Warning>
  **Critical:** Set `support.link` to the URL where you'll render these guides in your own documentation or dashboard. The Integration Hub uses this link to direct users to your rendered guides. If not set, the Hub will link to StackOne's generic documentation instead of your custom instructions.
</Warning>

```yaml theme={null}
authentication:
  - custom:
      type: custom
      label: API Key
      support:
        link: https://docs.yourcompany.com/integrations/provider-setup  # Required
        description: Admin privileges required
        guides:
          config:
            # ... your guide content
```

The `support.link` should point to where you host the rendered version of these guides, ensuring users see your branded, customized setup instructions.

***

## Section Structure

Each guide contains an array of sections with steps.

### Section Properties

```yaml theme={null}
sections:
  - title: Section Title                   # Required
    content: |                             # Optional - Intro text
      Section overview text.
    list:                                  # Optional - Bullet points
      - Item 1
      - Item 2
    steps:                                 # Optional - Nested steps
      - title: Step Title
        content: |
          Step instructions.
        list:
          - Sub-item 1
          - Sub-item 2
    applicableScopes: employees:read       # Optional - Filter by scopes (space-separated)
```

### Content Formatting

The `content` and `list` fields contain plain strings. To render markdown formatting, use a markdown parser in your rendering code. Common patterns include:

* **Links:** `[Provider Dashboard](https://example.com/dashboard)` → Parse with markdown renderer to create clickable links
* **Bold:** `**Settings**` for UI elements → Parse to render as `<strong>Settings</strong>`
* **Code:** `` `https://api.example.com` `` → Parse to render as `<code>https://api.example.com</code>`

<Tip>
  The API returns raw strings with markdown syntax. You're responsible for parsing and rendering them. Use libraries like `react-markdown`, `marked`, or similar, and always sanitize HTML output with tools like `DOMPurify` to prevent XSS attacks.
</Tip>

***

## Scope Definitions

<Warning>
  **Preview Feature:** Scope definitions and scope-aware guides are under active development. The structure and behavior may change. Currently used primarily for OAuth scopes, but designed to support any action requirements (pricing tiers, platform configuration, feature flags, etc.).
</Warning>

Define action requirements in `scopeDefinitions` at the connector root level. While commonly used for OAuth/API scopes, these can represent any prerequisite needed to enable an action.

### Basic Scopes

```yaml theme={null}
scopeDefinitions:
  employees:read:
    description: Read employee data
  employees:write:
    description: Create and update employee records
    includes: employees:read              # Write includes read
```

<Tip>
  Scopes aren't limited to API permissions. Use them to represent pricing tiers (`plan:enterprise`), platform features (`feature:advanced_reporting`), or configuration requirements (`config:sso_enabled`).
</Tip>

### Hierarchical Scopes

```yaml theme={null}
scopeDefinitions:
  https://www.googleapis.com/auth/drive:
    description: View and manage all Drive files
    includes: https://www.googleapis.com/auth/drive.readonly
  https://www.googleapis.com/auth/drive.readonly:
    description: View all Drive files (read-only)
```

**Rules:**

* Write scopes typically include read scopes via `includes`
* Broader scopes include narrower scopes
* Only include relationships explicitly documented by provider
* Read-only scopes should NOT include write scopes

***

## Scope-Aware Guide Content

Guide sections can be filtered based on selected scopes or requirements, showing only relevant instructions for the user's configuration.

### Basic Scope Filtering

```yaml theme={null}
guides:
  config:
    sections:
      - title: Read Permissions
        applicableScopes: employees:read   # Only show this section when this scope selected
        steps:
          - title: Enable Read Access
            content: |
              Grant read permissions in the admin panel.

      - title: Write Permissions
        applicableScopes: employees:write  # Only show this section when this scope selected
        steps:
          - title: Enable Write Access
            content: |
              Grant write permissions for creating/updating employees.
```

### Displaying Actions Enabled by Requirements

Use `displayScopes: true` to show which actions a step enables:

```yaml theme={null}
steps:
  - title: Select API Scopes
    content: |
      Choose the scopes you need based on your use case.
    displayScopes: true
    applicableScopes: employees:read employees:write departments:read  # Space-separated list
```

When rendered, this shows badges indicating which actions are enabled by these requirements (scopes, features, etc.).

***

## Complete Examples

### API Key Authentication

```yaml theme={null}
authentication:
  - custom:
      type: custom
      label: API Key
      support:
        description: Admin privileges required
        guides:
          config:
            warning: "Admin access to your account is required to generate an API key."
            sections:
              - title: Generating an API Key
                content: |
                  Generate an API key from your admin dashboard.
                steps:
                  - title: Sign in and open API settings
                    content: |
                      Sign in to your [Provider account](https://app.provider.com/signin).
                    list:
                      - Click **Settings** in the top navigation
                      - Select **API** from the sidebar
                      - Click **Create API Key**
                  - title: Name and create the key
                    content: |
                      Give your API key a descriptive name.
                    list:
                      - "**Name:** Enter 'StackOne Integration'"
                      - Click **Generate Key**
                  - title: Copy the API key
                    content: |
                      Copy your new API Key and store it securely.
                    list:
                      - This key will only be shown once
                      - Save it in a secure password manager
      authorization:
        type: bearer
        token: $.credentials.apiKey
      configFields:
        - key: apiKey
          label: API Key
          type: password
          required: true
          secret: true
          placeholder: sk_live_abc123def456
          description: Generate via Settings > API in your Provider account
      environments:
        - key: production
          name: Production
```

### OAuth 2.0 with Setup Guide

```yaml theme={null}
authentication:
  - oauth2:
      type: oauth2
      label: OAuth 2.0
      support:
        description: OAuth application setup required
        guides:
          setup:                           # For application owners - registering OAuth client
            warning: "Admin access required to create OAuth applications."
            sections:
              - title: Create OAuth Application
                content: |
                  Register an OAuth application in your Provider dashboard.
                steps:
                  - title: Navigate to OAuth Apps
                    content: |
                      Go to Settings > Developer > OAuth Applications.
                  - title: Register New Application
                    content: |
                      Click **New OAuth App** and configure:
                    list:
                      - "**Application Name:** StackOne"
                      - "**Redirect URI:** `https://api.stackone.com/connect/oauth2/provider_key/callback`"
                  - title: Copy Credentials
                    content: |
                      Save your Client ID and Client Secret.
                    list:
                      - Copy the Client ID immediately
                      - Generate and copy the Client Secret
                      - Store both securely for use later
          config:                          # For end-users/resource owners - authorizing access
            sections:
              - title: OAuth Connection Flow
                content: |
                  Authorize StackOne to access your account.
                steps:
                  - title: Initiate Connection
                    content: |
                      Click **Connect** in the StackOne Hub.
                  - title: Review Permissions
                    content: |
                      Review the requested permissions.
                    displayScopes: true
                    applicableScopes: employees:read employees:write  # Space-separated list
                  - title: Authorize Access
                    content: |
                      Click **Authorize** to grant access.
      authorization:
        type: oauth2
        authorizationUrl: https://provider.com/oauth/authorize
        tokenUrl: https://provider.com/oauth/token
        tokenRequest:
        args:
          - name: client_id
            value: $.credentials.clientId
            in: body
          - name: client_secret
            value: $.credentials.clientSecret
            in: body
          - name: code
            value: $.credentials.code
            in: body
          - name: grant_type
            value: authorization_code
            in: body
      setupFields:
        - key: clientId
          label: Client ID
          type: text
          required: true
        - key: clientSecret
          label: Client Secret
          type: password
          required: true
          secret: true

scopeDefinitions:
  employees:read:
    description: Read employee data
  employees:write:
    description: Create and update employee records
    includes: employees:read
```

***

## Retrieving Guides via API

Once your connector is deployed, guides are available through the `/actions` API endpoint.

### API Request

```bash theme={null}
curl -X GET "https://api.stackone.com/actions?include=authentication_guides&filter[connectors]=your_provider" \
  -H "Authorization: Basic $(echo -n 'YOUR_API_KEY:' | base64)"
```

### Response Structure

```json theme={null}
{
  "data": [
    {
      "key": "your_provider",
      "name": "Your Provider",
      "icon": "https://stackone-logos.com/api/your_provider/filled/png",
      "authentication": [
        {
          "type": "custom",
          "label": "API Key",
          "key": "api_key",
          "configFields": [
            {
              "key": "apiKey",
              "label": "API Key",
              "type": "password",
              "required": true,
              "secret": true,
              "placeholder": "sk_live_abc123"
            }
          ],
          "support": {
            "guides": {
              "config": {
                "warning": "Admin access required to generate an API key.",
                "sections": [
                  {
                    "title": "Generating an API Key",
                    "content": "Generate an API key from your admin dashboard.",
                    "steps": [
                      {
                        "title": "Sign in and open API settings",
                        "content": "Sign in to your Provider account.",
                        "list": [
                          "Click **Settings** in the top navigation",
                          "Select **API** from the sidebar",
                          "Click **Create API Key**"
                        ]
                      }
                    ]
                  }
                ]
              }
            }
          }
        }
      ],
      "actions": [
        {
          "id": "your_provider_list_employees",
          "label": "List Employees",
          "required_scopes": ["employees:read"]
        }
      ]
    }
  ],
  "next": null
}
```

### Query Parameters

| Parameter            | Description                          | Example                         |
| -------------------- | ------------------------------------ | ------------------------------- |
| `include`            | Must include `authentication_guides` | `include=authentication_guides` |
| `filter[connectors]` | Filter by connector key              | `filter[connectors]=bamboohr`   |
| `page_size`          | Results per page                     | `page_size=100`                 |
| `next`               | Pagination cursor                    | `next=cursor_string`            |

***

## Rendering Guides in Your System

You can render the guides however you choose. Here's a basic approach using TypeScript and React:

### 1. Fetch and Parse

```typescript theme={null}
interface GuideSection {
  title: string;  // Required per YAML schema
  content?: string;
  list?: string[];
  steps?: GuideStep[];
  applicableScopes?: string[];
}

interface GuideStep {
  title: string;  // Required per YAML schema
  content?: string;
  list?: string[];
  displayScopes?: boolean;  // Whether to show requirement badges for this step
  applicableScopes?: string[];  // Filter step by requirements (OAuth scopes, features, etc.)
}

interface AuthGuides {
  config?: {
    warning?: string;
    sections?: GuideSection[];
  };
  setup?: {
    warning?: string;
    sections?: GuideSection[];
  };
}

async function fetchConnectorGuides(
  connectorKey: string,
  apiKey: string,
  authMethodKey?: string
): Promise<AuthGuides> {
  // Browser: btoa(apiKey + ':')
  // Node.js: Buffer.from(apiKey + ':').toString('base64')
  const authHeader = typeof btoa !== 'undefined'
    ? btoa(apiKey + ':')
    : Buffer.from(apiKey + ':').toString('base64');

  const response = await fetch(
    `https://api.stackone.com/actions?include=authentication_guides&filter[connectors]=${connectorKey}`,
    {
      headers: {
        'Authorization': `Basic ${authHeader}`
      }
    }
  );

  const data = await response.json();

  // Normalize connectors list from API response (supports both documented and legacy shapes)
  const connectors = Array.isArray(data?.data)
    ? data.data
    : Array.isArray(data?.results)
    ? data.results
    : [];

  // Find the connector by key
  const connector = connectors.find(
    (c: any) => c.key === connectorKey || c.connector_key === connectorKey
  );

  if (!connector) {
    throw new Error(`Connector "${connectorKey}" not found`);
  }

  // Find the auth method by key, or use the first one
  const auth = authMethodKey
    ? connector.authentication?.find((a: any) => a.key === authMethodKey)
    : connector.authentication?.[0];

  if (!auth) {
    throw new Error(`Auth method not found`);
  }

  return auth.support?.guides || {};
}
```

### 2. Render Content

<Warning>
  Use a proper Markdown parser (like `react-markdown` or `marked`) with HTML sanitization (like `DOMPurify`) instead of regex replacements. The example below is simplified for demonstration and should not be used in production without proper sanitization.
</Warning>

```typescript theme={null}
// PRODUCTION: Use react-markdown + DOMPurify for safe rendering
// Example: import ReactMarkdown from 'react-markdown'
// Example: import DOMPurify from 'dompurify'

function renderGuideContent(content: string): string {
  // SIMPLIFIED EXAMPLE - Add HTML sanitization for production use
  const escapeHtml = (text: string) =>
    text.replace(/[&<>"']/g, (m) => ({
      '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#039;'
    }[m] || m));

  return content
    .replace(/\*\*(.*?)\*\*/g, (_, text) => `<strong>${escapeHtml(text)}</strong>`)
    .replace(/`(.*?)`/g, (_, text) => `<code>${escapeHtml(text)}</code>`)
    .replace(/\[(.*?)\]\((.*?)\)/g, (_, text, url) =>
      `<a href="${escapeHtml(url)}">${escapeHtml(text)}</a>`
    );
}

function renderSection(section: GuideSection): JSX.Element {
  return (
    <div className="guide-section">
      {section.title && <h3>{section.title}</h3>}
      {section.content && (
        <div dangerouslySetInnerHTML={{ __html: renderGuideContent(section.content) }} />
      )}
      {section.list && (
        <ul>
          {section.list.map((item, i) => (
            <li key={i} dangerouslySetInnerHTML={{ __html: renderGuideContent(item) }} />
          ))}
        </ul>
      )}
      {section.steps && section.steps.map((step, i) => (
        <div key={i} className="guide-step">
          {step.title && <h4>{step.title}</h4>}
          {step.content && (
            <div dangerouslySetInnerHTML={{ __html: renderGuideContent(step.content) }} />
          )}
          {step.list && (
            <ul>
              {step.list.map((item, j) => (
                <li key={j} dangerouslySetInnerHTML={{ __html: renderGuideContent(item) }} />
              ))}
            </ul>
          )}
        </div>
      ))}
    </div>
  );
}
```

### 3. Handle Requirement Filtering

```typescript theme={null}
function filterByRequirements(
  sections: GuideSection[],
  selectedRequirements: string[]
): GuideSection[] {
  return sections.filter(section => {
    if (!section.applicableScopes) return true;
    // Show section if any of its requirements are met
    return section.applicableScopes.some(req => selectedRequirements.includes(req));
  });
}
```

***

## Validation

After adding guides to your connector YAML, validate the configuration:

```bash theme={null}
stackone validate connectors/your-provider/your-provider.connector.s1.yaml
```

<Note>
  If you see a warning about `Unknown field 'guides'`, update your CLI to the latest version with `npm install -g @stackone/cli@latest`. The guides field is fully supported at runtime.
</Note>

***

## Testing Your Guides

### 1. Deploy Connector

```bash theme={null}
stackone push connectors/your-provider/ --api-key YOUR_API_KEY
```

### 2. Fetch from API

```bash theme={null}
curl -X GET "https://api.stackone.com/actions?include=authentication_guides&filter[connectors]=your_provider" \
  -H "Authorization: Basic $(echo -n 'YOUR_API_KEY:' | base64)"
```

### 3. Verify Response

Check that:

* [ ] `authentication[].support.guides.config` exists if `configFields` exist
* [ ] `authentication[].support.guides.setup` exists if `setupFields` exist
* [ ] All sections have `title` and `content` or `steps`
* [ ] Links are properly formatted
* [ ] Requirement filters (`applicableScopes`) match your `scopeDefinitions` if used

***

## Migration from Hub Docs

If you have existing guides in separate documentation, you can migrate them to the connector YAML.

### MDX to YAML Mapping

| MDX Element          | YAML Equivalent           |
| -------------------- | ------------------------- |
| `<Warning>` at top   | `warning:` field          |
| `## Section Title`   | `- title: Section Title`  |
| `<Steps>` block      | `steps:` array            |
| `<Step title="...">` | `- title:` in steps       |
| Paragraph content    | `content: \|` (multiline) |
| Bulleted list        | `list:` array             |
| `<Frame><img>`       | Omit (images not in YAML) |
| Links `[text](url)`  | Keep as-is                |

### Example Migration

**From MDX:**

```mdx theme={null}
<Warning>
  Admin privileges required.
</Warning>

## Finding Your API Key

<Steps>
  <Step title="Open Settings">
    Navigate to Settings > API Keys.
    - Click **Generate Key**
    - Copy the key immediately
  </Step>
</Steps>
```

**To YAML:**

```yaml theme={null}
guides:
  config:
    warning: "Admin privileges required."
    sections:
      - title: Finding Your API Key
        content: |
          Generate your API key from the admin dashboard.
        steps:
          - title: Open Settings
            content: |
              Navigate to Settings > API Keys.
            list:
              - Click **Generate Key**
              - Copy the key immediately
```

***

## Next Steps

<CardGroup>
  <Card title="Build Your Connector" icon="wrench" href="/guides/connector-engine/building-first-connector">
    Create the connector YAML configuration
  </Card>

  <Card title="Connector Structure" icon="book" href="/guides/connector-engine/connector-structure">
    Learn about authentication patterns and actions
  </Card>

  <Card title="YAML Reference" icon="file-code" href="/guides/connector-engine/connector-yaml-reference">
    Complete reference for all YAML properties
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/guides/connector-engine/cli-reference">
    Deploy and test connectors with the CLI
  </Card>
</CardGroup>


# Expression Language
Source: https://docs.stackone.com/guides/connector-engine/expression-language

Complete reference for JSONPath, JEXL, and string interpolation expressions in connector YAML

The Falcon engine uses the [`@stackone/expressions`](https://www.npmjs.com/package/@stackone/expressions) library to evaluate dynamic values throughout connector YAML files. Three expression formats are available, each suited to different use cases.

<Tip>
  **Quick rule of thumb:**

  * **JSONPath** (`$.path`) — Direct value access
  * **String Interpolation** (`${...}`) — Building strings/URLs
  * **JEXL** (`'{{...}}'`) — Logic, conditions, and transformations
</Tip>

***

## JSONPath Expressions

When an expression starts with `$`, it is treated as a JSONPath expression. Use this for direct data access without transformation.

### Syntax

| Operator           | Description                        | Example                  |
| ------------------ | ---------------------------------- | ------------------------ |
| `$`                | Root object                        | `$.user.name`            |
| `.`                | Child operator                     | `$.user.name`            |
| `@`                | Current object (in filters)        | `@.age`                  |
| `*`                | Wildcard — all elements/properties | `$.users[*]`             |
| `..`               | Recursive descent                  | `$..name`                |
| `[]`               | Subscript                          | `$.users[0]`             |
| `[,]`              | Union                              | `$.users[0,2]`           |
| `[start:end:step]` | Array slice                        | `$.users[0:2]`           |
| `[?(expression)]`  | Filter expression                  | `$.users[?(@.age > 30)]` |
| `()`               | Script expression                  | Custom expressions       |

### Available Contexts

| Context                   | Description                             | Example                           |
| ------------------------- | --------------------------------------- | --------------------------------- |
| `$.credentials`           | Authentication credentials              | `$.credentials.apiKey`            |
| `$.inputs`                | Action input parameters                 | `$.inputs.userId`                 |
| `$.config`                | Connector configuration                 | `$.config.region`                 |
| `$.steps.{stepId}.output` | Previous step output                    | `$.steps.fetch_users.output.data` |
| `$.response`              | Current response (in response handling) | `$.response.pagination.cursor`    |
| `$.iterator`              | Current foreach iteration context       | `$.iterator.item`                 |

### Examples

```yaml theme={null}
# Simple value access
token: $.credentials.apiKey
value: $.inputs.employee_id

# Step output
dataSource: $.steps.fetch_users.output.data

# Nested access
expression: $.user.address.city

# Bracket notation (for keys with special characters)
value: $["info/email"]

# Array access
value: $.steps.get_all_employees.output.data.employees[0].id

# Wildcard
iterator: $.steps.get_all_employees.output.data.employees[*].id
```

For more details on JSONPath syntax, refer to the [JSONPath specification](https://goessner.net/articles/JsonPath/).

***

## String Interpolation

Use `${...}` syntax to embed values within strings. This is the preferred method for building URLs, composing strings, and simple variable substitution.

### Syntax

```
${variable.path}
```

The content inside `${...}` supports the same dot-notation paths as JSONPath but without the `$` root prefix.

### Examples

```yaml theme={null}
# URL path parameters
url: /users/${inputs.id}
url: /users/${inputs.userId}/posts/${inputs.postId}

# Dynamic base URLs
baseUrl: https://${credentials.subdomain}.api.provider.com
baseUrl: https://api.${credentials.region}.provider.com/v2

# OAuth callback URLs
redirect_uri: ${apiHostUri}/connect/oauth2/${connector}/callback

# Composing strings
value: Bearer ${credentials.accessToken}
```

<Warning>
  String interpolation only substitutes values — it does not support operators, conditionals, or function calls. Use JEXL expressions for logic.
</Warning>

***

## JEXL Expressions

JEXL (JavaScript Expression Language) expressions are enclosed in double curly brackets `{{expression}}` and support variables, operators, functions, and conditional logic. In YAML, these must be wrapped in single quotes: `'{{...}}'`.

### Operators

#### Arithmetic

| Operator | Description                     | Example      | Result |
| -------- | ------------------------------- | ------------ | ------ |
| `+`      | Addition / string concatenation | `{{x + y}}`  | `15`   |
| `-`      | Subtraction                     | `{{x - y}}`  | `5`    |
| `*`      | Multiplication                  | `{{x * 2}}`  | `20`   |
| `/`      | Division                        | `{{x / y}}`  | `2`    |
| `//`     | Floor division                  | `{{7 // 2}}` | `3`    |
| `%`      | Modulus                         | `{{x % 3}}`  | `1`    |
| `^`      | Exponentiation                  | `{{2 ^ 3}}`  | `8`    |

#### Comparison

| Operator | Description                | Example              | Result  |
| -------- | -------------------------- | -------------------- | ------- |
| `==`     | Equal                      | `{{x == 10}}`        | `true`  |
| `!=`     | Not equal                  | `{{x != y}}`         | `true`  |
| `>`      | Greater than               | `{{x > y}}`          | `true`  |
| `>=`     | Greater than or equal      | `{{x >= 10}}`        | `true`  |
| `<`      | Less than                  | `{{x < 100}}`        | `true`  |
| `<=`     | Less than or equal         | `{{x <= 10}}`        | `true`  |
| `in`     | Element of string or array | `{{x in [1, 2, 3]}}` | `false` |

#### Logical

| Operator | Description | Example                 |
| -------- | ----------- | ----------------------- |
| `!`      | Logical NOT | `{{!active}}`           |
| `&&`     | Logical AND | `{{x > 5 && y < 10}}`   |
| `\|\|`   | Logical OR  | `{{x < 5 \|\| y > 10}}` |

#### Special

| Operator | Description        | Example                        |
| -------- | ------------------ | ------------------------------ |
| `? :`    | Ternary operator   | `{{x > 10 ? "big" : "small"}}` |
| `??`     | Nullish coalescing | `{{x ?? "default"}}`           |

### Identifiers and Context Access

Access variables from the evaluation context using dot notation:

```yaml theme={null}
# Given context: { name: { first: "John" }, jobs: ["Developer", "Designer"] }
'{{name.first}}'    # "John"
'{{jobs[1]}}'        # "Designer"
```

### Collection Filtering

Filter arrays using bracket expressions:

```yaml theme={null}
# Given context: { users: [{ name: "John", age: 30 }, { name: "Jane", age: 25 }] }
'{{users[.name == "John"].age}}'   # 30
'{{users[.age > 25].name}}'        # ["John"]
```

### Common Patterns in Connector YAML

```yaml theme={null}
# Conditional argument inclusion
condition: '{{present(inputs.filter)}}'

# Default values
value: '{{inputs.limit || 100}}'
value: '{{$.inputs.status ?? "active"}}'

# Ternary logic
value: '{{$.count > 0 ? $.count : 0}}'

# String concatenation
expression: '{{$.first_name + " " + $.last_name}}'

# Null checking with fallback
value: '{{present(inputs.cursor) ? inputs.cursor : null}}'

# Complex conditionals
condition: '{{present(inputs.start_date) && present(inputs.end_date)}}'
```

***

## Built-in Functions

The expression engine includes a set of built-in functions available in JEXL expressions.

### Presence & Type Checking

#### `present(value)`

Returns `true` if the value is not null or undefined. This is the most commonly used function in connector YAML for conditional argument inclusion.

```yaml theme={null}
# Include query param only if provided
condition: '{{present(inputs.filter)}}'
condition: '{{present(inputs.cursor)}}'

# Check step output exists
condition: '{{present(steps.fetch_data.output.data)}}'
```

| Input                | Result  |
| -------------------- | ------- |
| `present("hello")`   | `true`  |
| `present(0)`         | `true`  |
| `present([])`        | `true`  |
| `present({})`        | `true`  |
| `present(null)`      | `false` |
| `present(undefined)` | `false` |

#### `missing(value)`

Returns `true` if the value is null or undefined. The inverse of `present()`.

```yaml theme={null}
condition: '{{missing(inputs.optional_field)}}'
```

### String Functions

#### `capitalize(value, mode?)`

Capitalizes characters in a string. By default capitalizes the first character; use `'each'` mode to capitalize each word.

```yaml theme={null}
value: '{{capitalize(inputs.name)}}'            # "john" → "John"
value: '{{capitalize(inputs.name, "each")}}'    # "john doe" → "John Doe"
```

#### `truncate(value, maxLength, suffix?)`

Truncates a string to a maximum length, appending a suffix (default `"..."`).

```yaml theme={null}
value: '{{truncate(inputs.description, 100)}}'         # Truncate to 100 chars with "..."
value: '{{truncate(inputs.title, 50, "…")}}'           # Custom suffix
value: '{{truncate(inputs.note, 80, "")}}'              # No suffix
```

#### `padStart(value, targetLength, padString?)`

Pads the start of a string to reach a target length. Numbers are converted to strings automatically.

```yaml theme={null}
value: '{{padStart(inputs.id, 8, "0")}}'    # "42" → "00000042"
value: '{{padStart(5, 3, "0")}}'             # 5 → "005"
```

#### `encodeBase64(value)`

Encodes a string to Base64.

```yaml theme={null}
value: '{{encodeBase64(credentials.apiKey + ":" + credentials.secret)}}'
```

#### `decodeBase64(value)`

Decodes a Base64 string.

```yaml theme={null}
value: '{{decodeBase64(inputs.encoded_data)}}'
```

#### `regexMatch(value, pattern, groupIndex?)`

Extracts a value from a string using a regular expression. Returns the specified capture group (default: `1`) or `null` if no match.

```yaml theme={null}
# Extract cursor from Link header
value: '{{regexMatch(steps.request.output.headers.link, "after=([^&>]+)", 1)}}'

# Extract numeric ID
value: '{{regexMatch(inputs.reference, "user_id=(\\d+)", 1)}}'

# Full match (group 0)
value: '{{regexMatch(inputs.text, "World", 0)}}'
```

#### `extractMatch(value, pattern)`

Similar to `regexMatch` but simplified for common extraction patterns.

```yaml theme={null}
value: '{{extractMatch(inputs.url, "id=(\\w+)")}}'
```

### Crypto Functions

#### `sha256(value, encoding?)`

Computes the SHA-256 hash of a string. Useful for request signing and content verification.

* `value` (string): The string to hash
* `encoding` (string, optional): `'hex'` (default) or `'base64'`
* Returns: hash string, or empty string for invalid input

```yaml theme={null}
value: '{{sha256(inputs.body)}}'
value: '{{sha256(inputs.body, "base64")}}'
```

| Input                       | Result                                |
| --------------------------- | ------------------------------------- |
| `sha256("hello")`           | `"2cf24dba5fb0a30e..."` (64-char hex) |
| `sha256("hello", "base64")` | `"LPJNul+wow4m6Dsq..."` (base64)      |
| `sha256(null)`              | `""`                                  |

#### `hmacSha256(value, key, encoding?)`

Computes an HMAC-SHA256 signature using a secret key. Used for webhook signature verification and API request signing.

* `value` (string): The string to sign
* `key` (string): The secret key
* `encoding` (string, optional): `'hex'` (default) or `'base64'`
* Returns: HMAC digest, or empty string for invalid input

```yaml theme={null}
value: '{{hmacSha256(inputs.body, credentials.signingSecret)}}'
value: '{{hmacSha256(inputs.body, credentials.signingSecret, "base64")}}'
```

| Input                                     | Result                                |
| ----------------------------------------- | ------------------------------------- |
| `hmacSha256("hello", "secret")`           | `"88aab3ede8d3adf9..."` (64-char hex) |
| `hmacSha256("hello", "secret", "base64")` | base64-encoded HMAC                   |
| `hmacSha256(null, "secret")`              | `""`                                  |
| `hmacSha256("hello", null)`               | `""`                                  |

#### `md5(value, encoding?)`

Computes the MD5 hash of a string.

* `value` (string): The string to hash
* `encoding` (string, optional): `'hex'` (default) or `'base64'`
* Returns: hash string, or empty string for invalid input

```yaml theme={null}
value: '{{md5(inputs.body)}}'
value: '{{md5(inputs.body, "base64")}}'
```

| Input                    | Result                               |
| ------------------------ | ------------------------------------ |
| `md5("hello")`           | `"5d41402abc4b2a76b9719d911017c592"` |
| `md5("hello", "base64")` | `"XUFAKrxLKna5cZ2REBfFkg=="`         |
| `md5(null)`              | `""`                                 |

***

### Array Functions

#### `includes(array, value)`

Checks if an array includes a value. If `value` is an array, checks that ALL values are included.

```yaml theme={null}
condition: '{{includes(inputs.roles, "admin")}}'
condition: '{{includes(inputs.scopes, ["read", "write"])}}'   # All must match
```

#### `includesSome(array, value)`

Checks if an array includes AT LEAST ONE of the given values.

```yaml theme={null}
condition: '{{includesSome(inputs.tags, ["urgent", "critical"])}}'
```

#### `dedupe(array)`

Removes duplicate entries from an array, preserving order. Works with primitives and objects (compared by content with sorted keys).

```yaml theme={null}
value: '{{dedupe(steps.merge_data.output.data.ids)}}'
```

| Input                                 | Result               |
| ------------------------------------- | -------------------- |
| `dedupe([1, 2, 2, 3, 1])`             | `[1, 2, 3]`          |
| `dedupe(["a", "b", "a"])`             | `["a", "b"]`         |
| `dedupe([{id: 1}, {id: 2}, {id: 1}])` | `[{id: 1}, {id: 2}]` |

#### `join(array, separator?)`

Joins array elements into a string with a separator (default: `","`). Filters out null/undefined values.

```yaml theme={null}
value: '{{join(inputs.fields, ",")}}'
value: '{{join(inputs.tags, " - ")}}'
value: '{{join(["first", "last"], " ")}}'
```

| Input                       | Result    |
| --------------------------- | --------- |
| `join(["a", "b", "c"])`     | `"a,b,c"` |
| `join(["a", "b"], " - ")`   | `"a - b"` |
| `join(["a", null, "b"])`    | `"a,b"`   |
| `join(["a", "b", "c"], "")` | `"abc"`   |

#### `reduce(array, operation, field?)`

Applies an aggregate operation to an array. When `field` is specified, that field is extracted from each object before applying the operation.

Supported operations:

| Operation   | Description                                                                                                       |
| ----------- | ----------------------------------------------------------------------------------------------------------------- |
| `"sum"`     | Adds all numeric values                                                                                           |
| `"avg"`     | Averages all numeric values                                                                                       |
| `"count"`   | Returns the number of items                                                                                       |
| `"min"`     | Returns the smallest numeric value                                                                                |
| `"max"`     | Returns the largest numeric value                                                                                 |
| `"concat"`  | Extracts an array field from each object (requires `field`) and concatenates the results into a single flat array |
| `"flatten"` | Flattens one level of nesting when the array elements are themselves arrays (no `field` needed)                   |

```yaml theme={null}
# Sum an array of numbers
value: '{{reduce([1, 2, 3], "sum")}}'                                   # 6

# Sum a field across objects
value: '{{reduce(steps.fetch.output.data.items, "sum", "price")}}'

# Average a field across objects
value: '{{reduce(steps.fetch.output.data.scores, "avg", "value")}}'     # 85

# Count items
value: '{{reduce(steps.fetch.output.data.records, "count")}}'

# Concatenate nested arrays from a field
value: '{{reduce(steps.fetch.output.data.items, "concat", "tags")}}'    # ["a", "b", "c"]

# Flatten an array of arrays (no field required)
value: '{{reduce([[1, 2], [3, 4]], "flatten")}}'                        # [1, 2, 3, 4]
```

| Input                                             | Result         |
| ------------------------------------------------- | -------------- |
| `reduce([1, 2, 3], "sum")`                        | `6`            |
| `reduce([{v: 10}, {v: 20}], "sum", "v")`          | `30`           |
| `reduce([{v: 80}, {v: 90}], "avg", "v")`          | `85`           |
| `reduce([1, 2, 3], "count")`                      | `3`            |
| `reduce([{v: 1}, {v: 3}], "max", "v")`            | `3`            |
| `reduce([{t: ["a"]}, {t: ["b"]}], "concat", "t")` | `["a", "b"]`   |
| `reduce([[1, 2], [3, 4]], "flatten")`             | `[1, 2, 3, 4]` |
| `reduce(null, "sum")`                             | `null`         |

### Object Functions

#### `keys(object)`

Returns the keys of an object as an array. Returns empty array for non-objects.

```yaml theme={null}
value: '{{keys(steps.fetch_data.output.data.metadata)}}'
```

#### `values(object)`

Returns the values of an object as an array. Returns empty array for non-objects.

```yaml theme={null}
value: '{{values(steps.fetch_data.output.data.attributes)}}'
```

#### `zipObject(keys, values)`

Combines two parallel arrays into an object by pairing `keys[i]` with `values[i]`. If the arrays are different lengths, extra elements from the longer array are ignored. Non-string keys are skipped. Returns `{}` if either input is missing or not an array.

```yaml theme={null}
# Build an object from field names and values
value: '{{zipObject(steps.fetch.output.data.fields, steps.fetch.output.data.values)}}'

# Combine static keys with dynamic values
value: '{{zipObject(["name", "email"], [inputs.name, inputs.email])}}'
```

| Input                                                        | Result                                      |
| ------------------------------------------------------------ | ------------------------------------------- |
| `zipObject(["a", "b"], [1, 2])`                              | `{a: 1, b: 2}`                              |
| `zipObject(["name", "email"], ["John", "john@example.com"])` | `{name: "John", email: "john@example.com"}` |
| `zipObject(["a", "b", "c"], [1, 2])`                         | `{a: 1, b: 2}`                              |
| `zipObject([], [])`                                          | `{}`                                        |
| `zipObject(null, [1, 2])`                                    | `{}`                                        |

#### `groupBy(array, key)`

Array utility that groups items but returns an object result; it's documented here alongside object helpers for convenience (see the Array Functions section for related utilities). Groups an array of objects by the value of a specified key, producing an object where each unique key value maps to an array of matching items. Items without the key or with a null/undefined value for that key are collected under `"__missing__"`. Returns `{}` if the input is missing, not an array, or the key is not a string.

```yaml theme={null}
# Group employees by department
value: '{{groupBy(steps.fetch.output.data.employees, "department")}}'

# Group by status
value: '{{groupBy(steps.fetch.output.data.records, "status")}}'
```

| Input                                                                                                      | Result                                                           |
| ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `groupBy([{dept: "eng", name: "Alice"}, {dept: "hr", name: "Bob"}, {dept: "eng", name: "Carol"}], "dept")` | `{eng: [{...}, {...}], hr: [{...}]}`                             |
| `groupBy([{status: "active"}, {status: "inactive"}, {status: "active"}], "status")`                        | `{active: [{...}, {...}], inactive: [{...}]}`                    |
| `groupBy([{name: "Alice"}, {status: "active"}], "status")`                                                 | `{__missing__: [{name: "Alice"}], active: [{status: "active"}]}` |
| `groupBy(null, "key")`                                                                                     | `{}`                                                             |

### Date Functions

#### `now()`

Returns the current date/time in ISO 8601 format.

```yaml theme={null}
value: '{{now()}}'   # "2025-04-10T12:00:00.000Z"
```

#### `yearsElapsed(startDate, format, endDate?)`

Calculates the number of complete years between two dates. If `endDate` is omitted, uses today.

```yaml theme={null}
value: '{{yearsElapsed(inputs.hire_date, "yyyy-MM-dd")}}'
value: '{{yearsElapsed("2015-01-01", "yyyy-MM-dd", "2025-01-01")}}'   # 10
```

#### `hasPassed(date, format, yearsToAdd?)`

Checks whether a date (optionally with years added) has already passed.

```yaml theme={null}
condition: '{{hasPassed(inputs.expiry_date, "yyyy-MM-dd")}}'
condition: '{{hasPassed(inputs.start_date, "yyyy-MM-dd", 5)}}'   # Has start + 5 years passed?
```

#### `nextAnniversary(initialDate, format)`

Calculates the next anniversary of a date.

```yaml theme={null}
value: '{{nextAnniversary(inputs.hire_date, "dd/MM/yyyy")}}'
```

#### `deltaFromNowMs(dateInput, format?)`

Calculates milliseconds between a date and now. Supports ISO strings (default), Unix timestamps (`'timestamp'`), and seconds (`'seconds'`).

```yaml theme={null}
value: '{{deltaFromNowMs(inputs.expires_at)}}'
value: '{{deltaFromNowMs(inputs.timestamp, "timestamp")}}'
```

***

## Expression Selection Guide

Choosing the right expression format depends on the context:

| Scenario                        | Format               | Example                                    |
| ------------------------------- | -------------------- | ------------------------------------------ |
| Access a credential value       | JSONPath             | `$.credentials.apiKey`                     |
| Access an input parameter       | JSONPath             | `$.inputs.userId`                          |
| Reference step output           | JSONPath             | `$.steps.fetch.output.data`                |
| Build a URL with parameters     | String Interpolation | `/users/${inputs.id}`                      |
| Dynamic base URL                | String Interpolation | `https://${credentials.subdomain}.api.com` |
| Provide a default value         | JEXL                 | `'{{inputs.limit ?? 100}}'`                |
| Conditional argument            | JEXL                 | `'{{present(inputs.filter)}}'`             |
| Ternary logic                   | JEXL                 | `'{{x > 0 ? x : 0}}'`                      |
| String concatenation with logic | JEXL                 | `'{{inputs.first + " " + inputs.last}}'`   |
| Enum matching                   | JEXL                 | `'{{$.status == "ACTIVE"}}'`               |

<Warning>
  **Do not mix expression formats within a single value.** Use one format per field:

  * **Correct:** `value: '{{$.inputs.limit ?? 25}}'`
  * **Incorrect:** `value: '$.inputs.limit ?? 25'`
</Warning>

***

## Validation and Error Handling

### `isValidExpression(expression)`

The expression engine validates syntax before evaluation. Invalid expressions return errors that help identify issues.

### Incremental JSONPath Errors

When using the expression engine with `incrementalJsonPath: true`, detailed error messages are provided for JSON Path evaluation failures:

```
Key 'age' not found at '$.user.details'. Available keys: name
```

This is used internally by StackOne Agent for self-repair during connector development.

### Safe Evaluation

The `safeEvaluate` function returns `null` instead of throwing errors, which is useful for optional expressions and fallback patterns.


# CI/CD & Deployment
Source: https://docs.stackone.com/guides/connector-engine/github-workflow

Deploy connectors with GitHub Actions and environment-based branch routing

Set up automated validation and deployment for your custom connectors using GitHub Actions.

***

## Overview

The deployment pipeline is fully customizable. You can:

* **Single project**: Push directly to one project on any branch
* **Multi-environment**: Route branches to different projects (dev → staging → prod)
* **Custom workflows**: Define your own branch strategy and approval gates

The example below shows a multi-environment setup, but adapt it to your needs.

<Frame>
  <img alt="CI/CD workflow: Edit YAML → Validate → Push → GitHub Actions → StackOne Projects (dev/staging/prod)" />
</Frame>

***

## Repository Structure

Organize your connectors however works for your team. Example:

```
my-connectors/
├── .github/
│   └── workflows/
│       └── deploy.yml              # CI/CD pipeline
├── connectors/
│   └── {provider}/
│       ├── {provider}.connector.s1.yaml
│       └── {provider}.{resource}.s1.partial.yaml
└── README.md
```

<Tip>
  The [connectors-template](https://github.com/StackOneHQ/connectors-template/) provides a pre-configured Node.js project with git hooks and AI agent instructions if you prefer a starting point.
</Tip>

***

## GitHub Actions Workflow

### Step 1: Add Secrets

Go to **Settings → Secrets and variables → Actions** and add your API key:

| Secret             | Description                       |
| ------------------ | --------------------------------- |
| `STACKONE_API_KEY` | API key for your StackOne project |

### Step 2: Create Workflow File

Create `.github/workflows/deploy.yml`:

<Tabs>
  <Tab title="Simple (Single Project)">
    ```yaml theme={null}
    name: Validate and Deploy Connectors

    on:
      push:
        branches: [main]
        paths:
          - 'connectors/**'
      pull_request:
        branches: [main]
        paths:
          - 'connectors/**'

    jobs:
      validate-and-deploy:
        name: Validate and Deploy
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4

          - name: Setup Node.js
            uses: actions/setup-node@v4
            with:
              node-version: '20'

          - name: Install StackOne CLI
            run: npm install -g @stackone/cli

          - name: Validate connectors
            run: stackone validate connectors/

          - name: Deploy
            if: github.event_name == 'push'
            env:
              STACKONE_API_KEY: ${{ secrets.STACKONE_API_KEY }}
            run: stackone push connectors/ --api-key $STACKONE_API_KEY
    ```
  </Tab>

  <Tab title="Multi-Environment">
    For separate dev/staging/prod projects, add multiple secrets:

    | Secret                     | Description         |
    | -------------------------- | ------------------- |
    | `STACKONE_API_KEY_DEV`     | Development project |
    | `STACKONE_API_KEY_STAGING` | Staging project     |
    | `STACKONE_API_KEY_PROD`    | Production project  |

    ```yaml theme={null}
    name: Validate and Deploy Connectors

    on:
      push:
        branches: [develop, staging, main]
        paths:
          - 'connectors/**'
      pull_request:
        branches: [develop, staging, main]
        paths:
          - 'connectors/**'

    jobs:
      validate:
        name: Validate Connectors
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - uses: actions/setup-node@v4
            with:
              node-version: '20'
          - run: npm install -g @stackone/cli
          - run: stackone validate connectors/

      deploy-dev:
        needs: validate
        if: github.ref == 'refs/heads/develop' && github.event_name == 'push'
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - uses: actions/setup-node@v4
            with:
              node-version: '20'
          - run: npm install -g @stackone/cli
          - run: stackone push connectors/ --api-key ${{ secrets.STACKONE_API_KEY_DEV }}

      deploy-staging:
        needs: validate
        if: github.ref == 'refs/heads/staging' && github.event_name == 'push'
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - uses: actions/setup-node@v4
            with:
              node-version: '20'
          - run: npm install -g @stackone/cli
          - run: stackone push connectors/ --api-key ${{ secrets.STACKONE_API_KEY_STAGING }}

      deploy-prod:
        needs: validate
        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
        runs-on: ubuntu-latest
        environment: production  # Optional: require manual approval
        steps:
          - uses: actions/checkout@v4
          - uses: actions/setup-node@v4
            with:
              node-version: '20'
          - run: npm install -g @stackone/cli
          - run: stackone push connectors/ --api-key ${{ secrets.STACKONE_API_KEY_PROD }}
    ```
  </Tab>
</Tabs>

***

## Git Hooks (Optional)

If using the [connectors-template](https://github.com/StackOneHQ/connectors-template/), it includes git hooks:

| Hook           | Purpose                                 |
| -------------- | --------------------------------------- |
| **Pre-commit** | Runs linting before each commit         |
| **Post-merge** | Auto-updates dependencies after pulling |

```bash theme={null}
# Reinstall hooks if needed
npm run setup:hooks
```

***

## Local Development

### Configure Profiles (Optional)

Save API keys for quick access:

```bash theme={null}
stackone config set --profile myproject --api-key v1.eu1.xxxxx
```

### Development Workflow

```bash theme={null}
# Edit connector
vim connectors/provider/provider.connector.s1.yaml

# Validate (with watch mode)
stackone validate connectors/provider/ --watch

# Test locally
stackone run \
  --connector connectors/provider/provider.connector.s1.yaml \
  --account account.json \
  --credentials credentials.json \
  --action-id list_employees

# Push manually (or let CI handle it)
stackone push connectors/provider/ --profile myproject
```

***

## Testing After Deployment

Before testing in the Playground, you need a linked account:

<Steps>
  <Step title="Configure the Integration">
    Enable your custom connector in the [Connector Profiles](https://app.stackone.com/connector_profiles) page.

    <Card title="Connector Profiles Guide" icon="gear" href="/guides/connector-profiles" />
  </Step>

  <Step title="Link an Account">
    Create a linked account using StackOne Connect or the API.
  </Step>

  <Step title="Test in Playground">
    Go to [app.stackone.com/playground](https://app.stackone.com/playground), select your linked account, and test actions.
  </Step>

  <Step title="Iterate">
    Refine your connector based on test results, push updates, and repeat. Each deployment is additive, so you can continuously improve without breaking existing functionality.
  </Step>
</Steps>

**Alternative: Test via CLI**

You can also test directly using the CLI with an account ID:

```bash theme={null}
stackone run \
  --connector connectors/provider/provider.connector.s1.yaml \
  --account-id your_account_id \
  --profile myproject \
  --action-id list_employees
```

<Note>
  Your profile must have an API key with the appropriate credentials scope to access the linked account.
</Note>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Validation fails in CI">
    * Check YAML indentation (2 spaces, not tabs)
    * Ensure partial files start with `-` not `actions:`
    * Verify all `$ref` references match file names
    * Run validation locally first
  </Accordion>

  <Accordion title="Push fails with authentication error">
    * Verify API key secret is set correctly
    * Check the key has permissions for the target project
    * Ensure secret names match workflow file
  </Accordion>

  <Accordion title="Workflow not triggering">
    * Verify workflow file is in `.github/workflows/`
    * Check branch names match triggers
    * Ensure `paths` filter includes changed files
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup>
  <Card title="CLI Reference" icon="terminal" href="/guides/connector-engine/cli-reference">
    All CLI commands
  </Card>

  <Card title="StackOne Agent" icon="robot" href="/guides/connector-engine/stackone-agent">
    AI-powered connector generation
  </Card>
</CardGroup>


# Build Connectors
Source: https://docs.stackone.com/guides/connector-engine/introduction

Create custom connectors and make them available in your StackOne projects

StackOne's **Connector Engine** (aka *Falcon*) powers all 200+ pre-built connectors. You can use the same engine to build your own.

<Info>
  This workflow is optimized for **[Claude Code](https://claude.com/claude-code)**, which excels at tool calling and long-horizon tasks required for connector development. The MCP server and tools also work with other AI coding agents like Cursor, VS Code with Claude, and opencode.
</Info>

<Note>
  Custom connectors require enterprise access. Contact [support@stackone.com](mailto:support@stackone.com) for access.
</Note>

***

## How It Works

StackOne Connectors are YAML configurations that define API interactions. Once deployed, StackOne automatically exposes your connector through **multiple protocols**:

<CardGroup>
  <Card title="Actions API" icon="code">
    REST endpoints at `api.stackone.com` for traditional backend integrations
  </Card>

  <Card title="MCP Servers" icon="robot">
    Model Context Protocol for AI agents like Claude Code and Cursor
  </Card>

  <Card title="AI Toolset" icon="wrench">
    TypeScript and Python SDKs optimized for LLM tool calling
  </Card>
</CardGroup>

Write your connector once. It works across all StackOne protocols, whether your users are building traditional apps, AI agents, or both.

***

## When to Build Custom Connectors

<CardGroup>
  <Card title="Internal Systems" icon="building">
    Connect proprietary APIs or custom-built tools
  </Card>

  <Card title="Provider-Specific Actions" icon="plus">
    Add actions not covered by standard connectors
  </Card>

  <Card title="Niche Providers" icon="puzzle-piece">
    Support vertical-specific SaaS not in our catalog
  </Card>

  <Card title="Custom Mappings" icon="arrows-rotate">
    Transform data to match your requirements
  </Card>
</CardGroup>

***

## Prerequisites

* StackOne Agent Credentials (Contact [support@stackone.com](mailto:support@stackone.com) to request your agent credentials)
* StackOne CLI (`@stackone/cli`)
* API key with **Connectors** scopes enabled (see [API Keys](/guides/api-keys#configure-api-key-scopes-optional))
  * `connectors:read`: required to download connectors from the registry
  * `connectors:write`: required to push and delete connectors
  * `credentials:read`: required so the `run` command can use the credentials of the specified linked account

***

## Quickstart

<Steps>
  <Step title="Install the CLI">
    ```bash theme={null}
    npm install -g @stackone/cli
    ```

    <Tip>
      **Using Node.js?** Fork the [connectors-template](https://github.com/StackOneHQ/connectors-template/) for a pre-configured project structure with CI/CD workflows.
    </Tip>
  </Step>

  <Step title="Learn from Existing Connectors (Optional)">
    Download existing connectors to understand the YAML structure:

    ```bash theme={null}
    # Download a connector as reference
    stackone get bamboohr@1.0.1 --output ./examples/

    # View the structure
    ls ./examples/bamboohr/
    ```

    This gives you working examples of authentication patterns, pagination, and action definitions.
  </Step>

  <Step title="Authenticate">
    ```bash theme={null}
    stackone agent setup --global
    ```

    This authenticates via OAuth, stores your access token, and configures MCP tools for AI-assisted development. Use `--local` to scope to the current project only.
  </Step>

  <Step title="Build Your Connector">
    <Tabs>
      <Tab title="AI-Assisted (Recommended)">
        Open your IDE (Cursor or VS Code with Claude) and prompt:

        ```
        Build a connector for [Provider Name] with employee management actions.
        ```

        The AI agent will research the API, generate YAML, validate syntax, and test actions automatically.

        <Card title="StackOne Agent Details" icon="robot" href="/guides/connector-engine/stackone-agent" />
      </Tab>

      <Tab title="Manual">
        Create your connector files:

        ```
        your-provider/
        ├── your-provider.connector.s1.yaml
        ├── your-provider.employees.s1.partial.yaml
        └── your-provider.time_off.s1.partial.yaml
        ```

        **Main connector file:**

        ```yaml theme={null}
        # your-provider.connector.s1.yaml
        StackOne: 1.0.0
        info:
          title: Your Provider
          key: your_provider
          version: 1.0.0
          description: Your Provider connector

        baseUrl: https://api.yourprovider.com/v1

        authentication:
          - custom:
              type: custom
              label: API Key
              authorization:
                type: bearer
                token: $.credentials.apiKey
              configFields:
                - key: apiKey
                  label: API Key
                  type: password
                  required: true
                  secret: true

        actions:
          $ref: your_provider.employees
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Validate">
    ```bash theme={null}
    stackone validate your-provider/
    ```
  </Step>

  <Step title="Test">
    Create test files and run an action:

    ```bash theme={null}
    # Create test config
    echo '{"environment": "production", "provider": "your_provider"}' > account.json
    echo '{"apiKey": "your_test_api_key"}' > credentials.json

    # Run action
    stackone run \
      --connector your-provider/your-provider.connector.s1.yaml \
      --account account.json \
      --credentials credentials.json \
      --action-id list_employees \
      --debug
    ```

    <Tip>
      **Faster iteration:** Once your connector is pushed or an account is already linked, skip the credentials file and use `--account-id` instead:

      ```bash theme={null}
      stackone run \
        --connector your-provider/your-provider.connector.s1.yaml \
        --account-id acme-corp-provider \
        --action-id list_employees
      ```

      This uses stored credentials from the linked account, making it easier to iterate on action logic.
    </Tip>
  </Step>

  <Step title="Deploy">
    ```bash theme={null}
    stackone push your-provider/ --api-key YOUR_API_KEY
    ```

    Or set up CI/CD for automatic deployment:

    <Card title="CI/CD Setup" icon="github" href="/guides/connector-engine/github-workflow" />
  </Step>
</Steps>

***

## Key Capabilities

| Feature               | Description                                                            |
| --------------------- | ---------------------------------------------------------------------- |
| **Step Functions**    | `request`, `paginated_request`, `map_fields`, `typecast`, `group_data` |
| **Authentication**    | OAuth2, API Key, Basic Auth, Custom headers                            |
| **Expressions**       | JSONPath, String interpolation, JEXL templates                         |
| **Pagination**        | Cursor, offset, and page-based pagination                              |
| **Conditional Logic** | Include arguments only when conditions are met                         |
| **Rate Limiting**     | Built-in request throttling                                            |

***

## Next Steps

<CardGroup>
  <Card title="Build Your First Connector" icon="rocket" href="/guides/connector-engine/building-first-connector">
    Step-by-step guide from setup to deployment
  </Card>

  <Card title="Feature Reference" icon="book" href="/guides/connector-engine/connector-structure">
    All YAML engine capabilities
  </Card>

  <Card title="StackOne Agent" icon="robot" href="/guides/connector-engine/stackone-agent">
    AI-powered connector generation
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/guides/connector-engine/cli-reference">
    All CLI commands
  </Card>
</CardGroup>


# StackOne Agent
Source: https://docs.stackone.com/guides/connector-engine/stackone-agent

Build connectors with AI using Claude Code, Cursor, or any MCP-compatible IDE

The **StackOne Agent** is an AI assistant that creates complete StackOne Connector configurations. It can run inside a coding agent (Claude Code preferred, Cursor or others supported) and is also available as a standalone agent (no separate coding agent subscription required when used standalone). It leverages 20+ specialised MCP tools to research APIs, generate and validate YAML, and exhaustively test actions using the Falcon execution engine.

<Note>
  StackOne Agent is in early access. Contact [support@stackone.com](mailto:support@stackone.com) for credentials.
</Note>

***

## What It Does

<CardGroup>
  <Card title="Research APIs" icon="magnifying-glass">
    Discovers provider documentation and endpoints automatically
  </Card>

  <Card title="Generate YAML" icon="file-code">
    Creates complete connector configurations following the Falcon spec
  </Card>

  <Card title="Validate & Test" icon="flask">
    Validates syntax and tests actions against real APIs
  </Card>

  <Card title="MCP Testing" icon="comments">
    Conversational testing with automatic tool description improvements
  </Card>
</CardGroup>

***

## Setup

### Step 1: Install Dependencies

```bash theme={null}
npm install -g @stackone/cli
```

### Step 2: Fork the Template Repository

```bash theme={null}
git clone https://github.com/YOUR-ORG/connectors-template.git
cd connectors-template
npm install
```

### Step 3: Configure MCP Tools

```bash theme={null}
npx @stackone/cli agent setup --local
```

This configures your IDE with the MCP server connection. The agent credentials are stored securely as environment variables.

### Step 4: Start Building

Open your IDE and prompt:

```
Build a connector for HiBob HRIS with employee management actions.
```

***

## How It Works

The agent follows a strict 8-step workflow:

<Frame>
  <img alt="StackOne Agent workflow: Research → Version Validation → Config Building → YAML Validation → MCP Testing → Description Refinement → Security → Meta Feedback" />
</Frame>

1. **Research** - Discovers API documentation and endpoints
2. **Version Validation** - Resolves API version conflicts
3. **Config Building** - Generates YAML with all actions
4. **YAML Validation** - Runs `stackone validate`
5. **MCP Testing** - Conversational testing via MCP skill
6. **Description Refinement** - Improves tool descriptions based on test results
7. **Security** - Scrambles credentials before storage
8. **Meta Feedback** - Reports results for improvement

***

## MCP Tools

The agent has access to 20+ specialized tools:

### Research Tools

| Tool                   | Description                             |
| ---------------------- | --------------------------------------- |
| `discover_actions`     | Autonomous API discovery (5-15 min)     |
| `get_provider_actions` | Check S3 for indexed actions            |
| `vector_search`        | Semantic search StackOne knowledge base |
| `web_search`           | Web search for API documentation        |
| `fetch`                | Retrieve content from URLs              |

### Analysis Tools

| Tool                        | Description                                  |
| --------------------------- | -------------------------------------------- |
| `analyze_versioning`        | Detect and resolve API version conflicts     |
| `get_external_integrations` | Find how others integrate with the provider  |
| `scan_external_repo`        | Search open-source connector implementations |
| `extract_oas_actions`       | Parse OpenAPI specifications                 |

### Validation Tools

| Tool                   | Description                       |
| ---------------------- | --------------------------------- |
| `test_actions`         | Batch test connector actions      |
| `scramble_credentials` | Secure credentials before storage |

### StackOne Context

| Tool                      | Description                            |
| ------------------------- | -------------------------------------- |
| `get_stackone_categories` | Available categories (hris, ats, crm)  |
| `get_stackone_actions`    | Unified operations for a category      |
| `get_provider_coverage`   | Current StackOne coverage for provider |
| `get_docs`                | StackOne documentation index           |

***

## Agent Instructions

The agent's behavior is defined in `CLAUDE.md` at your repository root. Key sections:

**Workflow:** Strict 11-step process from research to completion

**Naming Conventions:**

* Provider folder: `connectors/provider/` (lowercase)
* Config file: `provider.connector.s1.yaml`

**Quality Standards:**

* Clear descriptions (1-2 sentences) for all operations
* Full CRUD operations where applicable
* Error handling and rate limiting
* Conversational MCP testing for validation

<Card title="CLAUDE.md - Agent Instructions" icon="github" href="https://github.com/StackOneHQ/connectors-template/blob/main/CLAUDE.md">
  View the complete agent instructions and MCP tool documentation on GitHub.
</Card>

***

## Example Session

**You:**

> Create a connector for HiBob HRIS with employee management actions

**Agent:**

> I'll start by researching the HiBob API. Launching action discovery...
>
> \[Uses `discover_actions("hibob")`]
> \[Uses `get_stackone_actions("hris")`]
> \[Uses `vector_search("authentication", "hibob")`]
>
> Based on my research, HiBob uses Basic Auth with a service user ID and token.
> I've identified 15 relevant endpoints. Creating the connector configuration...

The agent creates:

* `connectors/hibob/hibob.connector.s1.yaml` (main file)
* `connectors/hibob/hibob.employees.s1.partial.yaml`
* `connectors/hibob/hibob.time_off.s1.partial.yaml`

Then validates, tests all actions, and reports completion.

***

## MCP Testing Skill

The agent includes a built-in MCP testing skill for conversational validation:

<Card title="MCP Testing Skill" icon="github" href="https://github.com/StackOneHQ/connectors-template/tree/main/.claude/skills/test-mcp-connector">
  View the test-mcp-connector skill that enables conversational testing with automatic tool description improvements.
</Card>

**Key features:**

* **Conversational testing** - Test actions through natural language prompts
* **Tool description refinement** - Automatically improves descriptions based on test results
* **Real API validation** - Tests against actual provider endpoints

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="MCP server not connecting">
    * Run `stackone agent setup --local` again
    * Verify credentials are correct
    * Restart your IDE after setup
    * Check that `.cursor/mcp.json` or equivalent was created
  </Accordion>

  <Accordion title="Agent not using tools">
    * Verify `CLAUDE.md` is at repository root
    * Check MCP configuration in IDE settings
    * Ensure the file follows the correct format
  </Accordion>

  <Accordion title="Validation errors">
    * Run `stackone validate <file>` manually
    * Check `connectors/README.md` for YAML structure
    * Ensure all required fields are present
  </Accordion>

  <Accordion title="Test failures">
    * Use `--debug` flag to see full request/response
    * Verify credentials are correct and not expired
    * Check action IDs match exactly (case-sensitive)
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup>
  <Card title="Connector Structure" icon="book" href="/guides/connector-engine/connector-structure">
    Complete YAML configuration reference
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/guides/connector-engine/cli-reference">
    All CLI commands
  </Card>
</CardGroup>


# Connector Profiles
Source: https://docs.stackone.com/guides/connector-profiles

Enable, disable, and manage connector profiles in any StackOne Project

<Info>
  **Auth Configs are now Connector Profiles.**

  Functionality remains the same — you'll just see them called Connector Profiles across the dashboard and docs.
</Info>

The [*Connector Profiles*](https://app.stackone.com/connector_profiles) section of the StackOne dashboard allows you to manage connectors for a [StackOne Project](./managing-projects).

On the Connectors page, you can:

* **View** the list of all connectors for all the categories supported by StackOne (e.g., `HRIS`, `ATS`, `IAM`, `CRM`, `Marketing`, `LMS`, and more). Some connectors and categories are only available based on your plan or contract. If you do not see a category or connector that you would like, contact your support manager.
* **Enable**, configure, and disable connectors.
* Quickly **access** linked accounts and logs related to the connectors
* **Delete** connector profiles

<Note>
  Each connector profile resolves to a specific connector version. See [Connector Versioning](./connector-versioning) for how version selection works and how to pin a version.
</Note>

## Configuring your first connector

To configure your first connector, navigate to the [*Connector Profiles*](https://app.stackone.com/connector_profiles) section and click on the `+` button.

<Frame>
  <img alt="" />
</Frame>

You will be presented with a list of connectors to choose from. Select the connector you want to configure.

<Frame>
  <img alt="" />
</Frame>

You can also search for a specific connector by name.

<Frame>
  <img alt="" />
</Frame>

Once you have selected the connector, you will be presented with a form to configure the auth settings.

<Frame>
  <img alt="" />
</Frame>

Fill in the form with the required information and click the `Save` button. You will notice a "Default Configuration" dropdown that allows you to mark a connector profile as the default for that connector in the project. You can change the default later once you have multiple profiles for the same connector.

Once you have configured the connector, you will see it in the list of connectors.

<Frame>
  <img alt="" />
</Frame>

## Managing connectors

### Enabling and disabling connectors

**Setting up** a connector for the first time will automatically set its state as `enabled`, meaning it will be displayed in the StackOne Hub and you will be able to retrieve a [Connect Session token](/platform/api-reference/connect-sessions/) with the associated provider key.

When **disabling** a connector, a warning will appear. Note that disabling a connector with linked accounts will make all those accounts go into an `inactive` status, and API requests to these accounts will not be permitted. You can switch any connector back to an **enabled** state just as easily, which will reset all associated linked accounts to an `active` status.

<Frame>
  <img alt="" />
</Frame>

<Note>
  Connector settings are scoped to a specific project. If you need a connector to be configured on multiple StackOne projects, you will have to configure it for each individual project.
</Note>

### Ellipsis menu options

The ellipsis menu on each connector row provides the following options:

* **Edit** - Modify the connector profile
* **View logs** - See logs for this connector
* **Copy connector ID** - Copy identifiers for API use
* **Disable** - Temporarily disable the connector
* **Delete** - Remove the connector profile (only available if no linked accounts exist and it's not the sole default)
* **Make default** - Set as the default connector profile (only shown for non-default profiles when multiple exist)

<Frame>
  <img alt="" />
</Frame>

### Editing an existing connector profile

To modify an existing connector profile (such as updating the allowed actions, changing OAuth client details, updating scopes), click the **Edit** option from the ellipsis menu.

<Frame>
  <img alt="" />
</Frame>

In the edit form, you can:

* **Update the profile name** - Change the name of the connector profile to help distinguish between different profiles for the same connector
* **Update allowed actions** - Add or remove allowed actions for the connector
* **Update OAuth credentials** - Change Client ID, Client Secret, or other OAuth parameters
* **Adjust scopes** - Add or remove permission scopes for OAuth integrations

<Note>
  You cannot change the authentication type (e.g., from API Key to OAuth) when editing an existing connector profile. To switch authentication types, you must delete the current profile and create a new one with the desired auth type.
</Note>

After making your changes, click **Save** to update the connector profile. The changes will take effect immediately for new account connections, while existing linked accounts will continue using their previous settings.

### Deleting a connector profile

You'll only be able to delete a connector profile if there are no linked accounts for it, and if it's either the only profile for the connector or a non-default profile.

## Authentication types

When setting up or updating a connector, you are configuring a specific **authentication type**. The authentication type determines the process for your end-user to link their account for that provider, specifically which details or credentials they will need to submit.

### API Key and Basic Token

In most instances, you will see `API Key` or `Basic Token`, in which case the end-user will need to generate the required secret (e.g., [Ashby](https://hub.stackone.com/en/articles/7727335-ashby) or [Hibob](https://hub.stackone.com/en/articles/8233374-hibob-service-user-authentication)).

### OAuth-based authentications

For other connectors, you may have a choice of `OAuth` (and similar, e.g., `OIDC`), in which case your user may experience a simpler login-like flow (e.g., [Lever](https://hub.stackone.com/en/articles/7992510-lever) or [Hubspot](https://hub.stackone.com/en/articles/8005663-hubspot)).

Some connectors will prompt for OAuth-based fields such as `Client ID` and `Client Secret`.

You can use StackOne-provided credentials for testing, but for production you should register your own OAuth apps. Your own credentials give you:

* Your brand on OAuth consent screens (instead of "StackOne")
* Dedicated rate limits (not shared with other StackOne users)
* Compliance with marketplace requirements if you plan to list your integration

<Card title="OAuth Apps →" icon="key" href="/guides/using-your-own-oauth-apps">
  When and why to use your own OAuth credentials
</Card>

<Info>
  When configuring an OAuth application with a provider, you may be asked for a Callback or Redirect URI. Make sure to use `https://api.stackone.com/connect/oauth2/{provider key}/callback` (replace `{provider key}` with the actual key, for example: `hubspot` or `bamboohr`).
</Info>

### Configuring multiple connector profiles for the same connector

You can configure multiple connector profiles for the same connector. This is useful if you want to use different configurations for the same connector for different groups of accounts in the same project, for example if some accounts need to be linked with an API key and others with an OAuth token.

To configure multiple connector profiles for the same connector, you can go to the [Connector Profiles page](https://app.stackone.com/connector_profiles) and click on the `+` button. You will be presented with the same form as before, and you will be able to configure whether this profile should be the default for the connector or not.

You can toggle the default connector profile by clicking on the "Make default" option mentioned in the ellipsis menu options section above.

For example, with the Airtable connector we used in the previous example, we previously set up an API Key connector profile. Now we want to set up an OAuth 2.0 connector profile.

<Frame>
  <img alt="" />
</Frame>

If we set the API Key connector profile as the default, in the hub we'll show the API Key setup fields. In this case, the difference between the two is the OAuth authorization flow.

<Frame>
  <img alt="" />
</Frame>

However, if we set the OAuth 2.0 connector profile as the default, in the hub we'll show the OAuth 2.0 setup fields. Notice the different authentication flow presented to users.

<Frame>
  <img alt="" />
</Frame>

You will be able to select which specific connector profile to use in the hub in the future without having to toggle the default for the connector back and forth.

## Connector versions and pinning

Each connector profile has an independent version pin that controls which connector version its linked accounts use. By default, a connector profile uses the latest available version for the connector.

You can set the pin to:

* `latest` — always use the newest version
* `1.x.x` — track minor and patch releases within a major version (recommended for production)
* `1.2.0` — lock to an exact version

The pin can be set from the version selector when editing a connector profile, or via the API. For the full details on pin formats, migration strategies, and how to handle connector breaking changes, see [Connector Version Management](/guides/connector-versioning).

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connector or account not visible on the Connectors page">
    If you cannot see a specific connector or account on the [Connector Profiles page](https://app.stackone.com/connector_profiles), the connector likely needs to be enabled for your account by StackOne.

    Contact your StackOne support manager or reach out to [support@stackone.com](mailto:support@stackone.com) to request access. Connector and category availability depends on your plan and contract.
  </Accordion>

  <Accordion title="Connector not visible in the StackOne Hub">
    If the connector is visible on the Connectors page but not in the Hub, it's typically because the connector is disabled. Enable it from the Connectors page.
  </Accordion>

  <Accordion title="Wrong fields being shown in the StackOne Hub">
    Verify that the correct connector profile is set as the default for the connector. If you have multiple profiles for the same connector, only the default one's fields are shown in the Hub.
  </Accordion>

  <Accordion title="Connection issues behind a firewall">
    If your infrastructure is behind a firewall, allowlist these StackOne IP addresses:

    | IP Address     | Location |
    | -------------- | -------- |
    | 35.175.11.132  | US East  |
    | 54.221.239.152 | US East  |
    | 52.5.1.25      | US East  |
    | 34.249.109.57  | Ireland  |
    | 46.51.152.189  | Ireland  |
    | 52.51.165.231  | Ireland  |
    | 18.135.210.22  | UK       |
    | 18.169.58.64   | UK       |
    | 13.40.58.44    | UK       |

    API traffic routes through [AWS Edge Locations](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/LocationsOfEdgeServers.html), so you may also need to allow those. For webhooks, allow inbound traffic from the IPs above. All API requests use HTTPS with TLS 1.2+.
  </Accordion>
</AccordionGroup>


# Connector Versioning
Source: https://docs.stackone.com/guides/connector-versioning

Connector versioning ensures your linked accounts aren't affected by breaking changes until you're ready to adopt them. Pin each connector profile to a version and upgrade on your own schedule.

Connectors are versioned with semver (`major.minor.patch`). Each connector profile resolves to a specific connector version when linked accounts make requests. Because each connector profile pins independently, you can test a new version against a staging profile before rolling it out to production, and migrate different customer groups to a new connector version at their own pace.

## Version selection

By default, a connector profile resolves to:

1. The latest **custom** version of the connector, if one exists in your project.
2. Otherwise, the latest **StackOne** version.

Custom connectors are connectors you build and publish yourself using the [Falcon framework](/guides/connector-engine/overview). If you only use StackOne's built-in connectors, item 1 never applies — all requests resolve to item 2.

Custom connectors always take precedence over StackOne connectors with the same key, including when version numbers match. Publishing a new StackOne version does not override a custom connector with the same key.

### Pinning a version

When creating or editing a connector profile, you can override the default and pin the version to:

* **Latest StackOne** - always resolves to the latest published StackOne version, ignoring custom versions. Use this when you rely on StackOne's managed updates.
* **Latest custom** - always resolves to the latest published custom version. Use this when you maintain your own connector and want deploys to roll out automatically.
* **A specific version** - pin to an exact version number (StackOne or custom). Use this in production when you need full control over when updates apply.

When pinned to a "latest" option, existing linked accounts automatically pick up new versions as they are published. When pinned to a specific version, linked accounts stay on that version until the pin is changed.

The accepted pin formats are:

| Pin        | Resolves to                                      | Auto-updates        |
| ---------- | ------------------------------------------------ | ------------------- |
| `latest`   | Newest version (custom if exists, else StackOne) | Yes                 |
| `1.x.x`    | Latest minor + patch within major version 1      | Yes, within major 1 |
| `1.2.x`    | Latest patch within 1.2.\*                       | Yes, patch only     |
| `1.2.0`    | Exactly 1.2.0, never changes                     | No                  |
| *(no pin)* | Custom latest if exists, else StackOne latest    | Yes                 |

Note: npm-style caret (`^1.2.0`) and tilde (`~1.2`) are not accepted.

You can set the pin when editing a connector profile in the dashboard, or via the API:

```bash theme={null}
curl -X PUT https://api.stackone.com/connector_profiles/{connector_profile_id}/pinned_version \
  -H "Authorization: Basic <base64(api_key:)>" \
  -H "Content-Type: application/json" \
  -d '{"pinned_version": "1.x.x"}'
```

To revert to the default resolution (custom latest, then StackOne latest):

```bash theme={null}
curl -X DELETE https://api.stackone.com/connector_profiles/{connector_profile_id}/pinned_version \
  -H "Authorization: Basic <base64(api_key:)>"
```

<Tip>
  Pin production connector profiles to a major version wildcard — for example `1.x.x` rather than `latest`. A new major version can include auth or scope changes that break existing linked accounts if they upgrade without warning. With `1.x.x`, you pick up bug fixes and new optional fields automatically while keeping control over breaking upgrades.
</Tip>

## Breaking changes and version updates

This is how StackOne classifies changes when versioning its built-in connectors. Understanding these categories helps you interpret what a version bump means and whether it requires action on your end.

Publishing a new connector version does not invalidate existing linked accounts. Accounts continue to work and automatically pick up the new version on the next request, provided the connector profile is on an auto-updating pin (`latest`, `1.x.x`, or `1.2.x`). Accounts pinned to a specific version remain on that version until the pin is manually updated.

Any change that is not backwards compatible is released as a new **major** version. This includes, but is not limited to:

* **Authentication changes** - switching auth type, adding required scopes, or changing required credential fields. These require linked accounts to re-authenticate.
* **Response shape changes** - renaming or removing fields, changing field types, or restructuring nested objects in an action's response.
* **Request shape changes** - renaming or removing parameters, making optional parameters required, or changing accepted value types.
* **Removed or renamed actions** - any action that callers may currently reference.
* **Behavioural changes** - changes to pagination, filtering, error semantics, or default values that consumers may have relied on.

| Version bump            | Example change                                                                                 | Breaking for consumers |
| ----------------------- | ---------------------------------------------------------------------------------------------- | ---------------------- |
| Patch (`1.2.3 → 1.2.4`) | Bug fix, description update, internal refactor                                                 | No                     |
| Minor (`1.2.3 → 1.3.0`) | New action, new optional parameter, new optional response field                                | No                     |
| Major (`1.2.3 → 2.0.0`) | New auth type or required scope, removed/renamed field, changed response shape, removed action | Yes                    |

## Versioning strategy

When building custom connectors, you set your own versioning convention. The version number communicates what kind of migration work a change requires for anyone pinned to it.

Auth-breaking changes — new OAuth flow, required scopes, or changed credential fields — require end users to reauthenticate. These almost always warrant a major version bump. The migration involves creating a new connector profile and prompting users through a new connect flow.

A common approach:

| Level     | Use for                                        | Who needs to act                                          |
| --------- | ---------------------------------------------- | --------------------------------------------------------- |
| **Major** | Auth flow or scope changes                     | Your end users — they reauthenticate through the new flow |
| **Minor** | New actions, new optional fields or parameters | Nobody — existing code keeps working                      |
| **Patch** | Bug fixes, internal refactors                  | Nobody — existing code keeps working                      |

The version level is your contract with yourself — pick the convention that makes your migration work predictable.

## Checking available versions

To see every published version for a connector profile and which one is currently active:

```bash theme={null}
curl https://api.stackone.com/connector_profiles/{connector_profile_id}/versions \
  -H "Authorization: Basic <base64(api_key:)>"
```

```json theme={null}
[
  {
    "version": "1.0.0",
    "pinned": false,
    "builtin": true,
    "owner": "stackone"
  },
  {
    "version": "1.2.0",
    "pinned": true,
    "builtin": true,
    "owner": "stackone"
  }
]
```

The `pinned: true` entry is the version currently serving requests for this connector profile. Note that the response shows the resolved exact version (`1.2.0`), not the pin format (`1.2.x`) — the pin itself is set on the connector profile, not returned here.

## Migrating to a new version

### Non-breaking releases

For releases your team has classified as non-breaking (patch fixes, new optional fields, additive changes), connector profiles pinned to `latest`, a major wildcard (`1.x.x`), or a minor wildcard (`1.2.x`) will pick up the new version automatically on the next request — no action required.

If your connector profile is pinned to an exact version (e.g. `1.2.0`), it won't move until you update the pin manually:

```bash theme={null}
curl -X PUT https://api.stackone.com/connector_profiles/{connector_profile_id}/pinned_version \
  -H "Authorization: Basic <base64(api_key:)>" \
  -H "Content-Type: application/json" \
  -d '{"pinned_version": "1.2.1"}'
```

### Auth/permissions breaking changes

When a connector introduces a new OAuth flow or required scope, existing accounts stay on their current connector profile until you explicitly migrate them. This is a coordinated rollout rather than a silent upgrade.

<Steps>
  <Step title="Create a new connector profile pinned to the new major version">
    The existing connector profile and all accounts on it are untouched. This new profile handles the updated auth flow.
  </Step>

  <Step title="Get the connector_profile_id for the new connector profile">
    Call [`GET /connector_profiles`](/platform/api-reference/connector-profiles/list-connector-profiles) and read the `id` of the profile you created. Pass that value as `connector_profile_id` when creating connect sessions. (`integration_id` is a deprecated alias for the same field in some payloads.)
  </Step>

  <Step title="Issue connect session tokens for the new connector profile">
    Pass `connector_profile_id` explicitly when creating connect sessions — this routes the session to the new profile. Alternatively, make the new connector profile the project default and omit `connector_profile_id`.

    See [Using connect sessions with specific connector profiles](/platform/connect-your-backend-with-stackone#targeting-a-specific-connector-profile) for the request format.
  </Step>

  <Step title="Prompt end users to reauthenticate">
    Send an email, in-app notification, or modal prompting users to reconnect through the Integration Hub. The connect flow uses the new session token, which routes to the new connector profile. You can identify which accounts still need migration by checking which remain associated with the old connector profile.
  </Step>

  <Step title="Accounts migrate on successful auth">
    When a user completes the new auth flow, their linked account moves to the new connector profile. Subsequent requests resolve against the new major version.
  </Step>
</Steps>

<Tip>
  The recommended migration pattern is a staging connector profile pinned to the new version. Test your integration against it before updating the production profile. Each connector profile pins independently, so there's no coupling between environments.
</Tip>

## Immutable versioning

Immutable versioning controls whether published versions can be overwritten. It is **enabled by default** and toggled from the **Danger Zone** tab in **Project Settings**.

<Frame>
  <img alt="Immutable Versioning toggle enabled in the Danger Zone tab of Project Settings" />
</Frame>

* **Enabled** (default) - Each version number is locked once published. Subsequent publishes must use a new version number. Use this to guarantee that linked accounts on a pinned version see exactly the connector that was originally published.
* **Disabled** - Republishing the same version number is allowed when pushing with the [CLI's](/guides/connector-engine/cli-reference) `--force` flag (`stackone push --force`). Without `--force`, the CLI still rejects overwrites. Linked accounts resolving to an overwritten version will pick up the new content on the next request.

<Note>
  When immutable versioning is enabled, the `--force` flag has no effect - overwrites are rejected regardless.
</Note>

<Tip>
  Enable immutable versioning in production projects to prevent accidental overwrites of a version that linked accounts depend on. Disable it in development projects where iterating on a version without bumping the number is convenient.
</Tip>


# Dashboard Navigation
Source: https://docs.stackone.com/guides/dashboard-navigation

Navigate the StackOne dashboard. Understand the sidebar, project switcher, user settings, and quick search.

This guide explains how to navigate the StackOne dashboard efficiently.

## Dashboard Overview

When you log into StackOne, you'll see the main dashboard with three key areas:

<Frame>
  <img alt="StackOne dashboard with sidebar showing Overview, Configuration, and Support sections" />
</Frame>

***

## Sidebar Navigation

The left sidebar is organized into sections:

### Overview

| Menu Item     | Description                                                          |
| ------------- | -------------------------------------------------------------------- |
| **Dashboard** | API request metrics, linked accounts overview, and integration stats |
| **Accounts**  | Manage all linked customer accounts and their connection status      |
| **Logs**      | View request logs for debugging and monitoring API calls             |

### Configuration

| Menu Item              | Description                                                        |
| ---------------------- | ------------------------------------------------------------------ |
| **Field Mapping**      | Customize how data fields map between StackOne and providers       |
| **Connectors**         | Browse and configure available actions for each connector          |
| **Connector Profiles** | Set up authentication configurations (OAuth credentials, settings) |
| **API Keys**           | Create and manage API keys for your project                        |
| **Webhooks**           | Configure webhook endpoints for real-time event notifications      |
| **Playground**         | Test actions using natural language with AI                        |
| **Project Settings**   | Configure project-level settings and preferences                   |

### Support

| Menu Item          | Description                                        |
| ------------------ | -------------------------------------------------- |
| **Field Coverage** | Check which fields are supported for each provider |
| **Documentation**  | Quick link to these docs                           |

***

## Project Switcher

At the top of the sidebar, click on your project name to:

* **Switch projects**: Select a different project from your organization
* **View project details**: See the current project's region (EU1, US1, etc.)

<Tip>
  Use separate projects for development, staging, and production environments.
</Tip>

***

## User Profile & Organization

Click on your name at the bottom of the sidebar to access:

<Frame>
  <img alt="User profile dropdown showing Account, Manage Team, Security, and Sign Out options" />
</Frame>

### Account Settings

| Option          | Description                                        |
| --------------- | -------------------------------------------------- |
| **Account**     | Manage your personal account settings and security |
| **Manage Team** | Invite team members and manage roles (Admin only)  |
| **Security**    | Configure organization security settings like SSO  |
| **Sign Out**    | Log out of your StackOne session                   |

***

## Quick Search (CMD+K)

Press `Cmd+K` (Mac) or `Ctrl+K` (Windows/Linux) to open the command palette for quick navigation.

### What You Can Do

* **Search pages**: Type to filter and jump to any dashboard section
* **Switch projects**: Quickly change between projects
* **Access quick links**: Jump to frequently used pages

<Frame>
  <img alt="Command palette showing search input and quick links" />
</Frame>

<Tip>
  The command palette is the fastest way to navigate if you know where you want to go. Just start typing!
</Tip>

***

## Next Steps

<CardGroup>
  <Card title="Link Your First Account" icon="link" href="/guides/accounts-section">
    Connect a provider to start testing
  </Card>

  <Card title="Test in Playground" icon="play" href="/guides/playground">
    Try actions with natural language
  </Card>
</CardGroup>


# Defender
Source: https://docs.stackone.com/guides/defender

Protect your AI agents from prompt injection attacks by scanning API tool call responses before they reach your LLM.

Defender protects your AI agents from prompt injection attacks by scanning API tool call responses before they reach your LLM. When an MCP tool returns data from a third-party provider — emails, CRM records, documents — that data could contain instructions designed to hijack your agent's behavior. Defender intercepts and classifies those responses, and can block high-risk content before it causes harm.

## How It Works

In the default **Both** detection mode, Defender runs a two-stage pipeline on tool call responses:

* **Tier 1 — Pattern matching**: Fast rule-based scan that checks for known prompt injection signatures and risky field patterns. Runs on every response with negligible latency.
* **Tier 2 — AI classification**: A local ML model (MiniLM) scores the content for novel or subtle attacks that pattern matching would miss. Runs in parallel with Tier 1 on every response, scanning the SFE-filtered payload (or the `tier2Fields` subset when configured).

You can configure Detection Mode to run only one stage, or skip scanning entirely for responses that exceed the configured size limits (see [Advanced Settings](#advanced-settings) below).

```mermaid theme={null}
flowchart TD
    A[Tool call response] --> B(Tier 1: Pattern scan + sanitize)
    B --> D(Tier 2: ML classification)
    B --> R{Combined risk level}
    D --> R
    R -->|Low / medium| C[Allowed — passed to agent]
    R -->|High + block enabled| E[Blocked — error returned to agent]
    R -->|High + block disabled| F[Allowed — flagged in metadata]
```

Risk level and scan metadata are returned alongside every response so you can observe what Defender is seeing, even when not blocking.

## Configuration

Navigate to your project in the StackOne dashboard, then open the **Defender** tab in project settings.

<Frame>
  <img alt="Defender Settings" />
</Frame>

<Info>
  Defender settings apply project-wide. Per-account and per-request overrides take precedence where supported.
</Info>

### Core Settings

| Setting                     | Description                                                       | Default           |
| --------------------------- | ----------------------------------------------------------------- | ----------------- |
| **Status**                  | Master switch — enables scanning for this project                 | On (new projects) |
| **Block High Risk Content** | Automatically block responses classified as high or critical risk | Off               |

### Advanced Settings

<Frame>
  <img alt="Defender Advanced Settings — classification" />
</Frame>

<Frame>
  <img alt="Defender Advanced Settings — response handling" />
</Frame>

| Setting                      | Description                                                                                                                                                                                                                                                                                              | Default          |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| **Detection Mode**           | `Both` runs pattern + AI. `Pattern only` skips the ML model. `AI only` skips pattern matching. `Both` is recommended.                                                                                                                                                                                    | Both             |
| **High Risk Threshold**      | Score (0–1) above which content is classified as high risk                                                                                                                                                                                                                                               | 0.8              |
| **Medium Risk Threshold**    | Score (0–1) above which content is classified as medium risk                                                                                                                                                                                                                                             | 0.5              |
| **Large Response Behavior**  | What to do when a response exceeds the size limits: `Skip scanning` (default), `Block the response`, or `Scan anyway`                                                                                                                                                                                    | Skip scanning    |
| **Max Response Size**        | Byte threshold that triggers large response behavior                                                                                                                                                                                                                                                     | 1,048,576 (1 MB) |
| **Max Response Words**       | Word count threshold that triggers large response behavior                                                                                                                                                                                                                                               | 10,000           |
| **Annotate Tool Results**    | Wrap sanitized tool results with boundary tags such as `[UD-abc123]...[/UD-abc123]` (where the suffix is a random per-response ID) so downstream prompts can reason about data boundaries. Pair this with `generateBoundaryInstructions()` from `@stackone/defender` in your system prompt when enabled. | Off              |
| **Semantic Field Extractor** | Skip metadata and identifier fields (UUIDs, timestamps, URLs, etc.) before classification to reduce latency and false positives. Recommended.                                                                                                                                                            | On               |

## When to Use Defender

* You are building AI agents or MCP-based workflows that process third-party API responses
* Your integrations handle sensitive data such as emails, files, calendar events, or CRM records
* You want to observe risk signals on tool call responses without necessarily blocking them

## SDK Configuration

If you're using the Node.js SDK, you can configure Defender per-toolset directly from your code — override your project's dashboard setting, opt in with safe defaults, or forcibly disable for trusted internal flows. See [Tool Defense 101](/agents/typescript/tool-defense-101) for the SDK API.

## FAQ

<AccordionGroup>
  <Accordion title="Do I need to enable Defender?">
    No. It is off by default. Enable it when your agents consume third-party data and you want protection against prompt injection.
  </Accordion>

  <Accordion title="Does Defender add latency?">
    Tier 1 (pattern matching) adds negligible latency. Tier 2 (AI classification) runs in parallel on every response — the ML model runs locally, so there is no external API call. The Semantic Field Extractor preprocessor trims metadata/identifier fields before Tier 2 to keep latency low; for typical responses the added latency is under 100ms.
  </Accordion>

  <Accordion title="What happens when a response is blocked?">
    The tool call returns an error to your agent indicating the response was blocked. The agent can handle this like any other tool error — retry, skip, or surface it to the user.
  </Accordion>

  <Accordion title="Can I see what Defender flagged without blocking?">
    Yes. Leave **Block High Risk Content** disabled. Defender still scans and returns `riskLevel`, `tier2Score`, and `detections` in the response metadata, which you can inspect in your logs.
  </Accordion>

  <Accordion title="Will my data be used to train the AI model?">
    No. The classification model runs locally within StackOne's infrastructure and is never trained on your data.
  </Accordion>
</AccordionGroup>


# StackOne Hub UI
Source: https://docs.stackone.com/guides/embedding-stackone-hub

Embed the StackOne Hub in your application to let end-users authenticate and connect their accounts

The StackOne Hub lets end-users authenticate and configure [connectors enabled](/guides/managing-integrations) in your StackOne projects.

<div>
  <Frame>
    <img alt="StackOne Hub - Connector Selection" />
  </Frame>

  <Frame>
    <img alt="StackOne Hub - Credential Entry" />
  </Frame>
</div>

***

## Choosing a Hub Version

StackOne offers two Hub versions. We recommend the **Hub** for new projects. The **Legacy Hub** remains available for existing implementations.

|                        | Hub                            | Legacy Hub                           |
| ---------------------- | ------------------------------ | ------------------------------------ |
| **Package**            | `@stackone/hub`                | `@stackone/react-hub` / `connect.js` |
| **Architecture**       | Native React component         | Iframe-based (loads external script) |
| **React Support**      | Yes                            | Yes                                  |
| **Non-React Support**  | Not yet                        | Yes (`connect.js`)                   |
| **Filtering & Search** | Yes                            | No                                   |
| **Error Messages**     | Detailed with resolution steps | Basic                                |
| **Theming**            | Full theming via design system | Limited styling options              |
| **Performance**        | Fast (direct API calls)        | Average (iframe network hops)        |
| **Status**             | Recommended                    | Legacy                               |

### Why the Hub?

The Hub is a ground-up rebuild with a fundamentally different architecture:

* **Native React Component**: The Hub renders directly in your React tree. The Legacy Hub loads an external script (`connect.js`) that injects an iframe. This means the Hub shares your app's React context, supports proper component composition, and eliminates iframe-related overhead.

* **Direct API Communication**: The Hub makes API calls directly from your app. The Legacy Hub routes requests through an iframe hosted on StackOne's domain, adding latency from cross-origin communication and extra network hops.

* **Full Theming Support**: The Hub uses our Malachite design system, giving you complete control over colors, typography, and styling. You can match your app's design without CSS hacks or iframe styling limitations.

* **Better Event Handling**: The Hub uses native React callbacks. The Legacy Hub relies on `postMessage` to communicate events across the iframe boundary, which can be less reliable and harder to debug.

***

## Quick Start

<Tabs>
  <Tab title="Hub - React">
    The Hub (`@stackone/hub`) offers filtering, search, detailed error messages, and full theming support.

    <Steps>
      <Step title="Install the package">
        <CodeGroup>
          ```bash npm theme={null}
          npm install @stackone/hub
          ```

          ```bash yarn theme={null}
          yarn add @stackone/hub
          ```

          ```bash pnpm theme={null}
          pnpm add @stackone/hub
          ```
        </CodeGroup>
      </Step>

      <Step title="Get a session token from your backend">
        The Hub needs a connect session token to securely communicate with StackOne. This token must be generated server-side to keep your API key secure.

        ```typescript theme={null}
        async function retrieveConnectSessionToken() {
          const response = await fetch('/api/stackone/connect-session', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ username: 'jane@example.com' }),
          });
          const { token } = await response.json();
          return token;
        }
        ```

        See [Connect your Backend with StackOne](/platform/connect-your-backend-with-stackone) for backend implementation.
      </Step>

      <Step title="Add the component">
        ```tsx theme={null}
        import { StackOneHub } from "@stackone/hub";
        import { useEffect, useState } from "react";

        function ConnectorPage() {
          const [token, setToken] = useState<string>();

          useEffect(() => {
            retrieveConnectSessionToken().then(setToken);
          }, []);

          if (!token) return <div>Loading...</div>;

          return (
            <StackOneHub
              token={token}
              onSuccess={(account) => {
                console.log('Connected:', account.id, account.provider);
              }}
              onCancel={() => console.log('Cancelled')}
              onClose={() => console.log('Closed')}
            />
          );
        }
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Legacy Hub - React">
    <Note>
      The Legacy Hub. For new projects, use the **Hub** above.
    </Note>

    The Legacy Hub (`@stackone/react-hub`) provides a hook-based API.

    <Steps>
      <Step title="Install the package">
        <CodeGroup>
          ```bash npm theme={null}
          npm install @stackone/react-hub
          ```

          ```bash yarn theme={null}
          yarn add @stackone/react-hub
          ```

          ```bash pnpm theme={null}
          pnpm add @stackone/react-hub
          ```
        </CodeGroup>
      </Step>

      <Step title="Create a function to retrieve the session token">
        The Hub needs a connect session token to securely communicate with StackOne. This token must be generated server-side to keep your API key secure.

        ```typescript theme={null}
        export const retrieveConnectSessionToken = async ({ username, provider }) => {
          const response = await fetch('/api/stackone/connect-session', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
              originUsername: username,
              provider, // optional - skip connector listing
            }),
          });

          const { token } = await response.json();
          return { token };
        };
        ```

        See [Connect your Backend with StackOne](/platform/connect-your-backend-with-stackone) for backend implementation.
      </Step>

      <Step title="Create a Link Account Button">
        ```tsx theme={null}
        import { useCallback } from 'react';
        import { useStackOneHub } from '@stackone/react-hub';

        const LinkAccountButton = () => {
          const { startConnect } = useStackOneHub();

          const startFlow = useCallback(async () => {
            const { token } = await retrieveConnectSessionToken({
              username: 'jane@example.com'
            });
            startConnect({
              sessionToken: token,
              onSuccess: (account) => {
                console.log('Account linked:', account);
              },
              onCancel: () => console.log('Cancelled'),
              onClose: () => console.log('Closed'),
            });
          }, [startConnect]);

          return <button onClick={startFlow}>Connect Account</button>;
        };
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Legacy Hub - Vanilla JS">
    <Note>
      The Legacy Hub. The Hub doesn't yet support vanilla JS. For non-React apps, use `connect.js` below or generate [Auth Links](/guides/auth-link) from the dashboard.
    </Note>

    The Legacy Hub provides `connect.js`, a standalone JavaScript library for non-React applications.

    <Steps>
      <Step title="Install the connect script">
        <CodeGroup>
          ```html HTML Script Tag theme={null}
          <script src="https://app.stackone.com/stackone/connect.js"></script>
          ```

          ```javascript Dynamic JavaScript theme={null}
          const script = document.createElement('script');
          script.src = 'https://app.stackone.com/stackone/connect.js';
          script.onload = () => {
            // Connect is now available globally
            console.log('Connect.js loaded');
          };
          document.body.appendChild(script);
          ```
        </CodeGroup>
      </Step>

      <Step title="Create a function to retrieve the session token">
        ```javascript theme={null}
        async function retrieveConnectSessionToken() {
          const response = await fetch('/api/stackone/connect-session', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ username: 'jane@example.com' }),
          });
          return response.json();
        }
        ```

        See [Connect your Backend with StackOne](/platform/connect-your-backend-with-stackone) for backend implementation.
      </Step>

      <Step title="Start the connect flow">
        ```javascript theme={null}
        const { token } = await retrieveConnectSessionToken();

        Connect.start({
          sessionToken: token,
          onSuccess: (account) => {
            console.log('Account linked:', account);
          },
          onCancel: () => {
            console.log('User cancelled');
          },
          onClose: () => {
            console.log('Hub closed');
          },
        });
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

## API Reference

<Tabs>
  <Tab title="Hub - @stackone/hub">
    The `StackOneHub` component accepts these props:

    | Prop              | Type                                                  | Default                      | Description                                             |
    | ----------------- | ----------------------------------------------------- | ---------------------------- | ------------------------------------------------------- |
    | `token`           | `string`                                              | —                            | Connect session token from your backend                 |
    | `mode`            | `'integration-picker'`                                | `'integration-picker'`       | Hub mode                                                |
    | `accountId`       | `string`                                              | —                            | Pre-select a specific account to edit                   |
    | `baseUrl`         | `string`                                              | `'https://api.stackone.com'` | StackOne API base URL                                   |
    | `appUrl`          | `string`                                              | `'https://app.stackone.com'` | StackOne App URL                                        |
    | `height`          | `string`                                              | `'500px'`                    | Component height                                        |
    | `theme`           | `'light' \| 'dark' \| PartialMalachiteTheme`          | `'light'`                    | Theme configuration                                     |
    | `showFooterLinks` | `boolean`                                             | `true`                       | Show footer links                                       |
    | `onSuccess`       | `(account: { id: string; provider: string }) => void` | —                            | Called when account is connected                        |
    | `onCancel`        | `() => void`                                          | —                            | Called when user cancels                                |
    | `onClose`         | `() => void`                                          | —                            | Called when hub closes                                  |
    | `onCloseLabel`    | `string`                                              | `'Close'`                    | Custom label for the close button on the success screen |

    ```tsx theme={null}
    import { StackOneHub } from "@stackone/hub";

    <StackOneHub
      token={sessionToken}
      mode="integration-picker"
      height="600px"
      theme="dark"
      showFooterLinks={false}
      onSuccess={(account) => {
        console.log(`Connected ${account.provider} with ID ${account.id}`);
      }}
      onCancel={() => console.log('User cancelled')}
      onClose={() => console.log('Hub closed')}
      onCloseLabel="Done"
    />
    ```
  </Tab>

  <Tab title="Legacy Hub - @stackone/react-hub">
    The `useStackOneHub` hook returns a `startConnect` function:

    ```typescript theme={null}
    const { startConnect } = useStackOneHub({ connectUrl?: string });
    ```

    **StartOptions**

    | Option         | Type                         | Required | Description                             |
    | -------------- | ---------------------------- | -------- | --------------------------------------- |
    | `sessionToken` | `string`                     | Yes      | Connect session token from your backend |
    | `apiUrl`       | `string`                     | No       | Custom API URL                          |
    | `styles`       | `HubStyles`                  | No       | Style customization                     |
    | `onSuccess`    | `(account: Account) => void` | No       | Called when account is connected        |
    | `onCancel`     | `() => void`                 | No       | Called when user cancels                |
    | `onClose`      | `() => void`                 | No       | Called when hub closes                  |

    ```tsx theme={null}
    import { useStackOneHub } from '@stackone/react-hub';

    const { startConnect } = useStackOneHub();

    startConnect({
      sessionToken: token,
      onSuccess: (account) => {
        console.log('Connected account:', account.id);
      },
      onCancel: () => console.log('Cancelled'),
      onClose: () => console.log('Closed'),
    });
    ```
  </Tab>

  <Tab title="Legacy Hub - connect.js">
    After loading the script, use the global `Connect` object:

    ```javascript theme={null}
    Connect.start({
      sessionToken: string,     // Required - from your backend
      apiUrl?: string,          // Optional - custom API URL
      styles?: HubStyles,       // Optional - style customization
      onSuccess?: (account) => void,
      onCancel?: () => void,
      onClose?: () => void,
    });
    ```

    Full example:

    ```javascript theme={null}
    Connect.start({
      sessionToken: token,
      styles: {
        inline: { containerId: 'hub-container', width: '100%', height: '600px' },
        options: { back: true, close: true, bgColor: '#f5f5f5' },
      },
      onSuccess: (account) => {
        console.log('Account linked:', account);
        // account has: id, provider, status, etc.
      },
      onCancel: () => {
        console.log('User cancelled the flow');
      },
      onClose: () => {
        console.log('Hub modal was closed');
      },
    });
    ```
  </Tab>
</Tabs>

***

## Style Customization

<Tabs>
  <Tab title="Hub">
    The Hub supports full theming with the `theme` prop:

    ```tsx theme={null}
    <StackOneHub
      token={token}
      theme="dark"  // or "light"
    />
    ```

    For custom theming, pass a `PartialMalachiteTheme` object:

    ```tsx theme={null}
    <StackOneHub
      token={token}
      theme={{
        colors: {
          primary: {
            background: '#6366f1',
            foreground: '#ffffff',
          },
          card: {
            background: '#fafafa',
          },
        },
      }}
    />
    ```

    See the [@stackone/hub repository](https://github.com/StackOneHQ/hub) for full theme options.
  </Tab>

  <Tab title="Legacy Hub">
    The Legacy Hub uses a `styles` object with two sections:

    ### HubStyles Interface

    ```typescript theme={null}
    interface HubStyles {
      inline?: {
        containerId: string;  // Required - DOM element ID to embed the hub
        width?: string;       // e.g., '400px', '100%'
        height?: string;      // e.g., '500px', '100%'
      };
      options?: {
        back?: boolean;       // Show/hide back arrow (default: true)
        close?: boolean;      // Show/hide close button (default: true)
        bgColor?: string;     // Background color (e.g., 'white', '#f0f0f0')
      };
    }
    ```

    ### Default (Modal) vs Inline

    **Default (Modal)** - Hub opens in a centered modal overlay:

    ```javascript theme={null}
    startConnect({ sessionToken: token });
    ```

    <Frame>
      <img alt="Default modal style" />
    </Frame>

    **Inline** - Hub embeds in a specific container:

    ```javascript theme={null}
    startConnect({
      sessionToken: token,
      styles: {
        inline: {
          containerId: 'my-hub-container',
          width: '400px',
          height: '600px',
        },
        options: {
          back: false,
          close: false,
          bgColor: 'transparent',
        },
      },
    });
    ```

    <Frame>
      <img alt="Inline embedded style" />
    </Frame>
  </Tab>
</Tabs>

***

## Hub Behavior Customization

Control which connectors appear in the Hub by configuring the connect session on your backend.

### Filtering Connectors

You can specify a `provider` or `categories` property when creating the connect session to control which connectors appear in the Hub:

* **`provider`**: Opens the Hub directly at the credential entry screen for a specific connector, bypassing the connector listing
* **`categories`**: Filters the Hub to show only connectors from specified categories (e.g., `hris`, `ats`)

If neither is specified, the Hub displays all connectors enabled for the project.

<Warning>
  The connector specified in `provider` must be enabled in the [Connector Profiles page](https://app.stackone.com/connector_profiles) of the associated project.
</Warning>

Find valid `provider` keys in the [Supported Connectors](https://app.stackone.com/field_coverage) list under the `Provider Key` column.

### Backend Examples

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Skip connector list, go directly to BambooHR
  const result = await stackOne.connectSessions.createConnectSession({
    originOwnerId: "customer-123",
    originOwnerName: "Acme Inc",
    provider: "bamboohr",  // Go directly to this connector
  });
  ```

  ```javascript JavaScript (Categories) theme={null}
  // Show only HRIS connectors
  const result = await stackOne.connectSessions.createConnectSession({
    originOwnerId: "customer-123",
    originOwnerName: "Acme Inc",
    categories: ["hris"],  // Filter to HRIS category
  });
  ```
</CodeGroup>

***

## Event Callbacks

All Hub versions support these callbacks:

| Callback    | When it fires                                                                            |
| ----------- | ---------------------------------------------------------------------------------------- |
| `onSuccess` | User successfully connects an account. Receives account object with `id` and `provider`. |
| `onCancel`  | User explicitly cancels the flow (clicks cancel/back).                                   |
| `onClose`   | Hub closes for any reason (success, cancel, or clicking outside modal).                  |

<Tip>
  Use `onSuccess` to update your UI or trigger backend syncs. Use `onClose` as a cleanup handler that always runs.
</Tip>

```typescript theme={null}
startConnect({
  sessionToken: token,
  onSuccess: (account) => {
    // Refresh your linked accounts
    fetchLinkedAccounts();
    showNotification(`Connected to ${account.provider}`);
  },
  onCancel: () => {
    // User backed out - maybe show a prompt
    console.log('Connection cancelled');
  },
  onClose: () => {
    // Always runs - cleanup
    setIsConnecting(false);
  },
});
```

***

## Dashboard Access

You can also use the Hub directly from the StackOne dashboard without embedding:

### Connection Links

Generate connection links from your dashboard to share with end-users.

<div>
  <Frame>
    <video />
  </Frame>
</div>

### Direct Account Linking

Link accounts directly from the dashboard interface.

<div>
  <Frame>
    <video />
  </Frame>
</div>

***

## Backend Setup

Both hub versions require a connect session token generated from your backend. This keeps your API key secure.

<CardGroup>
  <Card title="Backend Implementation" icon="server" href="/platform/connect-your-backend-with-stackone">
    Generate session tokens securely from your backend
  </Card>

  <Card title="API Reference" icon="code" href="/platform/api-reference/connect-sessions/">
    Connect Sessions endpoint documentation
  </Card>
</CardGroup>


# Connectors
Source: https://docs.stackone.com/guides/explore-connectors

Browse and discover all available StackOne connectors and their actions

## Overview

The **Connectors** page ([app.stackone.com/connectors](https://app.stackone.com/connectors)) shows all available connectors and their actions. Use it to find actions, check parameters, and test them in the Playground.

<CardGroup>
  <Card title="Browse All Actions" icon="grid">
    View the complete catalog of actions across all connectors
  </Card>

  <Card title="Filter & Search" icon="magnifying-glass">
    Find specific actions by category, provider, or keyword
  </Card>

  <Card title="View Details" icon="list">
    See action parameters, inputs, outputs, and descriptions
  </Card>

  <Card title="Test Instantly" icon="play">
    Jump to the AI Playground to test any action with real data
  </Card>
</CardGroup>

## Accessing the Connectors Page

1. Navigate to [app.stackone.com/connectors](https://app.stackone.com/connectors)
2. Sign in to your StackOne account
3. Browse connectors and click on any to view its available actions

<Frame>
  <img alt="Connectors page showing integrations like Greenhouse, Ashby, HiBob, and their supported authentication methods" />
</Frame>

<Tip>
  **Quick access:** You can also access the Connectors page from the sidebar navigation in the StackOne dashboard.
</Tip>

## Understanding Actions

Actions are the building blocks of StackOne connectors. Each action represents a specific operation you can perform with a provider, such as:

* **List operations** - Retrieve collections of records (e.g., list employees, list contacts)
* **Get operations** - Fetch a single record by ID
* **Create operations** - Add new records to a system
* **Update operations** - Modify existing records
* **Delete operations** - Remove records

### Action Types

<AccordionGroup>
  <Accordion title="Provider-Specific Actions" icon="puzzle-piece">
    Direct access to provider APIs. These actions expose the full capabilities of each integration.

    **Examples:**

    * `gong_crm_search_calls` - Search CRM calls in Gong
    * `ashby_list_applications` - List applications from Ashby ATS
    * `workday_list_employees` - List employees from Workday HRIS
    * `salesforce_list_accounts` - List accounts from Salesforce CRM
  </Accordion>

  <Accordion title="Unified Actions" icon="code-branch">
    Standardized actions that work consistently across all providers in a category. Use these when you want your agent or application to work with any provider without provider-specific code.

    **Examples:**

    * `iam_list_users` - List users from Okta, Azure AD, Google Workspace, or any IAM provider
    * `iam_list_groups` - List groups across identity providers
    * `documents_list_files` - List files from Google Drive, SharePoint, Dropbox, or any document provider
    * `documents_download_file` - Download files with a consistent interface

    Unified actions normalize data schemas across providers, so your code works identically regardless of which system your user connects.

    <Tip>
      Want to build unified actions for your own connectors? See the [Connector Engine](/guides/connector-engine/introduction) to create custom connectors with unified schemas.
    </Tip>
  </Accordion>
</AccordionGroup>

## Using the Actions Explorer

### Browsing Connectors

The main page displays all available connectors in a list. Each row shows:

* **Connector name** with icon and action count
* **Supported authentication types** (OAuth, API Key, Basic, etc.)
* **Quick actions** - Play button to test in Playground

Click on any connector row to open the details panel.

### Exploring Connector Actions

After selecting a connector, a side panel opens with:

* **Search bar** - Filter actions by name or keyword
* **Tags filter** - Filter by action type or category
* **Connector Profiles filter** - Filter by authentication type
* **Use in Playground** - Launch the connector directly in the AI Playground
* **MCP setup info** - Ready-to-use MCP server URL and headers
* **AI Toolset docs** - Link to SDK documentation

The actions table lists all available operations for the connector with their names and descriptions.

<Tip>
  Use the **Active Actions Only** toggle to show only actions that are currently enabled for your account.
</Tip>

## From Explorer to Execution

Once you've found an action you want to use, you have several options:

<CardGroup>
  <Card title="Test in AI Playground" icon="play" href="/guides/playground">
    Test the action interactively with natural language using LLMs
  </Card>

  <Card title="Use via MCP" icon={<svg fill="currentColor" fillRule="evenodd" height="1em" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><path d="M15.688 2.343a2.588 2.588 0 00-3.61 0l-9.626 9.44a.863.863 0 01-1.203 0 .823.823 0 010-1.18l9.626-9.44a4.313 4.313 0 016.016 0 4.116 4.116 0 011.204 3.54 4.3 4.3 0 013.609 1.18l.05.05a4.115 4.115 0 010 5.9l-8.706 8.537a.274.274 0 000 .393l1.788 1.754a.823.823 0 010 1.18.863.863 0 01-1.203 0l-1.788-1.753a1.92 1.92 0 010-2.754l8.706-8.538a2.47 2.47 0 000-3.54l-.05-.049a2.588 2.588 0 00-3.607-.003l-7.172 7.034-.002.002-.098.097a.863.863 0 01-1.204 0 .823.823 0 010-1.18l7.273-7.133a2.47 2.47 0 00-.003-3.537z"></path><path d="M14.485 4.703a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a4.115 4.115 0 000 5.9 4.314 4.314 0 006.016 0l7.12-6.982a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a2.588 2.588 0 01-3.61 0 2.47 2.47 0 010-3.54l7.12-6.982z"></path></svg>} href="/mcp/quickstart">
    Access the action through StackOne's MCP server
  </Card>

  <Card title="Call via SDK" icon="code" href="/agents/typescript/introduction">
    Use the AI Toolset SDKs to call the action programmatically
  </Card>

  <Card title="Direct API Call" icon="bolt" href="/platform/api-reference/actions/make-an-rpc-call-to-an-action">
    Execute the action directly via the Actions RPC API
  </Card>
</CardGroup>

### Example: Using an Action

After finding an action like `workday_list_employees`, here's how you'd use it:

<Tabs>
  <Tab title="AI Playground">
    1. Go to [app.stackone.com/playground](https://app.stackone.com/playground)
    2. Select your Workday account
    3. Ask: "List all employees from Workday"
    4. The AI will automatically use the `workday_list_employees` action
  </Tab>

  <Tab title="MCP">
    ```json theme={null}
    // The action is automatically available as a tool
    // in any MCP-compatible client
    {
      "tool": "workday_list_employees",
      "arguments": {
        "limit": 100
      }
    }
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```typescript theme={null}
    import { StackOneToolSet } from "@stackone/stackone-client-ts";

    const toolset = new StackOneToolSet();
    const tools = await toolset.fetchTools({
      accountIds: ["workday-account-id"],
      actions: ["workday_list_employees"]
    });

    // Use with your AI framework
    const result = await tools[0].execute({ limit: 100 });
    ```
  </Tab>

  <Tab title="Actions API">
    ```bash theme={null}
    curl -X POST "https://api.stackone.com/actions/rpc" \
      -u "$STACKONE_API_KEY:" \
      -H "x-account-id: YOUR_ACCOUNT_ID" \
      -H "Content-Type: application/json" \
      -d '{
        "action": "workday_list_employees",
        "query": { "page_size": 100 }
      }'
    ```
  </Tab>
</Tabs>

## Best Practices

<AccordionGroup>
  <Accordion title="Start with the Playground" icon="play">
    Before integrating actions into your application, test them in the [AI Playground](/guides/playground) to understand their behavior and outputs.
  </Accordion>

  <Accordion title="Check Action Parameters" icon="sliders">
    Review the required and optional parameters for each action. Some actions require specific inputs to function correctly.
  </Accordion>

  <Accordion title="Monitor Usage" icon="chart-line">
    Use [Request Logs](/guides/request-logs) to monitor action executions and troubleshoot issues.
  </Accordion>
</AccordionGroup>

## Related Resources

<CardGroup>
  <Card title="AI Playground" icon="play" href="/guides/playground">
    Test actions interactively with LLMs
  </Card>

  <Card title="MCP Quickstart" icon={<svg fill="currentColor" fillRule="evenodd" height="1em" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><path d="M15.688 2.343a2.588 2.588 0 00-3.61 0l-9.626 9.44a.863.863 0 01-1.203 0 .823.823 0 010-1.18l9.626-9.44a4.313 4.313 0 016.016 0 4.116 4.116 0 011.204 3.54 4.3 4.3 0 013.609 1.18l.05.05a4.115 4.115 0 010 5.9l-8.706 8.537a.274.274 0 000 .393l1.788 1.754a.823.823 0 010 1.18.863.863 0 01-1.203 0l-1.788-1.753a1.92 1.92 0 010-2.754l8.706-8.538a2.47 2.47 0 000-3.54l-.05-.049a2.588 2.588 0 00-3.607-.003l-7.172 7.034-.002.002-.098.097a.863.863 0 01-1.204 0 .823.823 0 010-1.18l7.273-7.133a2.47 2.47 0 00-.003-3.537z"></path><path d="M14.485 4.703a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a4.115 4.115 0 000 5.9 4.314 4.314 0 006.016 0l7.12-6.982a.823.823 0 000-1.18.863.863 0 00-1.204 0l-7.119 6.982a2.588 2.588 0 01-3.61 0 2.47 2.47 0 010-3.54l7.12-6.982z"></path></svg>} href="/mcp/quickstart">
    Connect via MCP protocol
  </Card>

  <Card title="Execute Actions" icon="bolt" href="/platform/api-reference/actions/make-an-rpc-call-to-an-action">
    Direct RPC execution guide
  </Card>
</CardGroup>


# Getting Started with StackOne
Source: https://docs.stackone.com/guides/introduction

Configure your first connector and connect it to your agent in 5 minutes

<img alt="Getting started steps: Configure Connector, Link Account, Connect Agent" />

<Note>
  On first login, you'll be prompted to create an organization and project. Once that's done, continue below to start using a connector.
</Note>

## Configure Connector and Link an Account

<Steps>
  <Step title="Create a Connector Profile">
    Before linking an account, you need to enable and configure a <a href="/guides/connector-profiles">**Connector Profile**</a>. This is used to set up authentication and the actions and/or events you are looking to use.

    1. In the [StackOne dashboard](https://app.stackone.com/) sidebar, open **Connectors**
    2. Search for a connector you are interested in using (e.g. Zendesk, Gmail, Salesforce) and select it. This will open the **Connector page**.
    3. Following the **Quick Setup**, click **Add Profile**. This will open a side panel to configure the profile.

    <Frame>
      <img alt="Connector page showing the Quick Setup section with an Add Profile button" />
    </Frame>
  </Step>

  <Step title="Configure the Connector Profile">
    1. Leave the **Version** at **Latest**.
    2. Leave the **Profile name** as the default value.
    3. If multiple options exist, choose the **Authentication type** you wish to use.

    <Note>
      Depending on the Connector, there may be additional fields to complete (e.g. Client ID, Client Secret, API Key etc.) and/or additional configuration on the provider system. Check the [Connector Guides](/connectors) and follow the relevant Connector Profile guide.
    </Note>

    4. For getting started, we recommend deselecting all **Actions** and manually selecting a few read actions to test.
    5. Click **Create Profile**. The Connector Profile is now ready to use.

    <Frame>
      <img alt="Connector Profile configuration side panel showing version, profile name, and authentication type" />
    </Frame>

    <Frame>
      <img alt="Action selection panel within the Connector Profile, showing per-action toggles" />
    </Frame>
  </Step>

  <Step title="Link an Account">
    There are <a href="/guides/connect-tools-overview">multiple methods for linking an account</a>. In this guide, we'll link one directly through the StackOne dashboard.

    1. Following the **Quick Setup**, click the now enabled **Link Account** button. This will open the **Link an Account** popup.
    2. Select **Method 2 - Authenticate Now**.

    <Frame>
      <img alt="Link an Account popup showing the three connection methods with Method 2 - Authenticate Now selected" />
    </Frame>

    3. On **Enter Origin Owner Details**, leave all as default values and click **Next**.
    4. On **Integration Hub Preferences**, confirm the Connector Profile you configured earlier is selected, then click **Next**.

    <Note>
      Depending on the Connector there may be additional fields to complete and/or additional configuration on the provider system. Click **Connection Guide** in the top right for more details if needed.
    </Note>

    5. Click **Connect**.
    6. You may need to complete authentication with the provider (e.g. via OAuth). In this case a new window will pop up prompting you to sign in as needed.

    Once authorization is complete, your **Account** will now be linked in StackOne.
  </Step>
</Steps>

## Use the Connector

With a linked account in place, you can now use this Connector in the Agent of your choice. We recommend connecting it to your preferred agent client via **MCP**. You can also call StackOne directly from a TypeScript or Python agent, or an A2A orchestrator. If you just want to sanity-check the connector first, the **Playground** lets you test it without wiring up an agent.

<Tabs>
  <Tab title="MCP">
    The dashboard generates a ready-to-use MCP server for your linked account.

    <Steps>
      <Step>
        Following the **Quick Setup**, click the now enabled **Use in Agent** button. This will open the **Use with Agent Client** side panel.
      </Step>

      <Step>
        Under **MCP Server** > **Select Account**, choose the account you configured above.
      </Step>

      <Step>
        (Optional) Set the MCP Server Expiry. Default is 1 year.
      </Step>

      <Step>
        Select the agent client you want to be able to use this Connector.

        <Note>
          Further instructions are provided for most major platforms, otherwise the **HTTPS MCP** option reveals the URL that can be used in other MCP-compatible clients that support Streamable HTTP.
        </Note>
      </Step>

      <Step>
        Once the agent client confirms the connection, try a prompt like `"What tools can I use?"` or `"List the latest 5 records"` to verify the Connector is working.
      </Step>
    </Steps>

    <Frame>
      <img alt="Use with Agent Client side panel showing MCP Server account selector, expiry, and agent client options" />
    </Frame>

    <Card title="MCP Quickstart →" icon="bolt" href="/mcp/quickstart">
      Client-specific setup for Claude, Cursor, n8n, Vercel AI, and more
    </Card>
  </Tab>

  <Tab title="TypeScript SDK">
    For OpenAI Agents SDK, Vercel AI SDK, or a custom TypeScript agent.

    <Steps>
      <Step title="Create a StackOne API key">
        In the dashboard sidebar, open **API Keys**, click **Create API Key**, give it a name (e.g. `local-dev`), and copy the key — it's only shown once.

        <Note>
          The <a href="/guides/api-keys">StackOne API key</a> authenticates your application against StackOne and is separate from any provider credentials in the <a href="/guides/connector-profiles">Connector Profile</a>.
        </Note>
      </Step>

      <Step title="Follow your framework's integration guide">
        <CardGroup>
          <Card title="OpenAI Agents SDK" icon="robot" href="/agents/typescript/frameworks/openai-integration" />

          <Card title="Vercel AI SDK" icon="bolt" href="/agents/typescript/frameworks/vercel-ai-sdk" />
        </CardGroup>

        Or start with [Installation](/agents/typescript/installation) and [Basic Usage](/agents/typescript/basic-usage) for a custom setup.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Python SDK">
    For LangChain, LangGraph, CrewAI, OpenAI Agents SDK, Pydantic AI, or a custom Python agent.

    <Steps>
      <Step title="Create a StackOne API key">
        In the dashboard sidebar, open **API Keys**, click **Create API Key**, give it a name (e.g. `local-dev`), and copy the key — it's only shown once.

        <Note>
          The <a href="/guides/api-keys">StackOne API key</a> authenticates your application against StackOne and is separate from any provider credentials in the <a href="/guides/connector-profiles">Connector Profile</a>.
        </Note>
      </Step>

      <Step title="Follow your framework's integration guide">
        <CardGroup>
          <Card title="LangChain" icon="link" href="/agents/python/frameworks/langchain-integration" />

          <Card title="LangGraph" icon="diagram-project" href="/agents/python/frameworks/langgraph-integration" />

          <Card title="CrewAI" icon="users" href="/agents/python/frameworks/crewai-integration" />

          <Card title="OpenAI Agents SDK" icon="robot" href="/agents/python/frameworks/openai-integration" />

          <Card title="Pydantic AI" icon="square-check" href="/agents/python/frameworks/pydantic-ai-integration" />
        </CardGroup>

        Or start with [Installation](/agents/python/installation) and [Basic Usage](/agents/python/basic-usage) for a custom setup.
      </Step>
    </Steps>
  </Tab>

  <Tab title="A2A">
    For Google ADK, AG2, BeeAI, or any other A2A-aware orchestrator over the <a href="/a2a/introduction">Agent-to-Agent protocol</a>.

    <Steps>
      <Step title="Create a StackOne API key">
        In the dashboard sidebar, open **API Keys**, click **Create API Key**, give it a name (e.g. `local-dev`), and copy the key — it's only shown once.

        <Note>
          The <a href="/guides/api-keys">StackOne API key</a> authenticates your application against StackOne and is separate from any provider credentials in the <a href="/guides/connector-profiles">Connector Profile</a>.
        </Note>
      </Step>

      <Step title="Follow your framework's integration guide">
        <CardGroup>
          <Card title="Google ADK" icon="google" href="/a2a/framework-guides/adk" />

          <Card title="AG2" icon="users" href="/a2a/framework-guides/ag2" />

          <Card title="BeeAI" icon="bee" href="/a2a/framework-guides/beeai" />

          <Card title="A2A JavaScript SDK" icon="js" href="/a2a/sdk-guides/javascript" />

          <Card title="A2A Python SDK" icon="python" href="/a2a/sdk-guides/python" />
        </CardGroup>

        Or see the [A2A Quickstart](/a2a/quickstart) for the agent card URL, message format, and headers.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Playground">
    The [AI Playground](/guides/playground) lets you test actions with natural language directly in the dashboard without having your own agent client.

    <Steps>
      <Step>
        In the dashboard sidebar, open **Playground**.
      </Step>

      <Step>
        1. In the **Configure** panel, click **Manage Action Sources**.
        2. Select the Account you previously linked.
        3. Click **Done**.
      </Step>

      <Step>
        Try a prompt like `"What tools can I use?"` or `"List the latest 5 records"`.
      </Step>
    </Steps>

    You should be able to see the tool calls and responses from the agent, and provide follow-up prompts.

    <Card title="Full Playground Guide →" icon="wand-magic-sparkles" href="/guides/playground">
      Available models, debugging tool calls, and Playground limits
    </Card>
  </Tab>
</Tabs>

<Card title="Compare Agent Protocols →" icon="scale-balanced" href="/guides/calling-stackone-actions">
  Side-by-side comparison of MCP, SDKs, and A2A with worked examples.
</Card>

***

## What's Next?

<CardGroup>
  <Card title="StackOne 101" icon="book" href="/">
    Understand projects, connectors, actions, and accounts
  </Card>

  <Card title="Linking Accounts" icon="window" href="/guides/connect-tools-overview">
    Let end-users connect their accounts
  </Card>

  <Card title="Manage Accounts" icon="users" href="/guides/accounts-section">
    Monitor linked accounts and connection health
  </Card>

  <Card title="Browse Connectors" icon="grid" href="/connectors/introduction">
    See all 200+ supported providers
  </Card>
</CardGroup>


# Managing Projects
Source: https://docs.stackone.com/guides/managing-projects

Understand StackOne projects: isolated workspaces for organizing API keys, connectors, and linked accounts by region or environment.

## What is a Project?

A StackOne Project is an isolated workspace that organizes your API keys, connectors, and linked accounts. Projects let you separate data and access based on your needs.

Common use cases:

* **Regional data isolation**: EU project for GDPR compliance, US project for North American customers
* **Environment separation**: dev, staging, and production projects
* **Team isolation**: temporary projects for individual engineers or QA testing

## Creating a Project

1. Click the project selector in the top-left of the sidebar
2. Select **Create New Project**

Or go directly to [app.stackone.com/project/new](https://app.stackone.com/project/new).

<Note>
  Only Organization Admins can create new projects
</Note>

<Frame>
  <img alt="Create new project" />
</Frame>

### Choosing a Region

The region determines where your data is stored and processed. This ensures data locality compliance for your customers.

| Area          | Region                           | Data Center        | Availability  |
| :------------ | :------------------------------- | :----------------- | :------------ |
| Europe        | 🇮🇪 Ireland (Dublin)            | AWS EU-WEST-1      | ✔️ Available  |
| Europe        | 🇬🇧 United Kingdom (London)     | AWS EU-WEST-2      | ➕ Add-on      |
| North America | 🇺🇸 United States (N. Virginia) | AWS US-EAST-1      | ✔️ Available  |
| APAC          | 🇦🇺 Australia (Sydney)          | AWS AP-SOUTHEAST-2 | ⏳ Coming soon |

Need a custom region? Contact your StackOne account manager.

## Switching Projects

Click the project selector in the top-left to see all projects you have access to. The region code appears next to each project name (e.g., `EU1` or `US1`).

<Frame>
  <img alt="Project list" />
</Frame>

Organization Admins see all projects. Users with `basic` role only see projects they've been added to.

***

<Card title="Project Settings →" icon="gear" href="/guides/project-settings">
  Configure members, logs, IP restrictions, and AI features
</Card>


# Managing your Organization
Source: https://docs.stackone.com/guides/managing-your-organization

Learn how to manage your StackOne organization, including team member roles, security settings, MFA configuration, and access control across projects. Ideal for organization administrators managing users and security.

## Overview

StackOne allows adding multiple members inside your organization. You can invite all necessary users by specifying their email addresses and selecting the access role.

**Table of contents**:

1. [Manage team](#manage-team-members)
2. [Authentication & Security logs](#authentication--security-logs)
3. [Connection with Project Settings & Accounts](#connection-with-project-settings--accounts)

## Manage Team Members

If you have been assigned the "Org Admin" role, you will be able to manage the organization's team members. For role "Basic", the Team Members section is hidden.

With "Org Admin" role, you can:

* Add a new member, as well as resend or cancel a previously sent invitation (via the `invites` tab)
* Change a user's role
* Disable/Enable or Delete any other organization user
  * Unlock locked user accounts (eg. if the account has been locked for failed login attempts)
  * Reset another user's multi factor authentication
* Create and access any project
* View and update additional organization security settings

<Frame>
  <img alt="" />
</Frame>

## Authentication & Security Logs

As an admin user, you can access organization wide security settings by clicking on `security` upon clicking on your user.

The **Security** page allows you to enable OTP (One Time Password) MFA (Multi Factor Authentication) for all users currently inside the Organization and for any future users that will be added.

### Setting Up MFA

Once enabled, if you yourself haven't enabled MFA, you will be prompted to configure MFA for your own account. You can scan the QR code or enter the Authentication Secret manually using any authenticator app supporting Time-based One-Time Password (eg. Google Authenticator or Microsoft Authenticator, or password managers such as 1Password or Bitwarden).\
After successfully adding it your authenticator of choice, enter the Authenticator Code from the Auth app and click Confirm.

<Frame>
  <img alt="" />
</Frame>

<Warning>
  Important:

  All organization members that have not yet already enabled multi factor authentication will be required to do so the next time they log in the platform.
</Warning>

### Security Logs

The **[Security Logs](https://app.stackone.com/organization/security_logs)** tab shows a log of every log-in attempts (success or failures). This allows you to monitor users' login activity to identify potential authentication issues and help meet your compliance & audit requirements.

<Frame>
  <img alt="" />
</Frame>

## Connection with Project Settings & Accounts

Organization admins can also [Create Projects](/guides/managing-projects). For each project created, project admins can decide who from their organization can access that project.

For example, one user can have a `basic` organization role but be made `Project Admin` on any project within the organization, this means that the user will have admin level access to the project and will be able to manage the project's settings, accounts, and connectors.


# Dashboard Overview
Source: https://docs.stackone.com/guides/overview

Monitor API requests, track connector health, and view statistics for your linked accounts.

## Overview

The [Dashboard](https://app.stackone.com/) is the first page that loads for any project. It shows your project's activity at a glance, including requests made to StackOne's Unified API and webhooks. Use it to monitor the health and growth of your connectors.

Once you start using various [available StackOne connectors](https://www.stackone.com/integrations), the dashboard will populate the data respectively.

## Dashboard graph

You can configure multiple projects, and each will have its own dashboard statistics.

<Frame>
  <img alt="Dashboard Overview Page" />
</Frame>

By default, the API requests period is selected as 1 month from the current date. You can also select a custom range – last day, 7 days, 90 days, or any desirable date range from the calendar view.

<Frame>
  <img alt="" />
</Frame>

The graph table view shows the total number of API requests to StackOne's Unified API which also include the total number webhook requests.

* 🟢 Successful count, HTTP response code 200 or 201 (200s)

* 🔴 Failed count, any request which returned an error status code (400s or 500s)

You can review detailed information by hovering over individual bars in the chart. You can change the granularity of the data you're looking at via the relevant dropdown to view `hourly`, `weekly` or `monthly` data points.

<Frame>
  <img alt="" />
</Frame>

<Info>
  Additional Info

  The graph will count requests made to one of the supported unified API endpoint regardless of the source of the request as long as it was properly authenticated. This means requests made via [Postman requests](/guides/using-postman), the docs.stackone.com API Reference test UI, or any request made via the [request tester in the accounts page](https://app.stackone.com/accounts) will also be included within the graph.
</Info>

## Linked Accounts & Connectors

**Linked Accounts** shows the graph of active configured accounts in total. The graph and the delta number are for the last 7 days.

**Connectors** section beneath the main graph shows the list of all providers for which there is at least 1 linked account. Since you can enable or disable particular providers via the [Connector Profiles page](https://app.stackone.com/connector_profiles), the counter shows the **In-Use**/Enabled number.


# AI Playground
Source: https://docs.stackone.com/guides/playground

Test StackOne actions with natural language. No code required. Inspect Defender risk signals on tool calls.

The [AI Playground](https://app.stackone.com/playground) lets you test any action from your linked accounts using natural language.

<Frame>
  <img alt="Playground Main Interface" />
</Frame>

<Note>
  **Testing tool, not a production agent.** The Playground is designed for quickly testing actions and exploring capabilities. For production use cases, build your own agent using our [MCP Server](/mcp/quickstart), [AI Toolset](/agents/typescript/introduction), or [A2A Protocol](/a2a/quickstart). See [Agent Protocols Comparison](/guides/calling-stackone-actions) for guidance.
</Note>

<Info>
  **Access Required**: Contact StackOne support if you don't see the Playground in your dashboard.
</Info>

## Getting Started

<Steps>
  <Step title="Select accounts">
    Choose one or more linked accounts from the dropdown. Each account shows its provider and category.
  </Step>

  <Step title="Configure actions (optional)">
    Expand the **Actions** section to enable/disable specific actions before chatting.
  </Step>

  <Step title="Start chatting">
    Ask questions like *"List 5 employees"* or *"What tools can I use?"*
  </Step>
</Steps>

<Warning>
  Action selection is locked once you start a conversation. To change actions, start a new chat.
</Warning>

## Example Queries

The queries you can run depend on which accounts you've connected and what actions are available. Tailor your prompts to your agent's use case:

| Use Case                 | Example Query                                                          |
| ------------------------ | ---------------------------------------------------------------------- |
| **Explore capabilities** | "What tools can I use with these accounts?"                            |
| **List data**            | "Show me the first 10 employees"                                       |
| **Get specific records** | "Find employee with email [john@company.com](mailto:john@company.com)" |
| **Create records**       | "Create a new contact with name Jane Doe"                              |

<Tip>
  Start with "What tools can I use?" to see available actions for your selected accounts.
</Tip>

## Model Selection

Click the model selector at the bottom right to switch between models:

| Model                | Recommendation                                                                |
| -------------------- | ----------------------------------------------------------------------------- |
| **Anthropic Haiku**  | **Recommended.** Best balance of speed and tool calling accuracy for testing. |
| **Anthropic Sonnet** | Use for complex multi-step reasoning tasks.                                   |
| **GPT-4o**           | Alternative for comparison testing.                                           |

<Info>
  **StackOne Tool Calling Model (Beta)**

  StackOne is fine-tuning a specialized model optimized for SaaS tool calling, at lower cost than leading models.

  Contact [ai@stackone.com](mailto:ai@stackone.com) to join the beta.
</Info>

## Defender

The Playground includes a **StackOne Defender** toggle in the configuration sidebar that scans tool call responses for prompt injection attempts before the model sees them.

**Per-request override.** The Playground toggle is a per-request override — it controls Defender for the Playground session only, regardless of what the project-level setting is. Use it to test how your agent behaves with Defender on or off without changing your project configuration. The toggle defaults to **on** in the Playground.

**Risk indicators on tool calls.** When Defender is enabled, every tool call in the chat log displays a colored icon next to its status badge:

| Icon      | Meaning                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| <img />   | Low risk — response passed Defender's checks                                                                                          |
| <img />   | Medium risk — flagged but not blocked                                                                                                 |
| <img />   | High or critical risk — when **Block High Risk Content** is on in your project settings, this call is blocked from reaching the model |
| *no icon* | Defender did not scan this response (toggle off, size limit exceeded, or no defender metadata)                                        |

Hover any icon for the precise risk level reported by Defender.

**Behaviour when blocked.** With **Block High Risk Content** enabled at the project level, a high/critical tool call surfaces as a `Blocked` status in the chat log and the model receives an error in place of the tool response. The agent can react like any other tool error — retry, skip, or surface to the user.

For the full Defender configuration reference — detection modes, thresholds, large-response behaviour, SFE, and SDK overrides — see the [Defender guide](/guides/defender).

## Use Setup

The **"Use Setup"** button shows configuration for connecting StackOne's MCP server to your own applications:

<Frame>
  <img alt="Use Setup Dialog" />
</Frame>

* **URL**: `https://api.stackone.com/mcp`
* **Auth**: `Basic <base64-encoded-api-key>`
* **Header**: `x-account-id: <your-account-id>`

For full setup instructions, see the [MCP Quickstart](/mcp/quickstart). To understand which protocol is right for your use case, see [Agent Protocols Comparison](/guides/calling-stackone-actions).

## Troubleshooting

<AccordionGroup>
  <Accordion title="No accounts visible">
    Ensure accounts are linked in the [Accounts section](/guides/accounts-section) and actions are enabled in your [connector configuration](/guides/managing-integrations).
  </Accordion>

  <Accordion title="Slow responses">
    Switch to Haiku (fastest) or reduce the number of selected accounts.
  </Accordion>

  <Accordion title="Tool not found">
    Verify the action is enabled in your integration configuration. Check [Request Logs](/guides/request-logs) for details.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup>
  <Card title="Defender" icon="shield-halved" href="/guides/defender">
    Prompt-injection defense for tool call responses
  </Card>

  <Card title="Agent Protocols" icon="scale-balanced" href="/guides/calling-stackone-actions">
    Choose the right protocol for production
  </Card>

  <Card title="MCP Quickstart" icon="bolt" href="/mcp/quickstart">
    Connect MCP clients
  </Card>
</CardGroup>


# Project Settings
Source: https://docs.stackone.com/guides/project-settings

Configure project details, team members, logging, IP restrictions, AI features, Defender, and project deletion.

Access project settings by clicking **Project Settings** in the sidebar, or navigating to your project's settings page directly.

## Project Details

Update your project name anytime without affecting linked accounts or other settings. The region cannot be changed after creation.

<Frame>
  <img alt="Project details" />
</Frame>

## Team Members

Add, remove, or modify project-level roles for team members.

<Frame>
  <img alt="Project members" />
</Frame>

<Note>
  **Access Roles:**

  * **Viewer**: Can view Dashboard, Accounts, and Connector Profiles. Cannot access API keys or modify settings.
  * **Project Admin**: Full access to manage accounts, connectors, API keys, webhooks, and project settings.
</Note>

## Advanced Logs

Enable detailed request logging for debugging. Configure:

* **Retention period**: How long logs are stored before automatic deletion
* **Error-only mode**: Store only logs with HTTP status ≥ 400

<Frame>
  <img alt="Advanced logs settings" />
</Frame>

<Note>
  Changes to retention period only apply to new logs. Existing logs keep their original retention.
</Note>

## IP Restrictions

<Info>
  Available to enterprise customers only
</Info>

Restrict API access to specific IP addresses, ranges, or CIDR blocks:

* Single IP: `192.168.1.100`
* Range: `192.168.1.100-192.168.1.150`
* CIDR: `192.168.1.0/24`

If your network uses a NAT gateway, allow the gateway's external IP to permit all internal traffic.

<Frame>
  <img alt="IP restrictions" />
</Frame>

<Note>
  With no allowlist configured, all IPs are allowed. Once you add entries, only those IPs can access your project's API.
</Note>

## AI Settings

Control AI-powered features at the project level.

**Global Toggle**: Enable or disable all AI features for the project.

**Individual Features:**

* **[Error Explainer](/guides/ai-features#error-explainer)**: Provides context and resolution steps for error logs

<Frame>
  <img alt="AI settings" />
</Frame>

## Defender

Configure [Defender](/guides/defender) — StackOne's prompt-injection defense for tool call responses — at the project level.

**Status**: Enable or disable Defender scanning for this project. Enabled by default on new projects.

**Block High Risk Content**: When on, responses classified as high or critical risk are blocked from reaching your agent. Off by default — flagged content still surfaces in the response metadata so you can observe before enforcing.

**Advanced Settings**: Detection Mode (pattern, AI, or both), risk thresholds, large-response handling, boundary annotation, and the Semantic Field Extractor preprocessor. High Risk Threshold must be greater than or equal to Medium Risk Threshold.

<Frame>
  <img alt="Defender settings" />
</Frame>

See the [Defender guide](/guides/defender) for the full configuration reference, classification details, and SDK overrides.

## Danger Zone

The Danger Zone tab contains settings that affect connector publishing behaviour and project lifecycle.

<Frame>
  <img alt="Danger Zone settings with Immutable Versioning toggle and Delete Project action" />
</Frame>

### Immutable Versioning

Controls whether published connector versions can be overwritten. Enabled by default — each version number is locked once published, and subsequent pushes must use a new version number. When disabled, the CLI's `stackone push --force` flag can overwrite an existing version.

See [Connector Versioning](./connector-versioning#immutable-versioning) for the full behaviour and how this interacts with linked accounts pinned to a version.

### Deleting a Project

Delete a project from the settings page. There's a 7-day grace period before permanent deletion.

<Warning>
  Deleting a project removes everything inside it: linked accounts, API keys, webhooks, and all associated data. Contact StackOne support within 7 days if you need to reverse a deletion.
</Warning>


# Rate Limiting
Source: https://docs.stackone.com/guides/rate-limiting

Understand StackOne's rate limits (1000 requests/minute) and how caching optimizes API performance

## Understanding Rate Limiting

In the context of APIs, **rate limiting** controls how many requests a client can make to a service in a specified period of time. It's a way of ensuring that individual users or services don't monopolize resources by making excessive or unnecessary requests. Rate limiting is especially important for shared services or public APIs where multiple users may be accessing the same resources.

When a service reaches its rate limit, it will typically respond with a **429 Too Many Requests** HTTP status code, indicating that the client needs to wait before retrying their request.

## StackOne's Rate Limiting Policy

API keys are limited to **1000 requests per minute**. If you exceed this, you'll get a rate limit response.

<Info>The 1000 requests/minute limit may change in the future.</Info>

### What Happens When You Hit the Rate Limit?

When you hit the limit, you'll get a **429 Too Many Requests** response:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 60
```

The Retry-After header is included in the response when a rate limit is triggered. It provides guidance on how long the client should wait before making a subsequent request. The Retry-After value can be expressed either as a value in seconds or as a specific date/time. At StackOne we will return the value in seconds.

## Handling Rate Limiting in Your Application

To properly handle rate limiting, you need to read the 429 response code and the Retry-After header in your application, then implement backoff logic to pause and retry the request after the specified wait time.

### StackOne's Automatic Retry Mechanism

When you encounter rate limits from providers, StackOne automatically handles retries for you:

* **Automatic Retries**: When a provider returns a 429 response, StackOne automatically retries the request using the provider's `Retry-After` header
* **Retry Attempts**: Up to 5 consecutive retry attempts are made before returning the original 429 response
* **Request Timeout**: If retries exceed the 60-second request lifetime, a 408 Request Timeout is returned instead
* **Retry-After Headers**: Both 429 and 408 responses include appropriate `Retry-After` headers (either from the original provider response or a default 60 seconds)

This means you don't need to implement provider-specific retry logic in your application - StackOne handles this complexity for you while respecting provider rate limits.

### Best Practices for Rate Limiting

If you consistently hit the rate limit, consider optimizing your API usage, such as by caching responses or batching requests, to reduce the number of calls made.

## How StackOne Uses Caching to Optimize Requests

<Accordion title="Caching Infrastructure for Performance Optimization">
  <Info>
    StackOne uses intelligent caching to optimize performance and minimize rate limits while maintaining strict privacy standards and data freshness.
  </Info>

  ### 1. Ephemeral Memory Cache During Request Lifecycle

  During the processing of a single unified API request, StackOne uses ephemeral in-memory caching to avoid redundant calls to providers.

  <CardGroup>
    <Card title="Request-Scoped" icon="hourglass-half">
      Cache exists only for the duration of a single request
    </Card>

    <Card title="No Persistence" icon="ban">
      Data is immediately discarded after request completion
    </Card>

    <Card title="Automatic Cleanup" icon="broom">
      Memory is freed as soon as the request completes
    </Card>
  </CardGroup>

  #### Common Use Cases

  * **Ticketing Systems**: When listing tickets with associated agents, projects, and categories, we cache agent profiles and project metadata to avoid repeated lookups for each ticket
  * **Account Hierarchies**: Storing parent account information when processing related contacts, opportunities, or cases in CRM systems
  * **Category & Tag Mappings**: Caching taxonomy data (categories, tags, labels) when processing multiple content items, learning objects, or documents that share classifications
  * **Permission & Role Definitions**: Temporarily storing role-based access control data when evaluating permissions across multiple resources in a single request
  * **Currency & Locale Data**: Caching exchange rates and regional settings when processing financial data across multiple entities
  * **Field Definitions**: Caching custom field schemas and metadata when transforming records across different providers

  ```mermaid theme={null}
  sequenceDiagram
      participant Client as Your Application
      participant API as StackOne API
      participant Cache as Ephemeral Cache
      participant Provider as Integration Provider

      Note over Client,Provider: Single Request Lifecycle
      
      Client->>API: GET /unified/ats/applications
      API->>Cache: Check for job_123 details
      Cache->>API: Cache miss
      
      API->>Provider: Fetch job_123 details
      Provider->>API: Return job data
      API->>Cache: Store job_123 (TTL: request scope)
      
      loop Processing Applications
          API->>Cache: Get job_123 details
          Cache->>API: Return cached data
          Note over API,Cache: Reuse cached data
      end
      
      API->>Client: Return transformed applications
      Note over Cache: Cache cleared automatically
  ```

  ### 2. Redis Cache for Cross-Request Optimization

  For data that is frequently requested across multiple API calls, StackOne uses Redis with carefully managed TTLs.

  <Tabs>
    <Tab title="Short-lived Cache">
      <Note>
        **Typically \< 2 minutes** - This is the standard caching approach for most data
      </Note>

      **Purpose**: Optimize data access during active list operations or related requests

      **Examples**:

      * Pagination tokens for active dataset traversal
      * Data relationships during a listing operation
      * Temporary results while a user navigates through pages

      <Warning>
        If data potentially contains PII, it's cached only for the lifecycle of a listing operation (typically seconds to a couple of minutes maximum)
      </Warning>
    </Tab>

    <Tab title="Rare Extended Cache">
      <Warning>
        **Up to 30 minutes** - This is extremely rare and only used for guaranteed static, non-PII data
      </Warning>

      **Strict Requirements**:

      * Data must be guaranteed PII-free
      * Data must change very infrequently (e.g., system constants)
      * Clear business justification for extended caching

      **Limited Examples**:

      * Provider API capability flags (e.g., `"supports_custom_fields": true`)
      * System enumeration values (e.g., standard industry codes)
      * Static schema definitions that never contain user data

      <Info>
        The vast majority of data falls into the short-lived cache category. Extended caching is an exceptional case.
      </Info>
    </Tab>
  </Tabs>

  ### Benefits of StackOne's Caching Strategy

  <CardGroup>
    <Card title="Reduced Provider Load" icon="shield">
      Fewer requests to providers means less chance of hitting their rate limits
    </Card>

    <Card title="Improved Response Times" icon="rocket">
      Cached data returns instantly, improving your application's performance
    </Card>

    <Card title="Cost Optimization" icon="dollar-sign">
      Fewer API calls can reduce usage-based costs with some providers
    </Card>

    <Card title="Reliability" icon="check-circle">
      Cache serves as a buffer during temporary provider outages
    </Card>

    <Card title="Privacy-First" icon="lock">
      Intelligent data classification ensures PII is never cached
    </Card>
  </CardGroup>

  <Info>
    For more information about customizing caching behavior for your use case, contact StackOne support.
  </Info>
</Accordion>

For more information on handling rate limits or troubleshooting specific issues, contact StackOne support.


# Request Logs
Source: https://docs.stackone.com/guides/request-logs

Monitor and troubleshoot API requests with StackOne's request logs. View detailed information about API calls, filter by various parameters, and analyze both unified API requests and underlying provider interactions.

StackOne registers relevant information of requests made to the connected provider to fulfill any Unified API requests it receives. This can be useful for:

* Debugging issues with a particular account or integration
* Auditing the operations StackOne performs on your behalf

The [Request Logs](https://app.stackone.com/request_logs) page offers efficient find, filter, and analysis of API requests and HTTP status codes.

> ⏳ logs are only persisted up to 90 days after the original request occurred.

## Troubleshooting via Request Logs

When you execute an API query and want to investigate an API response, that's when the realization comes – logs review is inevitable.

The page shows all requests made to the StackOne <Tooltip>Unified API</Tooltip> and also allows you to see all requests that StackOne made to the [underlying providers](https://www.stackone.com/integrations) to fulfill the unified request. By default, it shows the logs in descending order per when the request occurred.

<Info>
  **AI-Powered Error Analysis**: When you encounter errors in request logs, use the [Error Explainer](/guides/ai-features#error-explainer) to get AI-generated resolution steps. The Error Explainer analyzes error logs and provides actionable troubleshooting steps based on StackOne and provider documentation.
</Info>

<iframe title="app.stackone.com/request_logs" />

The possible filtering options are:

| Filter              | Description                                                                                                                                                                                                                                                | Example values                                                   |
| :------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------- |
| Account             | The linked accounts' `origin_owner_name` for the current project. You can also see & search within that filter for a specific provider in case multiple accounts have been linked for the same `origin_owner_name`                                         | `Acme Inc.` `Sample Organization`                                |
| Provider            | The specific integration (aka [Provider](https://app.stackone.com/field_coverage)) associated with the request                                                                                                                                             | `Workday``Ashby``Salesforce`                                     |
| Resource            | The type of resource (and optionally sub resource requested and the action done on the resource.                                                                                                                                                           | `List Employees``Create Candidates Note``Get Applications Offer` |
| Source              | The source that originated the request - specifically the type of source allowing you to filter for requests made via the StackOne U.I. or an API key                                                                                                      | `API Request` `Dashboard UI` `Webhook`                           |
| Status              | The response's [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) - refer to additional documentation here regarding the meaning behind the [Unified API Error Codes](/guides/unified-api-error-codes-and-troubleshooting-guide) | `200` `201` `400` `404` `502`                                    |
| Method              | The HTTP method used to make the request                                                                                                                                                                                                                   | `post``get``patch`                                               |
| Start/End date time | A date and time window                                                                                                                                                                                                                                     | `Jan 01, 2023 01:01`                                             |

<Tip>
  New Features:

  1. You can now investigate each successful request in detail by clicking ➡️ for the respective request. This request is coming from StackOne directly to Provider's API.
  2. It's now possible to view the source of the request – Dashboard, Test Connection, or Other (Postman, API docs, etc).
  3. Since all filters are now grouped inside 1 search bar, you can easily remove multiple filters by clicking ❌ on the search bar's hover-over.
</Tip>

## Accessing the request logs page

After configuring Account integration and testing its connection, you can also access its specific request logs directly by clicking the `View Logs` option in the ellipsis menu.

<Frame>
  <img alt="Request logs interface" />
</Frame>

<br />

You will be redirected to the logs page with a filter pre-applied in the search bar

<Frame>
  <img alt="" />
</Frame>

## Viewing Log Details

When you click on a log entry, a detailed view opens up with two tabs:

1. **Details**: Shows the details of the unified API request made to StackOne, including request/response headers, body, query parameters, and status.

   > Note: Log storage duration can be configured in the [Advanced Logs](/guides/project-settings#advanced-logs) section of your Project Settings.

<Frame>
  <img alt="" />
</Frame>

2. **Underlying Requests**: Displays all API calls made to the provider's API to fulfill your unified request to enable better debugging.

<Frame>
  <img alt="" />
</Frame>

***

## Programmatic Access via API

You can also access request logs programmatically using the Request Logs API endpoints:

<CardGroup>
  <Card title="List Logs" icon="list" href="/platform/api-reference/request-logs/list-logs">
    **`GET /requests/logs`**: Retrieve a list of request logs with filtering options
  </Card>

  <Card title="Get Log" icon="file-lines" href="/platform/api-reference/request-logs/get-log">
    **`GET /requests/logs/{id}`**: Get detailed information about a specific log entry
  </Card>

  <Card title="List Step Logs" icon="layer-group" href="/platform/api-reference/request-logs/list-step-logs">
    **`GET /requests/logs/steps`**: Retrieve step-by-step logs for request processing
  </Card>

  <Card title="List Platform Logs" icon="server" href="/platform/api-reference/request-logs/list-platform-logs">
    **`GET /requests/platform-logs`**: Access platform-level logs and system events
  </Card>
</CardGroup>

These APIs allow you to integrate log data into your monitoring, alerting, or analytics systems.


# SSO Setup
Source: https://docs.stackone.com/guides/sso-setup

Configure SAML 2.0 Single Sign-On (SSO) for your StackOne organization, including setup with identity providers like Okta.

## Overview

StackOne supports SAML 2.0-based Single Sign-On (SSO), allowing your organization members to authenticate through your identity provider (IdP). Once configured and verified, users with matching email domains are automatically redirected to your IdP for authentication.

This guide covers:

1. [Configuring SSO in StackOne](#configure-sso-in-stackone)
2. [Setting up a SAML application in Okta](#set-up-a-saml-application-in-okta)
3. [Completing the SSO registration](#complete-the-sso-registration-in-stackone)
4. [Verifying your domain](#verify-your-domain)

## Prerequisites

* **Org Admin** role in your StackOne organization
* Access to your identity provider's admin dashboard (e.g., Okta)
* Ability to manage DNS records for your organization's domain

## Configure SSO in StackOne

Navigate to **Organization Settings > Security > SSO** to begin the setup process. StackOne walks you through a three-step configuration flow.

<Steps>
  <Step title="Copy the Service Provider details">
    The first step displays two values you'll need when configuring your identity provider:

    * **ACS URL (Assertion Consumer Service URL)** — the endpoint where your IdP sends SAML assertions
    * **SP Entity ID (Service Provider Entity ID)** — the metadata URL that identifies StackOne as the service provider

    Enter a **Provider ID** at the bottom of this step. This is a unique identifier for your SSO configuration (e.g., `your-company-sso`). It must be lowercase and can contain letters, numbers, hyphens, and dots.

    The ACS URL and SP Entity ID update automatically based on your Provider ID.

    <Frame>
      <img alt="SSO setup step 1 showing ACS URL and SP Entity ID fields" />
    </Frame>

    Copy both values — you'll paste them into your identity provider in the next section.
  </Step>

  <Step title="Configure your identity provider">
    After setting up the SAML application in your IdP (see [Okta example below](#set-up-a-saml-application-in-okta)), collect these three values from the IdP:

    * **Identity Provider Issuer (Entity ID)** — the IdP's unique identifier URL
    * **Identity Provider Single Sign-On URL** — the IdP's login endpoint
    * **X.509 Certificate** — the signing certificate in PEM format

    <Frame>
      <img alt="SSO setup step 2 showing fields to enter identity provider values" />
    </Frame>
  </Step>

  <Step title="Register the SSO provider">
    Fill in the registration form with the values collected from your IdP:

    | Field                     | Description                       | Example                                  |
    | ------------------------- | --------------------------------- | ---------------------------------------- |
    | **Provider ID**           | Unique identifier (set in step 1) | `acme-corp-sso`                          |
    | **Domain**                | Email domain for SSO users        | `acme.com`                               |
    | **Entity ID (Issuer)**    | IdP issuer URL from step 2        | `http://www.okta.com/exk...`             |
    | **SSO URL (Entry Point)** | IdP login URL from step 2         | `https://acme.okta.com/app/.../sso/saml` |
    | **X.509 Certificate**     | Signing certificate from step 2   | `-----BEGIN CERTIFICATE-----...`         |

    Click **Register SSO Provider** to save the configuration.

    <Frame>
      <img alt="SSO registration form with all fields filled in" />
    </Frame>
  </Step>
</Steps>

## Set Up a SAML Application in Okta

This section walks through creating a SAML 2.0 application in Okta. If you use a different identity provider, the general flow is similar — you'll need to provide the ACS URL and SP Entity ID from StackOne, then retrieve the IdP issuer, SSO URL, and certificate.

<Steps>
  <Step title="Create a new application">
    In your Okta admin dashboard, go to **Applications > Applications** and click **Create App Integration**.

    Select:

    * **Sign-in method**: SAML 2.0

    Click **Next**.

    <Frame>
      <img alt="Okta Create App Integration dialog with SAML 2.0 selected" />
    </Frame>
  </Step>

  <Step title="Configure general settings">
    Enter a name for the application (e.g., "StackOne SSO") and optionally upload a logo.

    Click **Next**.

    <Frame>
      <img alt="Okta general settings page for the SAML application" />
    </Frame>
  </Step>

  <Step title="Configure SAML settings">
    In the **SAML Settings** section, enter the values from StackOne's SSO setup (step 1):

    | Okta Field                      | Value from StackOne        |
    | ------------------------------- | -------------------------- |
    | **Single sign-on URL**          | ACS URL                    |
    | **Audience URI (SP Entity ID)** | SP Entity ID               |
    | **Default RelayState**          | `https://app.stackone.com` |
    | **Name ID format**              | EmailAddress               |
    | **Application username**        | Email                      |

    <Frame>
      <img alt="Okta SAML settings configured with StackOne ACS URL and Entity ID" />
    </Frame>

    Click **Next**, then **Finish**.
  </Step>

  <Step title="Copy the IdP values">
    After creating the application, go to the **Sign On** tab and on the right you will find the **SAML Setup** section. Click **View SAML setup instructions**.

    From here, copy:

    * **Identity Provider Single Sign-On URL**
    * **Identity Provider Issuer**
    * **X.509 Certificate**

    <Frame>
      <img alt="Okta Sign On tab showing IdP metadata and certificate" />
    </Frame>
  </Step>

  <Step title="Assign users">
    Go to the **Assignments** tab and assign the users or groups that should have access to StackOne via SSO.

    <Frame>
      <img alt="Okta Assignments tab for adding users to the SAML application" />
    </Frame>
  </Step>
</Steps>

## Complete the SSO Registration in StackOne

Return to the StackOne SSO setup page and paste the values from Okta into the Step 2 and Step 3 fields as described in [Configure SSO in StackOne](#configure-sso-in-stackone).

After clicking **Register SSO Provider**, you'll see a provider card with your SSO configuration details.

<Frame>
  <img alt="SSO provider card showing configuration details and verification status" />
</Frame>

## Verify Your Domain

Domain verification is required to activate SSO. This ensures your organization owns the email domain used for SSO authentication.

<Steps>
  <Step title="Copy the DNS TXT record">
    On the SSO provider card, find the **Domain Verification** section. It displays a DNS TXT record in this format:

    ```
    _stackone-sso-verification-token-{providerId}={verificationToken}
    ```

    Copy the full record value.

    <Frame>
      <img alt="Domain verification section showing the DNS TXT record to add" />
    </Frame>
  </Step>

  <Step title="Add the TXT record to your DNS">
    Go to your domain's DNS management panel (e.g., Cloudflare, Route 53, GoDaddy) and add a new TXT record with the value from the previous step.

    <Note>
      DNS propagation can take up to 48 hours, though it typically completes within minutes to a few hours.
    </Note>
  </Step>

  <Step title="Verify the domain in StackOne">
    Return to the StackOne SSO settings and click **Verify Domain**. If the DNS record has propagated, you'll see a success message confirming that SSO is active.

    If verification fails, wait for DNS propagation and try again.

    <Frame>
      <img alt="SSO provider card showing verified domain status" />
    </Frame>
  </Step>
</Steps>

## Managing Your SSO Configuration

Once SSO is configured, you can:

* **Edit SSO settings** — Update the domain, issuer, entry point, or certificate by clicking **Edit SSO** on the provider card
* **Delete SSO** — Remove the SSO configuration entirely by clicking **Delete SSO**

<Warning>
  Deleting your SSO configuration will require all organization members using SSO to sign in with email and password instead. Make sure affected users have alternative credentials before removing SSO.
</Warning>

## Troubleshooting

| Symptom                                     | Likely Cause                              | Fix                                                                |
| ------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------ |
| SSO tab not visible                         | Feature not enabled for your organization | Contact StackOne support to enable SSO                             |
| Domain verification fails                   | DNS record hasn't propagated              | Wait and retry — propagation can take up to 48 hours               |
| SAML login fails with "Invalid certificate" | Certificate mismatch                      | Re-copy the X.509 certificate from your IdP and update in StackOne |
| Users not redirected to IdP                 | Domain not verified                       | Complete the [domain verification](#verify-your-domain) step       |
| "403 Forbidden" error                       | User lacks Org Admin role                 | Ensure you have the Org Admin role to manage SSO settings          |


# User Settings
Source: https://docs.stackone.com/guides/user-settings

Manage your profile, change your password, and configure multi-factor authentication

Access your personal settings by clicking your name in the bottom-left corner of the dashboard.

<Frame>
  <img alt="User profile menu showing Account, Manage Team, Security, and Sign Out options" />
</Frame>

## Your Profile

The **Account** settings page displays your profile information:

| Field             | Description                   |
| ----------------- | ----------------------------- |
| **Name**          | Your display name (read-only) |
| **Email Address** | Your login email (read-only)  |
| **Joined**        | When you created your account |

<Note>
  To change your name or email, contact your organization administrator or StackOne support.
</Note>

## Change Password

1. Click **Change Password** in your account settings
2. Enter your current password
3. Enter and confirm your new password
4. Click **Save**

<Tip>
  Use a strong, unique password. Consider using a password manager like 1Password or Bitwarden.
</Tip>

## Multi-Factor Authentication

Add an extra layer of security to your account with MFA:

1. Click **Enable Multi-Factor Authentication**
2. Scan the QR code with your authenticator app (Google Authenticator, Microsoft Authenticator, 1Password, etc.)
3. Enter the 6-digit code from your authenticator
4. Click **Confirm**

<Warning>
  If your organization has enforced MFA, you'll be required to set it up on your next login.
</Warning>

## Sign Out

Click **Sign Out** from the user menu to end your session. You'll be redirected to the login page.

***

## Related

<CardGroup>
  <Card title="Managing Your Organization" icon="building" href="/guides/managing-your-organization">
    Team management and organization security (Org Admins only)
  </Card>

  <Card title="API Keys" icon="key" href="/guides/api-keys">
    Create and manage API keys for your projects
  </Card>
</CardGroup>


# OAuth Apps
Source: https://docs.stackone.com/guides/using-your-own-oauth-apps

When to use StackOne's shared OAuth credentials vs registering your own

When configuring OAuth connectors, you can use StackOne's shared credentials or register your own OAuth apps with each provider. The right choice depends on how you're using StackOne.

## Connecting your own tools

If you're using StackOne to connect your own company's accounts (your Salesforce, your HubSpot, your Google Drive), StackOne's shared credentials work well.

**When shared credentials work:**

* Low-volume internal tools and automations
* Connecting your team's SaaS accounts
* Testing and development
* Proof-of-concept integrations

**When to consider your own OAuth app:**

* You want your company name on the OAuth consent screen
* You need dedicated rate limits for high-volume usage
* Your security team requires it as a matter of policy

## Connecting your customers' tools

If you're using StackOne to let your customers connect their accounts (embedded iPaaS), **use your own OAuth apps for production**.

Your customers will see your brand during OAuth consent instead of a third party, you'll have dedicated rate limits, and if you ever want to list in a SaaS marketplace, you'll need your own credentials anyway. Register your OAuth apps early - verification can take weeks for some providers. In the meantime, you can use StackOne's credentials to keep testing. Contact support via in-app chat or Slack (or [support@stackone.com](mailto:support@stackone.com)) if you need additional connector profiles pre-configured with StackOne's OAuth apps.

<AccordionGroup>
  <Accordion title="🏪 Marketplace requirements">
    If you plan to list your integration in any major SaaS marketplace, this isn't optional.

    **HubSpot** requires your app to authorize requests with your own app ID. Apps using shared OAuth credentials are rejected during review.

    **Zendesk** explicitly prohibits using another developer's OAuth client. Their terms require third-party developers to use their own global OAuth client.

    **Microsoft** requires multitenant apps to register in your own Entra ID tenant. Since 2020, apps without Publisher Verification show warnings that the app is "risky to download."

    **Atlassian**, **Salesforce**, and **Google Workspace** all have similar requirements - partners must use their own OAuth applications registered under their own developer accounts.
  </Accordion>

  <Accordion title="🎨 Consent screen branding">
    When your customer clicks "Connect to Salesforce" in your app, the OAuth consent screen shows who's requesting access. With StackOne's credentials, they see "StackOne is requesting access to your account." With your own, they see your company name and logo.

    This matters for trust. Your customers chose your product, not StackOne. Seeing an unfamiliar name during authorization creates confusion and support tickets.

    Google and Microsoft also tie verification badges to the OAuth app owner. The blue "verified" checkmark only appears if *you* complete publisher verification - it doesn't transfer from StackOne's credentials.
  </Accordion>

  <Accordion title="🏢 Enterprise compliance">
    Enterprise customers often require vendors to use their own OAuth credentials as part of security reviews. This shows up in security questionnaires and vendor assessments.

    Having your own OAuth app also gives you:

    * Direct access to each provider's developer console
    * Visibility into your app's usage and quotas
    * Control over scopes and permissions requested
    * Ability to respond to provider security notifications directly
  </Accordion>

  <Accordion title="⚡ Dedicated rate limits">
    API rate limits are enforced per OAuth app, not per end-user or per StackOne customer.

    **Microsoft Graph** allows 130,000 requests per 10 seconds per app across all tenants using that app. **Google** quotas are per Cloud Project. **Slack** is particularly strict: non-Marketplace apps are limited to 1 request per minute for some endpoints, versus 50+ for verified apps.

    With shared credentials, one customer's bulk sync or misconfigured integration can exhaust limits for everyone. Your own OAuth app means your own quota - your customers aren't competing with other StackOne users.
  </Accordion>
</AccordionGroup>

## Setting up your own OAuth credentials

<Steps>
  <Step title="Register with the provider">
    Create an OAuth application in the provider's developer console (Google Cloud Console, Microsoft Entra ID, etc.).
  </Step>

  <Step title="Add the redirect URI">
    ```
    https://api.stackone.com/connect/oauth2/{provider}/callback
    ```

    Replace `{provider}` with the connector key (e.g., `hubspot`, `googledrive`).
  </Step>

  <Step title="Complete verification">
    Many providers require OAuth verification for production. Start early as this can take days or weeks.
  </Step>

  <Step title="Configure in StackOne">
    Go to [Connector Profiles](https://app.stackone.com/connector_profiles), select your connector, and enter your Client ID and Client Secret.
  </Step>
</Steps>

### Provider-specific guides

<CardGroup>
  <Card title="Google Drive" icon="google" href="/integration-guides/documents/googledrive-partner-oauth" />

  <Card title="SharePoint" icon="microsoft" href="/integration-guides/documents/sharepoint-oauth" />

  <Card title="OneDrive" icon="microsoft" href="/integration-guides/documents/onedrive-oauth" />

  <Card title="OAuth Proxy Redirect" icon="arrow-right-arrow-left" href="/integration-guides/oauth-proxy-redirect" />
</CardGroup>

## Decision guide

| Use case                      | StackOne credentials  | Your own OAuth app    |
| ----------------------------- | --------------------- | --------------------- |
| Testing / POC                 | ✅ Recommended         | Optional              |
| Connecting your own accounts  | ✅ Works well          | Optional              |
| Low-volume internal tools     | ✅ Works well          | If required by policy |
| High-volume usage             | ⚠️ Shared rate limits | ✅ Dedicated limits    |
| Production with end-customers | ⚠️ Not recommended    | ✅ Recommended         |
| Marketplace listing           | ❌ Won't pass review   | ✅ Required            |


# Webhooks
Source: https://docs.stackone.com/guides/webhooks

Receive notifications when events occur in your provider's system or in StackOne. Subscribe to events and react immediately to sync data, trigger workflows, or log activity.

## Introduction & Overview

StackOne's webhook system enables real-time event notifications between your application and integrated services. Instead of constantly polling for updates, webhooks provide an efficient way to receive immediate notifications when important events occur.

### What are Webhooks?

<Tooltip>Webhooks</Tooltip> are automated HTTP callbacks that allow real-time communication between systems:

1. Your application exposes an HTTPS endpoint to receive event notifications
2. StackOne sends HTTP POST requests with event data to your endpoint
3. Your application processes these events and responds accordingly

### Benefits of Using Webhooks

* **Real-time Updates**: Receive instant notifications about changes
* **Reduced API Load**: Eliminate the need for constant polling
* **Efficient Processing**: Handle events as they happen
* **Automated Workflows**: Trigger actions based on events
* **Resource Optimization**: Save resources by avoiding unnecessary API calls

<br />

<iframe title="StackOne - Accounts - Auth Link" />

## Getting Started with Webhooks

### Quick Start Guide

1. Navigate to [StackOne Webhooks Dashboard](https://app.stackone.com/webhooks)
2. Click "Add Webhook"
3. Enter your endpoint URL
4. Select desired events
5. Save and copy your signing secret
6. Implement signature verification in your application
7. Start receiving events!

### Webhook Dashboard Overview

The webhook dashboard at [https://app.stackone.com/webhooks](https://app.stackone.com/webhooks) lets you manage all your webhooks:

* **View & Configure**: Manage webhook settings and configurations
* **Monitor Health**: Track webhook delivery status and performance
* **Security**: Access signing secrets for request verification
* **Event Management**: Add or modify event subscriptions

### Prerequisites

Before setting up webhooks, ensure you have:

1. A publicly accessible HTTPS endpoint to receive webhooks
2. Ability to verify webhook signatures (recommended)
3. Proper error handling for webhook payloads
4. Rate limiting consideration for high-volume events

<Frame>
  <img alt="" />
</Frame>

<br />

## Setting up a new webhook

1. After selecting a StackOne project, you will see the `Webhooks` section in the left-hand-side menu.

2. Create and configure a new webhook by clicking the `Add Webhook` button

3. Input in the `Webhook URL` field a valid URL that StackOne should send a request to whenever one of the previously selected event occurs.

4. Select the events that your webhook should be triggered on, programmatic native, manual native, or synthetic events, the availability of which depends on the provider you're connecting to.

5. **Programmatic native events**: are events generated by the underlying provider which are then mapped to StackOne unified resource events. Once subscribed to a provider's programmatic native event, our system will programmatically create an event subscription in the provider's system for each currently linked account for that provider, and to any future linked account of that provider.

6. **Manual native events**: are events generated by the underlying provider which are then mapped to StackOne unified resource events. Unlike the programmatic events, manual events are not automatically subscribed to by our system. You will need to manually create an event subscription for each currently linked account for that provider, and to any future linked account of that provider. We'll provide you with a link to the URL the provider will send the event to, as well as a secret to authenticate the request.

7. **Synthetic Events:** For these events, StackOne periodically polls the underlying provider's records every hour and compares the stored hashes against the hashes of the mapped records received from the provider. Thanks to the hashing process, no PII is stored. The polling time can be configured based on your needs.

8. Finally, click on the `Save Webhook` button. You should now see your newly configured Webhook on the `webhooks` page.

9. Take note of the webhook secret displayed in the webhook listing page as it will allow you to verify the authenticity of events coming from StackOne, we'll use this secret to sign the webhook request based on the payload of the event.

   1. As a relatively less secure but simpler alternative, you can also verify events sent by StackOne by adding a custom query parameter to your webhook URL eg `?token=unique_secret_token ` and verify this parameter's presence when receiving the request.

### Overview Tab

The overview tab shows you at a glance the number of events sent to the configured webhook URL within the timeframe selected on the right-hand side (whether these events were successfully sent or if the request to the configured webhook URL failed)

<Frame>
  <img alt="" />
</Frame>

### Events Tab

#### Account Events

Account Events are events originating from StackOne related to a linked account connection and not to any underlying resource (eg: employee or candidates). Account events can be useful for your application/server to be notified of any new Accounts being linked (`account.created` event) or updated (`account.updated`) allowing you to trigger relevant workflow on your end (eg. syncing data from the underlying tenant).

#### Unified Events

The Events tab of the webhook configuration allows you to view and update the unified events this webhook is subscribed to. Any "green" in the table indicates that the webhook is currently subscribed to a programmatic native, manual native, or synthetic event for one or more providers. Anything in orange represents an event subscription that has been modified but not yet saved.

<Frame>
  <img alt="" />
</Frame>

<br />

### Health Tab

The health tab of the new webhook allows you to see at a glance the status of each underlying programmatic native webhook subscription for each linked account, as well as the status of the synthetic events execution.

### Disabling a webhook

You can disable a webhook by clicking the `Disable` button in the webhook listing page. This will stop the emission of events to the webhook URL.

### Enabling a webhook

You can enable a disabled webhook by clicking the `Enable` button in the webhook listing page. This will resume the emission of events to the webhook URL

### Deleting a webhook

You can delete a webhook by clicking the `Delete` button in the webhook listing page. This will remove the webhook from the webhook listing page and stop the emission of events to the webhook URL. This will also clean up the relevant programmatically created subscriptions for the linked accounts in the underlying provider's system.

<Warning>
  Deleting a webhook is irreversible.
</Warning>

### How StackOne Synthetic Webhooks Work

<Accordion title="How Synthetic Webhooks Work - Privacy-First Design">
  <Info>
    Synthetic webhooks provide event notifications through intelligent polling and cryptographic change detection. Unlike real-time webhooks, synthetic webhooks poll for changes with a default interval of 1 hour, which can be reduced to as low as 5 minutes based on resource availability and time filter support.
  </Info>

  StackOne's synthetic webhooks are generated through intelligent polling and change detection, unlike native webhooks that rely on the provider's webhook infrastructure.

  #### Key Privacy Features

  <CardGroup>
    <Card title="No PII Storage" icon="shield-halved">
      StackOne does not store any personally identifiable information (PII) when detecting changes
    </Card>

    <Card title="Cryptographic Hashing" icon="fingerprint">
      We use secure hashing algorithms to create unique fingerprints of resource states
    </Card>

    <Card title="Change Detection" icon="code-compare">
      By comparing hashes of current and previous states, we can detect changes without storing the actual data
    </Card>

    <Card title="Ephemeral Processing" icon="clock">
      Resource data is processed in memory and immediately discarded after hash generation
    </Card>
  </CardGroup>

  #### How It Works

  <Steps>
    <Step title="Polling">
      StackOne polls the provider for resource updates (default: every 1 hour, configurable down to 5 minutes)
    </Step>

    <Step title="Hashing">
      When data is retrieved, we generate a cryptographic hash of the resource state
    </Step>

    <Step title="Comparison">
      The new hash is compared with the previously stored hash (not the data itself)
    </Step>

    <Step title="Event Generation">
      If hashes differ, a change is detected and a webhook event is generated
    </Step>

    <Step title="Delivery">
      The webhook event is sent to your application with the resource identifier
    </Step>

    <Step title="Data Retrieval">
      Your application can then fetch the full resource data via API when needed
    </Step>
  </Steps>

  <br />

  ```mermaid theme={null}
  sequenceDiagram
      participant Client as Your Application
      participant StackOne
      participant Provider as Integration Provider
      participant Hash as Hash Storage

      Note over StackOne,Provider: Synthetic Webhook Process

      StackOne->>Provider: Poll for resources (periodic)
      Provider->>StackOne: Return resource data

      rect rgb(240, 248, 255)
          Note over StackOne: Privacy-First Processing
          StackOne->>StackOne: Generate cryptographic hash of resource
          StackOne->>Hash: Compare with stored hash
          Hash->>StackOne: Hash comparison result

          alt Hashes are different
              StackOne->>StackOne: Change detected!
              StackOne->>Hash: Update stored hash
              StackOne->>StackOne: Generate webhook event
              Note over StackOne: No PII stored, only hash
          else Hashes are identical
              Note over StackOne: No change, no action needed
          end
      end

      StackOne->>Client: Send webhook event (resource ID only)
      Client->>Client: Verify webhook signature
      Client->>StackOne: Return 200 OK

      opt Client needs full data
          Client->>StackOne: Request resource data via API
          StackOne->>Provider: Fetch current resource data
          Provider->>StackOne: Return resource data
          StackOne->>Client: Return transformed resource data
      end

      Note over Client,Hash: Privacy maintained throughout
  ```

  <Check>
    **Privacy Guarantees:**

    * Your data privacy is maintained at all times
    * StackOne can detect changes efficiently without storing sensitive information
    * You receive timely notifications about resource changes
    * The system remains compliant with data protection regulations
  </Check>
</Accordion>

```mermaid theme={null}
sequenceDiagram
    participant Client as Your Application
    participant StackOne
    participant Provider as Integration Provider

    StackOne->>Provider: Poll for changes to resources
    Provider->>StackOne: Respond with resource data
    StackOne->>StackOne: Process & transform resource data
    StackOne->>Client: Send webhook events
    Client->>Client: Verify webhook signature
    Client->>StackOne: Return 200 OK
    Client->>StackOne: Request resource data (if needed)
    StackOne->>Provider: Request resource data (if needed)
    Provider->>StackOne: Return resource data
    StackOne->>Client: Return resource data
    Note over Client,StackOne: Event processed successfully
```

### How StackOne Native Webhooks Work

```mermaid theme={null}
sequenceDiagram
    participant Client as Your Application
    participant StackOne
    participant Provider as Integration Provider

    Provider->>StackOne: Event occurs (e.g., new candidate)
    StackOne->>StackOne: Process & transform event
    StackOne->>Client: Send webhook event
    Client->>Client: Verify webhook signature
    Client->>StackOne: Return 200 OK
    Client->>StackOne: Request resource data (if needed)
    StackOne->>Provider: Request resource data (if needed)
    Provider->>StackOne: Return resource data
    StackOne->>Client: Return resource data
    Note over Client,StackOne: Event processed successfully
```

### Event subscriptions lifecycle details

* When a webhook is created, StackOne will programmatically create an event subscription in the underlying provider's system for each currently linked account for that provider, and to any future linked account of that provider.
* When a webhook is deleted, StackOne will clean up the relevant programmatically created subscriptions for the linked accounts in the underlying provider's system.
* When a webhook is disabled, StackOne will stop the emission of events to the webhook URL, but the event subscriptions in the underlying provider's system will remain active.
* When a webhook is enabled, StackOne will resume the emission of events to the webhook URL, and the event subscriptions in the underlying provider's system will remain active.

<Frame>
  <img alt="" />
</Frame>

#### `event` list and associated `record_type`

| Category  | Resource     | Events                                                                                |
| --------- | ------------ | ------------------------------------------------------------------------------------- |
| Accounts  | Accounts     | `account.created`, `account.updated`, `account.deleted`                               |
| HRIS      | Employees    | `hris_employees.created`, `hris_employees.updated`, `hris_employees.deleted`          |
|           | Employments  | `hris_employments.created`, `hris_employments.updated`, `hris_employments.deleted`    |
| ATS       | Assessments  | `ats_assessments.created`, `ats_assessments.updated`, `ats_assessments.deleted`       |
|           | Candidates   | `ats_candidates.created`, `ats_candidates.updated`, `ats_candidates.deleted`          |
|           | Applications | `ats_applications.created`, `ats_applications.updated`, `ats_applications.deleted`    |
|           | Interviews   | `ats_interviews.created`, `ats_interviews.updated`, `ats_interviews.deleted`          |
|           | Jobs         | `ats_jobs.created`, `ats_jobs.updated`, `ats_jobs.deleted`                            |
|           | Job Postings | `ats_job_postings.created`, `ats_job_postings.updated`, `ats_job_postings.deleted`    |
|           | Lists        | `ats_lists.created`, `ats_lists.updated`, `ats_lists.deleted`                         |
|           | Users        | `ats_users.created`, `ats_users.updated`, `ats_users.deleted`                         |
| CRM       | Accounts     | `crm_accounts.created`, `crm_accounts.updated`, `crm_accounts.deleted`                |
|           | Contacts     | `crm_contacts.created`, `crm_contacts.updated`, `crm_contacts.deleted`                |
| LMS       | Assignments  | `lms_assignments.created`, `lms_assignments.updated`, `lms_assignments.deleted`       |
|           | Completions  | `lms_completions.created`, `lms_completions.updated`, `lms_completions.deleted`       |
|           | Content      | `lms_content.created`, `lms_content.updated`, `lms_content.deleted`                   |
|           | Courses      | `lms_courses.created`, `lms_courses.updated`, `lms_courses.deleted`                   |
|           | Users        | `lms_users.created`, `lms_users.updated`, `lms_users.deleted`                         |
| Documents | Files        | `documents_files.created`, `documents_files.updated`, `documents_files.deleted`       |
|           | Folders      | `documents_folders.created`, `documents_folders.updated`, `documents_folders.deleted` |

<Note>
  The webhook settings such as `URL` and `Events` can be updated at any point after creating the webhook by returning to the Webhooks page and clicking on the webhook you would like to update.\
  You can also delete the webhook if it's no longer needed (irreversible action).
</Note>

## Event payload

### Account Events

Accounts-based webhooks will follow the following interface:

```typescript theme={null}
{
  project_id: string, // the ID of the StackOne project
  event: 'account.updated' | 'account.created' | 'account.deleted' | 'hris_employees.updated', 'hris_employees.created',
  event_date: 'string', // date as ISO string (eg: '2023-07-03T01:55:47.217Z')
  record_type: 'account',
  record_id: string | number, // In the case of accounts-based events - this will be the account ID
  sent_at: 'string', // date as ISO string (eg: '2023-07-03T01:55:47.217Z')
  account_id: string, // This will always be the Account ID
  provider: string, // The provider the account is connected to
  origin_owner_id?: string, // unique identifier used to track customers or organizations
  origin_owner_name?: string, // human-readable name associated with Origin Owner ID
  origin_username?: string, // username responsible for connecting the tool
  setup_information?: object, // extra information used to setup the account
}
```

#### Account updated event `account.updated` example

```json theme={null}
{
  "project_id": "acmeinc-27270",
  "account_id": "GnQoASvosYhE5wJcmmAQs",
  "event": "account.updated",
  "event_date": "2023-11-01T13:10:31.408Z",
  "record_type": "account",
  "record_id": "GnQoASvosYhE5wJcmmAQs",
  "sent_at": "2023-11-01T13:10:31.418Z",
  "provider": "integration_key",
  "origin_owner_id": "unique-org-identifier",
  "origin_owner_name": "Test organization",
  "origin_username": "sample-user",
  "setup_information": {
    "domain": "companytest"
  }
}
```

### Unified Events

Unified events are events for a unified resource type, such as an employee, a job, a candidate, etc. Synthetic events will not contain the `raw_event` field due to the nature of the hashing process.

<Warning>
  Note:

  Synthetic events will not contain the `raw_event` or `event_data` fields due to the nature of the hashing process. Native events will contain the `raw_event` field, containing the original event payload received from the provider, as well as `event_data` which contains as much mapped data as possible from the original event payload.
</Warning>

```typescript theme={null}
{
  project_id: string, // the ID of the StackOne project
  event: string, // the event name
  event_date: string, // date as ISO string (eg: '2023-07-03T01:55:47.217Z')
  record_type: string, // the type of the resource
  record_id: string | number, // the ID of the resource
  sent_at: string, // date as ISO string (eg: '2023-07-03T01:55:47.217Z')
  raw_event?: object, // native events only - the original event payload received from the provider
  event_data?: object, // native events only - the mapped data from the original event payload
}
```

#### Synthetic event example

```json theme={null}
{
  "project_id": "acmeinc-27270",
  "account_id": "GnQoASvosYhE5wJcmmAQs",
  "event": "hris_employees.updated",
  "event_date": "2023-11-01T15:09:22.961Z",
  "record_type": "employees",
  "record_id": "3223323715753018140",
  "sent_at": "2023-11-01T15:09:22.978Z"
}
```

#### Native event example

```json theme={null}
{
  "project_id": "dev-56501", // StackOne Project ID
  "account_id": "GnQoASvosYhE5wJcmmAQs", // StackOne Linked Account ID
  "event": "ats-job_postings.updated", // Unified Event name
  "event_date": "2024-11-13T17:01:16.0007", // Datetime string of when the event was received by StackOne from the provider
  "record_type": "ats_job_postings", // Unified Resource Type
  "record_id": "cxIQam9iX2lkOjEzMmM3ZWRjLWNmMTktNDdjMy1hODdlLTUxMzU3NDI4ZDVmZA", // StackOne Identifier for the resource
  "record_remote_id": "132c7edc-cf19-47c3-a87e-51357428d5fd", // Original (remote) Identifier for the resource
  "sent_at": "2024-11-13T17:01:16.844Z", // Timestamp of when the event was sent to the configured webhook URL

  // original event data including original payload
  "raw_event": {
    "headers": {
      "smartrecruiters-timestamp": "1731517276",
      "content-type": "application/json"
    },
    "body": {
      "job_id": "18dedcd5-2509-4363-a565-7b63b2ablaf1",
      "job_ad_id": "132c7edc-cf19-47c3-a87e-51357428d5fd"
    }
  }
}
```

### Webhook signature verification

We'll use the signature secret we mentioned in the previous section to verify the authenticity of the webhook request. To do so we'll send a `x-stackone-signature` header. This header will contain an [hmac](https://www.okta.com/identity-101/hmac/#:~:text=Hash%2Dbased%20message%20authentication%20code,use%20signatures%20and%20asymmetric%20cryptography.) `sha256` hash of the given payload using the `Signature Secret` previously given as a secret key during hashing.

<Warning>
  3rd party Webhook generators:

  You can easily test the account-based webhooks by using a third-party webhook creation tool such as [https://typedwebhook.tools/](https://typedwebhook.tools/) or by setting-up a proxy to your localhost via [ngrok](https://ngrok.com/).

  StackOne is not affiliated with these websites.
</Warning>

## Understanding Webhook Payloads

### What information is included in webhook event payloads?

Webhook event payloads follow a consistent structure across all providers and resource types. The payload includes metadata about the event but does not contain the actual data changes.

**Standard webhook payload fields:**

* `project_id`: The StackOne project identifier
* `account_id`: The connected account identifier
* `event`: The type of event (e.g., `hris_employees.updated`, `ats_candidates.created`)
* `event_date`: ISO timestamp when the event occurred
* `record_type`: The resource type affected (e.g., `employees`, `candidates`)
* `record_id`: The unique identifier of the affected record
* `sent_at`: ISO timestamp when the webhook was sent
* `provider`: The provider name

### How do I determine what specific fields were updated in a webhook event?

Webhook payloads do not include field-level change information or data diffs. To identify what specific fields were updated:

1. **Use the webhook payload identifiers**: Extract the `record_id` and `account_id` from the webhook payload
2. **Make a follow-up API call**: Use these identifiers to retrieve the current state of the record via the appropriate StackOne API endpoint
3. **Compare with your stored data**: Compare the retrieved record with your previously stored version to identify changes

**Example workflow:**

```
1. Receive webhook: hris_employees.updated for record_id "12345"
2. Call GET /unified/hris/employees/12345 with the account_id
3. Compare returned employee data with your stored version
4. Identify and process the specific field changes
```

### Why don't webhook payloads include the actual data changes?

StackOne uses data hashing for change detection rather than field-level tracking. This approach:

* **Protects data privacy**: Sensitive information is not included in webhook payloads
* **Ensures consistency**: All providers follow the same webhook payload structure
* **Provides flexibility**: Allows you to retrieve only the current record state when needed
* **Prevents unnecessary requests**: You may not be interested in every webhook event or individual resources (e.g., you only care about webhooks related to specific File IDs, or for specific Candidates etc.), avoiding unnecessary data retrieval from the underlying provider

### Troubleshooting Webhook Delivery Issues

**Common troubleshooting steps:**

1. **Verify webhook configuration**:
   * Check that your webhook URL is accessible and returns HTTP 200
   * Ensure the webhook is configured for the correct events
   * Verify the webhook is active in your StackOne project

2. **Check webhook signature validation** (optional step that adds complexity):
   * Ensure your endpoint validates the `x-stackone-signature` header if implementing signature verification
   * Verify you're using the correct signing secret
   * Confirm your HMAC SHA256 validation logic is correct
   * Note: For most use cases, signature verification may not be necessary

3. **Review webhook logs**:
   * Check the main webhook view/logs in the StackOne dashboard
   * Look for failed delivery attempts or error responses (these appear in webhook logs, not the health tab)
   * Verify underlying provider webhook subscriptions are active

4. **Test connectivity**:
   * Use tools like ngrok for local development testing
   * Ensure your webhook endpoint is publicly accessible
   * Check for any firewall or network restrictions

### Triggering a webhook event manually for testing purposes

In case you want to verify that your webhook is working as expected, you can trigger a webhook event manually by using an API key from the API keys section of the project you're working on, getting the webhook ID from the webhook details URL, and calling the webhook events endpoint like so:

```bash theme={null}
curl -X POST "https://api.stackone.com/webhooks/events" \
  -u "$STACKONE_API_KEY:" \
  -H "Content-Type: application/json" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -d '{
    "webhook_ids": [123],
    "events": [
      { "event": "hris_employees.created", "record_id": "123456" }
    ]
  }'
```

### Sample Webhook consumer code

An example of a webhook consumer code in Node.js with signature verification can be found below:

```javascript theme={null}
// index.js
import express from 'express';
import bodyParser from 'body-parser';
import { createHmac } from 'crypto';
const app = express();

// Replace with the signing secret string displayed on the StackOne webhooks details page
const STACKONE_WEBHOOK_SIGNATURE =
  'S-gQTtwraolKVsY88OvQNZ-TlGrHw9mvHKp-ls8Co9CkOADQc1VSeCZ_2hDK6oWuKUd_4qxjRLzoEGYA9JVCNg';


/**
 * The function checks if a given signature is valid by comparing it with the payload hash using a signing secret.
 * @param signature - The `signature` parameter is the signature value that you want to validate. It is typically a string
 * representing the cryptographic signature of the `payload` parameter.
 * @param payload - The payload is the data that needs to be signed. It can be any string or object that you want to verify
 * the integrity of.
 * @param signingSecret - The `signingSecret` parameter is a secret key used for generating the signature. It is a string
 * value that should be kept confidential and known only to the parties involved in the signature verification process.
 * @returns a boolean value indicating whether the calculated hash is equal to the provided signature.
 */
function isSignatureValid(signature, payload, signingSecret) {
  const hash = createHmac('sha256', signingSecret)
    .update(payload)
    .digest('base64url');
  return hash === signature;
}

const jsonParser = bodyParser.json();

app.post('/integrations/webhook/accounts', jsonParser, (req, res) => {
  const signature = req.headers['x-stackone-signature'];
  if (
    !signature ||
    !isSignatureValid(
      req.headers['x-stackone-signature'],
      JSON.stringify(req.body),
      STACKONE_WEBHOOK_SIGNATURE,
    )
  ) {
    return res.status(401).send('Unauthorized');
  }
  // Do something with the payload
  console.log(req.body);

  // The webhook URL should return a 200 upon successful processing of the event. The response does not need to include anything else.
  return res.status(200).send(`Thank you for the account webhook event ❤️`);
});

console.log('listening on port 3333');
app.listen(3333);

// This sample server can be run via `node index.js`
```

<br />

## Signing Secret Rotation

You can rotate the webhook signing secret by following this process

1. Create a new signing secret by clicking on the existing secret to view and click with the `Add Signing Secret` button

   <Frame>
     <img alt="" />
   </Frame>

   The new signing secret will be flagged as inactive and requests sent to your webhook URL will only be signed with the active signing secret

   <Frame>
     <img alt="" />
   </Frame>

2. In StackOne: Copy this new (currently inactive) signing secret value

   <Frame>
     <img alt="" />
   </Frame>

3. In your own codebase:**update the verification logic to verify the request with both the current secret and the new one copied in the previous step.**

4. In StackOne: Activate the new webhook signing secret by clicking on it and confirming the activation. Once activated all requests sent to your webhook URL by StackOne will be signed using this new secret.

5. In StackOne: Once you've verified that new requests are being verified as expected, you may delete the old secret. *You will not be able to retrieve it or activate it again once deleted.*

6. In your own codebase: remove the logic responsible for verifying the request with the now inactive / deleted signing secret

## Troubleshooting & Monitoring

### Common Issues and Solutions

1. **Webhook Not Receiving Events**
   * Verify webhook is enabled in dashboard
   * Check endpoint URL is accessible
   * Review event subscriptions
   * Inspect webhook health tab

2. **Signature Verification Failures**
   * Confirm correct signing secret usage
   * Check for payload modifications
   * Verify signature calculation method
   * Ensure correct encoding (base64url)

3. **Missing Events**
   * Check webhook health metrics
   * Review retry status
   * Verify event subscriptions
   * Consider synthetic events for reliability
   * Add logging to your webhook consumer code when an event is received in your application

4. **Performance Issues**
   * Implement async processing
   * Optimize response time
   * Consider rate limiting
   * Monitor resource usage

### Production Checklist

* Implement proper error handling
* Set up monitoring and alerting
* Configure retry policies
* Document recovery procedures
* Test failure scenarios
* Monitor resource usage
* Regular security reviews

<Note>
  Keep your webhook endpoints efficient and reliable:

  * Process events asynchronously
  * Implement proper error handling
  * Monitor webhook health regularly
  * Maintain security best practices
</Note>


# Get Group
Source: https://docs.stackone.com/iam/api-reference/groups/get-group

get /unified/iam/groups/{id}



# List Groups
Source: https://docs.stackone.com/iam/api-reference/groups/list-groups

get /unified/iam/groups



# Get Me
Source: https://docs.stackone.com/iam/api-reference/me/get-me

get /unified/iam/me



# Get Organization
Source: https://docs.stackone.com/iam/api-reference/organizations/get-organization

get /unified/iam/organizations/{id}



# List Organizations
Source: https://docs.stackone.com/iam/api-reference/organizations/list-organizations

get /unified/iam/organizations



# Get Policy
Source: https://docs.stackone.com/iam/api-reference/policies/get-policy

get /unified/iam/policies/{id}



# List Policies
Source: https://docs.stackone.com/iam/api-reference/policies/list-policies

get /unified/iam/policies



# List Resource Types
Source: https://docs.stackone.com/iam/api-reference/resource-types/list-resource-types

get /unified/iam/resource_types



# List Resource Users
Source: https://docs.stackone.com/iam/api-reference/resource-users/list-resource-users

get /unified/iam/resource_users



# Get Role
Source: https://docs.stackone.com/iam/api-reference/roles/get-role

get /unified/iam/roles/{id}



# List Roles
Source: https://docs.stackone.com/iam/api-reference/roles/list-roles

get /unified/iam/roles



# Delete User
Source: https://docs.stackone.com/iam/api-reference/users/delete-user

delete /unified/iam/users/{id}



# Get User
Source: https://docs.stackone.com/iam/api-reference/users/get-user

get /unified/iam/users/{id}



# List Users
Source: https://docs.stackone.com/iam/api-reference/users/list-users

get /unified/iam/users



# Update User
Source: https://docs.stackone.com/iam/api-reference/users/update-user

patch /unified/iam/users/{id}



# Basic Authentication with StackOne API
Source: https://docs.stackone.com/iam/common-guide/basic-authentication-with-stackone-api

Learn how to authenticate with the StackOne API using Basic Authentication.

## Overview

StackOne uses API key-based authentication to secure access to all endpoints. This guide explains how to use your API keys with Basic Authentication to make secure requests to the StackOne API.

<Info>
  **Basic Authentication** is one of the simplest authentication methods where credentials are sent as a Base64-encoded string in the Authorization header.
</Info>

## Prerequisites

Before using Basic Authentication, ensure you have completed these steps:

➡️ **[Create an API Key](/guides/api-keys)** : Generate your API key from the StackOne Dashboard

## Steps for Basic Authentication

<Steps>
  <Step title="Convert the API Key into a Base64 Encoded String">
    To authenticate using Basic Auth, you must convert your API key into a Base64 encoded string.

    <Warning>
      **Important**: The API key must be base64 encoded when using Basic authentication. You cannot use the raw API key directly.
    </Warning>

    Here are examples of how to encode your API key:

    **Terminal/Command Line:**

    ```bash theme={null}
    echo -n "your_api_key_here" | base64
    ```

    **Python:**

    ```python theme={null}
    import base64

    api_key = 'your_api_key_here'
    base64_api_key = base64.b64encode(api_key.encode()).decode()
    print(base64_api_key)
    ```

    **JavaScript/Node.js:**

    ```javascript theme={null}
    const apiKey = 'your_api_key_here';
    const base64ApiKey = Buffer.from(apiKey).toString('base64');
    console.log(base64ApiKey);
    ```

    **Example**: If your API key is `v1.eu1.abc123xyz`, the base64 encoded result would be: `djEuZXUxLmFiYzEyM3h5eg==`
  </Step>

  <Step title="Using the Base64 Encoded API Key for API Requests">
    Include the Base64 encoded API key in the Authorization header of your requests.

    **Header Format:**

    ```bash theme={null}
    Authorization: Basic <BASE64_ENCODED_API_KEY>
    ```

    **Complete cURL Example:**

    ```bash theme={null}
    curl --request GET \
         --url 'https://api.stackone.com/accounts' \
         --header 'accept: application/json' \
         --header 'authorization: Basic djEuZXUxLmFiYzEyM3h5eg=='
    ```
  </Step>

  <Step title="Making Unified API Requests">
    For unified API endpoints, you'll also need to include the account ID in the `x-account-id` header:

    ```bash theme={null}
    curl --request GET \
         --url 'https://api.stackone.com/unified/ats/applications' \
         --header 'accept: application/json' \
         --header 'authorization: Basic djEuZXUxLmFiYzEyM3h5eg==' \
         --header 'x-account-id: your_account_id_here'
    ```

    <Note>
      Replace `your_account_id_here` with the actual account ID obtained from the [List Accounts](/platform/api-reference/accounts/list-accounts) endpoint.
    </Note>
  </Step>

  <Step title="Using StackOne SDKs with Basic Authentication">
    StackOne provides official SDKs for multiple programming languages that simplify API integration and handle authentication automatically. Here's how to initialize each SDK with your API key:

    <Tabs>
      <Tab title="TypeScript">
        ```typescript theme={null}
        import { StackOne } from '@stackone/stackone-client-ts';

        // Initialize the StackOne client with your API credentials
        const stackOne = new StackOne({
          security: {
            username: "your_api_key_here",
            password: "",
          },
        });

        // Example: List accounts
        const accounts = await stackOne.accounts.list();

        // Example: Make a unified API request
        const applications = await stackOne.ats.applications.list({
          accountId: 'your_account_id_here'
        });
        ```
      </Tab>

      <Tab title="Ruby">
        ```ruby theme={null}
        require 'stackone_client'

        # Initialize the StackOne client with your API key
        s = ::StackOne::StackOne.new(
          security: Models::Shared::Security.new(
            password: "",
            username: "your_api_key_here",
          ),
        )

        # Example: List accounts
        res = s.accounts.list_linked_accounts()
        if ! res.linked_accounts_paginated.nil?
          # handle response
        end

        # Example: Make a unified API request
        req = Models::Operations::AtsListApplicationsRequest.new(
          x_account_id: "your_account_id_here",
        )
        res = s.ats.list_applications(req)
        if ! res.applications_paginated.nil?
          # handle response
        end
        ```
      </Tab>

      <Tab title="PHP">
        ```php theme={null}
        <?php
        require_once 'vendor/autoload.php';

        use StackOne\client;
        use StackOne\client\Models\Components;

        // Initialize the StackOne client with your API credentials
        $sdk = client\StackOne::builder()
            ->setSecurity(
                new Components\Security(
                    username: 'your_api_key_here',
                    password: '',
                )
            )
            ->build();

        // Example: List accounts
        $result = $sdk->accounts->listLinkedAccounts();

        // Example: Make a unified API request
        $result = $sdk->ats->listApplications(
            xAccountId: 'your_account_id_here',
        );
        ?>
        ```
      </Tab>

      <Tab title="Java">
        ```java theme={null}
        import com.stackone.stackone_client_java.StackOne;
        import com.stackone.stackone_client_java.models.components.Security;
        import com.stackone.stackone_client_java.models.operations.ListLinkedAccountsResponse;
        import com.stackone.stackone_client_java.models.operations.AtsListApplicationsResponse;

        // Initialize the StackOne client with your API credentials
        StackOne sdk = StackOne.builder()
            .security(Security.builder()
                .username("your_api_key_here")
                .password("")
                .build())
            .build();

        // Example: List accounts
        ListLinkedAccountsResponse res = sdk.accounts().listLinkedAccounts()
            .call();

        // Example: Make a unified API request
        AtsListApplicationsResponse res = sdk.ats().listApplications()
            .xAccountId("your_account_id_here")
            .call();
        ```
      </Tab>

      <Tab title="C#">
        ```csharp theme={null}
        using StackOneHQ.Client;
        using StackOneHQ.Client.Models.Components;
        using StackOneHQ.Client.Models.Operations;

        // Initialize the StackOne client with your API credentials
        var sdk = new StackOneHQClient(security: new Security() {
            Username = "your_api_key_here",
            Password = "",
        });

        // Example: List accounts
        var res = await sdk.Accounts.ListLinkedAccountsAsync();

        // Example: Make a unified API request
        var res = await sdk.Ats.ListApplicationsAsync(new AtsListApplicationsRequest() {
            XAccountId = "your_account_id_here",
        });
        ```
      </Tab>
    </Tabs>

    <Note>
      The SDKs automatically handle Base64 encoding and proper Authorization header formatting for HTTP Basic Authentication. Provide your raw API key in the `username` field and leave `password` empty when initializing the client.
    </Note>
  </Step>
</Steps>

## Security Best Practices

<Warning>
  **Store API Keys Securely**: Never expose API keys in client-side code, version control, or public repositories. Store them in secure locations such as environment variables or key vaults.
</Warning>

* Use environment variables to pass API keys to your application
* Rotate API keys regularly for enhanced security
* Use API key scopes to limit permissions when possible
* Monitor API key usage through the StackOne Dashboard

## Next Steps

After setting up Basic Authentication:

1. **[Making Your First API Request](/guides/making-your-first-api-request)** - Step-by-step examples for common API operations
2. **[Explore API Endpoints](/platform/api-reference)** - Browse available Platform API endpoints
3. **[Try Unified APIs](/documents/introduction)** - Start with Documents or IAM
4. **[Use SDKs](/guides/stackone-api-sdks)** - Simplify integration with official SDKs
5. **[Set up Webhooks](/guides/webhooks)** - Get real-time updates from connected providers

## Additional Resources

* [API Keys Management Guide](/guides/api-keys)
* [Making Your First API Request](/guides/making-your-first-api-request)
* [StackOne API SDKs](/guides/stackone-api-sdks)
* [Rate Limiting](/guides/rate-limiting)


# Expression Language Syntax
Source: https://docs.stackone.com/iam/common-guide/expression-language-syntax

Learn about the expression language syntax for field mapping and transformations.

There are three types of expressions supported:

### JSON Path Expressions

When the expression starts with `$`, it is treated as a JSON Path expression and will be evaluated as such.

#### JSON Path Syntax

| JSON Path              | Description                                                        |
| ---------------------- | :----------------------------------------------------------------- |
| `$`                    | The root object                                                    |
| `.`                    | Child operator                                                     |
| `@`                    | The current object                                                 |
| `*`                    | Wildcard. All elements in an array, or all properties of an object |
| `..`                   | Recursive descent                                                  |
| `[]`                   | Subscript operator                                                 |
| `[,]`                  | Union operator                                                     |
| `[start : end : step]` | Array slice operator                                               |
| `?(expression)`        | Filter expression                                                  |
| `()`                   | Script expression                                                  |

Examples:

```js theme={null}
// Given the context: { user: { name: "John", age: 30 }, "info/email": "info@email.com" }
'$.user.name'         // Returns "John"
'$.user.age'          // Returns 30
'$.user[*]'           // Returns ["John", 30]
'$["info/email"]'     // Returns "info@email.com"
```

For more information on JSON Path syntax, refer to the original [JSON Path documentation](https://goessner.net/articles/JsonPath/).

### JEXL Expressions

This kind of expression is enclosed in double brackets `{{expression}}`. It supports variables and operators.

#### Operators

| Operator | Description                    |
| :------- | :----------------------------- |
| `!`      | Logical NOT                    |
| `+`      | Addition, string concatenation |
| `-`      | Subtraction                    |
| `*`      | Multiplication                 |
| `/`      | Division                       |
| `//`     | Floor division                 |
| `%`      | Modulus                        |
| `^`      | Exponentiation                 |
| `&&`     | Logical AND                    |
| `\|`     | Logical OR                     |
| `==`     | Equal                          |
| `!=`     | Not equal                      |
| `>`      | Greater than                   |
| `>=`     | Greater than or equal          |
| `<`      | Less than                      |
| `<=`     | Less than or equal             |
| `in`     | Element of string or array     |
| `? :`    | Ternary operator               |

Examples:

```js theme={null}
// Given the context: { x: 10, y: 5 }
'{{x + y}}'                  // Returns 15
'{{x * 2}}'                  // Returns 20
'{{x > y}}'                  // Returns true
'{{x == 10 ? "yes" : "no"}}' // Returns "yes"
'{{x in [1, 2, 3]}}'         // Returns false
'{{x != y}}'                 // Returns true
```

#### Identifiers

Identifiers can be used to reference variables in the context.

```js theme={null}
// Given the context:
// { 
//     name: {
//         first: "John",
//         last: "Smith"
//     },
//     jobs: ["Developer", "Designer"]
// }
`{{name.first}}`          // Returns "John"
`{{jobs[1]}}`             // Returns "Designer"
```

#### Collections

Collections, or arrays of objects, can be filtered by including a filter expression in brackets.

```js theme={null}
// Given the context:
// {
//     users: [
//         { name: "John", age: 30 },
//         { name: "Jane", age: 25 }
//     ]
// }
`{{users[.name == "John"].age}}` // Returns 30
`{{users[.age > 25].name}}`      // Returns ["John"]
```

### String Interpolation

To simplify strings usage, a more straightforward syntax is provided for string interpolation of variables using the `${var}` syntax.

Examples:

```js theme={null}
// Given the context: { name: "John", age: 30 }
"Hello ${name}"       // Returns "Hello John"
"User is ${age}"    // Returns "User is 30"
```

Note: If the expression is a string without any of the patterns described above, it will be returned as is.

```js theme={null}
// Given the context: { name: "John", age: 30 }
"Hello world"       // Returns "Hello world"
```

For more information on the JEXL syntax, refer to the [JEXL Syntax documentation](https://commons.apache.org/proper/commons-jexl/reference/syntax.html).


# Field Coverage
Source: https://docs.stackone.com/iam/common-guide/field-coverage

Understand which fields are supported across different connectors and API operations.

<Frame>
  <img alt="" />
</Frame>

# Overview

Field Coverage is a feature in StackOne that helps you understand which fields are supported across different connectors and API operations. This tool is great for planning your implementation, evaluating connector compatibility, and ensuring your use cases can be fully supported.

> Field Coverage is available in the Dashboard at [app.stackone.com/field\_coverage](https://app.stackone.com/field_coverage)

# Key Features

## Search Experience

The field coverage interface provides a multiselect search experience.

* Search by field and model
* Layer multiple search terms and filters to display the union of all results
* Fuzzy search - find fields and models even with partial or similar names

<Frame>
  <img alt="" />
</Frame>

## Filters

### Integration Filters

Filter field coverage by specific connectors to focus on those relevant to your use case.

* **Category filters**: HRIS, ATS, CRM, LMS, Marketing, Documents, etc.
* **Provider filters**: Specific providers (e.g., BambooHR, Greenhouse, HubSpot)
* **Status filters**: Active connectors

### Operation Filters

Narrow down results by operation filters.

* **List operations**: Fields available when listing resources
* **Get operations**: Fields available when retrieving individual resources
* **Create operations**: Fields that can be set when creating new resources
* **Update operations**: Fields that can be modified in existing resources

<Frame>
  <img alt="" />
</Frame>

## Export Behavior

Field coverage data can be exported as CSV for analysis and documentation.

* **CSV export**: For spreadsheet analysis and reporting

### Export Options

1. **Full export**: All field coverage data across all connectors
2. **Filtered export**: Only data matching your current filters

<Frame>
  <img alt="" />
</Frame>

## Key/Legend

Understanding the visual indicators in field coverage.

### Operation Indicators

* **GET - Green G**
* **LIST - Blue L**
* **CREATE - Brown C**
* **UPDATE - Purple U**
* **UPSERT - Teal UP**

### Capability Indicators

* **Custom fields**: Wrench/gear icon indicating custom field support
* **Enums**: Lowercase 'e' icon indicating enum field support
* **Required**: Red dot in white square indicating required fields
* **Conditionally required**: Orange dot with red outline indicating conditionally required fields
* **Filtering**: Filter icon indicating filtering support
* **Batch**: Refresh/sync icon indicating batch operation support
* **Unsupported by Provider**: Grey icon with strikethrough indicating unsupported fields

<Frame>
  <img alt="" />
</Frame>

# Use Cases

## Evaluating New Connectors

**Scenario**: You want to evaluate whether a new connector can support your use case.

### Step-by-Step Process

1. **Filter for the specific integration**
   * Choose the relevant category (HRIS, ATS, CRM, etc.)
   * Use the integration filter to select the connector you're evaluating

2. **Search for specific fields**
   * Use the search functionality to find fields critical to your use case
   * Look for both exact matches and similar field names

3. **Expand relevant objects/models**
   * Click on objects to see their complete field structure
   * Check nested objects and relationships

4. **Analyze coverage**
   * Review the coverage indicators for each required field
   * Note any limitations or unsupported fields

5. **Export results**
   * Export the filtered data for stakeholder review
   * Document gaps and workarounds

## Integration Planning

**Scenario**: Planning a new integration and need to understand field availability.

### Best Practices

1. **Start with core fields**
   * Identify the essential fields for your use case
   * Check coverage across multiple potential connectors

2. **Compare connectors**
   * Use filters to compare field support across different providers
   * Export comparison data for decision-making

3. **Plan for gaps**
   * Identify unsupported fields early
   * Consider alternative approaches or custom field mapping

## API Development

**Scenario**: Building an application that consumes StackOne APIs.

### Development Workflow

1. **Research field availability**
   * Use field coverage to understand what data is available
   * Plan your data models based on actual field support

2. **Handle field variations**
   * Use the expand functionality to understand field differences
   * Implement fallback logic for unsupported fields

3. **Optimize API calls**
   * Use field coverage to determine which fields to request
   * Avoid requesting unsupported fields to improve performance

# Caveats and Disclaimers

## Coverage Accuracy

<Warning>
  **Field coverage data may not always reflect the complete picture**
</Warning>

* **Dynamic fields**: Some connectors support dynamic or custom fields that may not appear in coverage data
* **Provider updates**: Integration providers may add or modify fields without immediate coverage updates
* **Conditional support**: Some fields may be available under specific conditions or configurations

## Limitations

### Data Freshness

* Field coverage is updated regularly but may lag behind provider changes
* Always verify critical field support through testing or direct API calls

## Best Practices

1. **Verify with testing**: Always test critical fields with actual API calls
2. **Stay updated**: Regularly check field coverage for updates
3. **Contact support**: Reach out to StackOne support for clarification on specific field support
4. **Document findings**: Keep records of field support for your specific use cases

# Getting Help

If you need assistance with field coverage or have questions about specific field support:

* **Status Page**: Check [status.stackone.com](https://status.stackone.com) for system status and incidents
* **Documentation**: Check the relevant [API Reference](/hris/introduction) for detailed field information
* **Support**: Contact StackOne support through the in-app support, email ([support@stackone.com](mailto:support@stackone.com))


# Field Mapping
Source: https://docs.stackone.com/iam/common-guide/field-mapping

Learn how to map custom fields across different providers using StackOne's unified field mapping.

<Frame>
  <img alt="" />
</Frame>

# Overview

Custom Unified Fields enables you to create bespoke fields that and implement them across any connector already supported on the StackOne platform.

This gives you flexibility and control over any unified API and connectors available on StackOne, allowing you to tailor each connector to meet your specific product needs.

➡️ Custom unified fields can only use data that is already returned by underlying connectors. You cannot fetch additional requests or use data not already present in the underlying provider requests that StackOne's default unified operations make.

➡️ Custom unified fields are, like any other unified fields, real-time by default meaning that the data returned by the StackOne unified API will reflect the latest values from the source fields.

> 🙋 Reach out to StackOne's support to get Custom Unified Fields enabled for your organization

# Use-cases

Use-cases are broad and entirely dependant on the product and feature you're building and what type of connectors you're using. Some examples of custom unified fields:

* A new `emergency_contact_number` to be retrieved when listing [Employees](/hris/api-reference/employees/list-employees) (HRIS)
* A `multi_factor_authentication` boolean variable on IAM [Users](/iam/api-reference/users/list-users) on top of the existing array (IAM)
* Support for an LMS [Content](/lms/api-reference/content/list-content) `label` surfacing label and tag data from LMS systems that support it (LMS)

# Nomenclature:

We'll refer throughout the guides and user interface to various properties

* **Custom Unified Field:** A user-defined field that can be mapped and unified across various connectors by a Project Admin
* **Variable Key:** The unique identifier for the custom field.
* **Display Name:** The user-friendly name for the custom field.
* **Variable Type:** The data type of the custom field (currently only primitive data types are supported).
* **Field Mapping:** The process of linking a custom unified field to fields from different HR systems.

# Creating and managing fields

Project admins can access the field mapping section by clicking on ["Field Mapping"](https://app.stackone.com/field_mapping) in the left-hand menu.:

<Frame>
  <img alt="" />
</Frame>

To create the Custom Unified Field, you will need to specify the necessary details such as the Variable Key (which will be the actual property key in the returned JSON, an associated Type and a name & description to go with it (meant more for documentation and readability purposes as these latter two will not be returned in the request's response). All these details can be updated later via the `edit` button.

<Frame>
  <img alt="" />
</Frame>

### Limitations

* **Data Types:** Only primitive data types (string, number, boolean) are supported. Values will be typecasted when possible.
* **Operations:** Initially, only read operations (List and Get) are supported. Write operations will be introduced in future updates.

# Future capabilities of custom unified fields

Currently, Custom Unified Field mapping allows you to pull and use information that is already returned by the provider. Here's what we'll enable and add in future release

* Ability to update and add underlying provider requests so you can use more data from the underlying tools
* Creation of brand new operations and unified models
* Operations, formulas and functions so you can create more complex, derived fields and values.
* Account specific overrides so you can have different mapping per account and use tenant-based custom fields for specific field mappings when relevant

# FAQ

**Why can't I see the `Field Mapping` section in the side-menu?**\
The feature is only available to Project Admin and needs to first be enabled by StackOne (reach out to StackOne support for it to be enabled for your organization)

**Why can't I see the unified model I want to add custom unified for in the `Field Mapping` page?**\
Only pre-selected unified models have been enabled, if you would like to access another model available in our API but not visible in the custom unified fields section, reach out to our support team.

**How can I map a complex object like an array, enum or object?**\
This is currently not supported in the beta version but will come shortly with the global release of this feature.


# Integration Field Mapping
Source: https://docs.stackone.com/iam/common-guide/integration-field-mapping

Learn how to configure field mappings for specific integrations.

Once you've created a [custom unified field](/guides/field-mapping), you need to define the "mapping" for each integration you want this field to be enabled and usable for.

<Frame>
  <img alt="" />
</Frame>

Adding an integration field mapping is done via the *integration-level* mapping tab after selecting a specific custom unified field.

<Info>
  Only connectors configured and enabled on the [Connector Profiles](https://app.stackone.com/connector_profiles) page can be mapped.
</Info>

# Configuring the mapping

Although it's possible to map without using an underlying linked account, it's always advised to use a connected linked account (eg. a sandbox account) to have the most realistic view of what type of properties and fields may be available on the underlying integration.

<Frame>
  <img alt="" />
</Frame>

## Preview & Test

1. **Preview Fields:** *(optional)*
   * Select a source from the dropdown list to pull a sample set of field data.
   * Click on "Request" to preview the data.
   * Example preview JSON response:
     ```json theme={null}
     {
       "employees": [
         {
           "id": "5",
           "firstName": "Anna",
           "lastName": "Skywalker",
           "terminationDate": "2024-05-28"
         }
       ]
     }
     ```
2. **Field Mapping Steps:**
   * **Step 1:** Select the source field you want to map from the integration.
   * **Step 2:** Enter the target custom field name.
   * **Step 3:** Use the expression language syntax to point to the relevant integration field
     * Example: `$.employees.output.data.terminationDate`

***

### Tips & Tricks

#### Mapping array values

Some origin data will return a list of resources instead of a single resource (eg: all the documents instead of a specific document). In this case, you should make sure to use one of the provided default variables (eg: `id`) to find the element in the array that matches the ID.

#### Expression language

Custom unified fields can be mapped using the StackOne's expression language. This language supports JSON path syntax, JEXL expressions for more complex use cases or simple string interpolation. For more information about all the expression language capabilities please refer to the [Expression language syntax documentation](/guides/expression-language-syntax).

***

## Additional Features:

* **Typecasting:** Values will be automatically typecasted to the defined variable type when possible (eg: if the variable type is a `string` but the underlying integration returns a `number` the number will be return as a string and vice-versa).
* **Viewing Mappings:** Once an integration mapping is configured, the source will be visible directly in the integration-level mapping list:

  <Frame>
    <img alt="" />
  </Frame>

# Using a Custom Unified Field

Once you have configured an integration custom field mapping you will need to make sure the field is enabled:

<Frame>
  <img alt="" />
</Frame>

You can retrieve the data via any `GET` or `LIST` API request for the model you created the field on:

The unified custom field will be embedded in an property called `unified_custom_fields`.

<Frame>
  <img alt="" />
</Frame>

<Info>
  When using SDKs (ie: Typescript SDK) the property may be camel cased instead (ie: `unifiedCustomFields`). The SDK will not have types for the individual properties contained in this object given it is fully customizable.
</Info>


# Pagination
Source: https://docs.stackone.com/iam/common-guide/pagination

Understand cursor-based pagination in the IAM API and how to efficiently retrieve large datasets.

StackOne's <Tooltip>Unified API</Tooltip> allows paginating on API requests that return multiple records using a page cursor.

The following optional URL parameters are used for pagination:

<ParamField type="string">
  The number of records per page.
</ParamField>

<ParamField type="string">
  The `next` parameter is used to iterate through data pages.
</ParamField>

<Warning>
  It is recommended to keep the same page\_size throughout the sequence of pagination requests otherwise unexpected behaviour may occur.
</Warning>

## Sample URL

```
https://api.stackone.com/unified/hris/employees?page_size=25&next=eyJyIjphAsHHere
```

## Sample Response

In the response payload, you can find the `next` cursor. To get the next page of data send a new request with the `next` parameter set to this value.

```json theme={null}
"next":"eyJyIjphAsHHere",
"data":[
   0: [...],
   1: [...],
   ...
   24: [...],
]
```

Once the cursor reaches the end of the data list, both values become NULL.

## Page Size

By default, the `page_size` parameter is set to 25 results per page, you can over-ride this by passing in a custom page size with this parameter. If fewer records remain in the underlying connected provider than a given page\_size, you will not receive a `next`  cursor value on the next request.

For example, if you have 17 records in total, all of them will be shown on one page with `next` parameter being empty. Then you specify the `page_size` = 10, you'll get the `next` value. If you use this `next` value, you will get a stripped array of the last 7 records.

## Early Cursor return

Occasionally we have to apply custom filters or structure requests to ensure we can get data which is not returned by the native API, this can cause timeout issues where we wouldn't fill an entire page.

In this case we will return a cursor value with the incomplete page, and you can continue paginating through the data to the end of the data set. When the final record is reached on the underlying provider we will return an empty next cursor.

```json theme={null}
"next":"eyJyIjphAsHHere",
"data":[]
```


# API SDKs
Source: https://docs.stackone.com/iam/common-guide/stackone-api-sdks

Language-native libraries for StackOne Unified APIs

## Postman

StackOne maintains a Postman collection to more easily test & interact with the StackOne internal API and unified APIs:  [***Run in Postman***](https://god.gw.postman.com/run-collection/25987823-c68540f2-7aba-475e-89d2-77625c6a6424?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D25987823-c68540f2-7aba-475e-89d2-77625c6a6424%26entityType%3Dcollection%26workspaceId%3Df291b2e0-d0cb-4dc2-93c4-c2d4f581da3f)

* You can also directly Download / import the Postman collection [via our github repository](https://github.com/StackOneHQ/stackone-client-postman)

## Unified API SDKs

StackOne maintains and publishes the following SDKs:

* **Ruby** ([RubyGems](https://rubygems.org/gems/stackone_client), [GitHub](https://github.com/StackOneHQ/stackone-client-ruby))
* **Typescript** ([npm](https://www.npmjs.com/package/@stackone/stackone-client-ts), [GitHub](https://github.com/StackOneHQ/stackone-client-typescript))
* **PHP** ([Packagist](https://packagist.org/packages/stackone/client-sdk), [GitHub](https://github.com/stackoneHQ/stackone-client-php)) - Beta
* **Java** ([Maven](https://mvnrepository.com/artifact/com.stackone/stackone-client-java), [GitHub](https://github.com/StackOneHQ/stackone-client-java)) - Beta
* **C#** ([nuget](https://www.nuget.org/packages/StackOneHQ.Client), [GitHub](https://github.com/StackOneHQ/stackone-client-csharp)) - Beta

Additionally, our API Reference provides code snippets in multiple languages (JavaScript, Python, PHP, Go, Java, Ruby), making it easy to copy and test our endpoints.

## AI Tools

StackOne makes it easy for AI agents to interact with any connected SaaS via its AI Toolset:

* **Node/Typescript** ([GitHub](https://github.com/StackOneHQ/stackone-ai-node))
  * [Basic Usage](/agents/typescript/basic-usage)
* **Python** ([GitHub](https://github.com/stackoneHQ/stackone-ai-python))

Reach out to our team via your dedicated Slack channel or at [support@stackone.com](mailto:support@stackone.com) to request access to any other SDK.


# StackOne Identifiers
Source: https://docs.stackone.com/iam/common-guide/stackone-identifiers

Understand synthetic IDs and how to use them interchangeably with provider IDs across the unified API

# Understanding Synthetic IDs in Our API

We often need to combine data from multiple sources to create unified responses. For instance, consider Workday's Applications. To create a unified application with the data provided by Workday, we need to link Job Requisitions with Candidates. Here, a candidate can be associated with multiple job requisitions and vice versa. Consequently, we can't use either of these IDs to identify a specific record.

## What Are Synthetic IDs?

To address this, we've introduced the concept of synthetic IDs. These IDs do not match an ID in the underlying provider, but allow you (and us) to identify the combined resources that were used to create this unified response. You can then use these IDs across our unified API. For example, you could use a `job_id` from a listing to search for candidates matching that value.

For simplicity, all IDs provided by the API will be synthetic IDs. These IDs are easy to identify because they are prefixed with `c28xIQ`. In most cases, you'll still be able to see the underlying ID from the provider in a field prefixed by `remote_`. For example, in the case of `job_id`, the underlying ID will be in `remote_job_id`.

## Using Synthetic and Regular IDs

When it comes to writing or fetching data, both types of IDs can be used interchangeably.

### Fetching Data

For reading, let's say we have the synthetic and regular IDs:

```jsx theme={null}
{
  job_id: 'c28xIQaWQ6MQ',
  remote_id: '1'
}

```

You can make either of these calls and expect the same response:

```bash theme={null}
# Using a regular ID
curl --request GET \
--url https://api.stackone.com/unified/ats/jobs/1 \
--header 'accept: application/json'

# Using a synthetic ID
curl --request GET \
--url https://api.stackone.com/unified/ats/jobs/c28xIQaWQ6MQ \
--header 'accept: application/json'

```

This applies to any query parameters as well:

```bash theme={null}
# Using a regular ID
curl --request GET \
     --url https://api.stackone.com/unified/ats/applications?raw=false&filter[job_id]=1&page_size=25 \
     --header 'accept: application/json'

# Using a synthetic ID
curl --request GET \
     --url https://api.stackone.com/unified/ats/applications?raw=false&filter[job_id]=c28xIQaWQ6MQ&page_size=25 \
     --header 'accept: application/json'

```

### Writing Data

When it comes to writing, the behavior is similar. You can use the ID field as usual and provide either a regular ID or a synthetic ID:


# Synthetic Identifiers
Source: https://docs.stackone.com/iam/common-guide/synthetic-identifiers

Learn about synthetic identifiers in the IAM API and how StackOne normalizes IDs across providers.

StackOne's Unified API generates unique synthetic identifiers for each resource to avoid any potential clashes that may have occurred through the process of unifying data from multiple sources. These are only used within the Unified API and are not found in the underlying provider systems.

* By default, all IDs are returned as synthetic identifiers.
* All synthetic identifiers are prefixed with `c28xIQ`.
* In most cases we also provide the "remote" id from the underlying provider, identified by the `remote_` prefix.
* Both synthetic and remote identifiers can be used interchangeably within the Unified API, the result will be the same.

<Note>
  It is strongly recommended to use the synthetic identifier for ease of use and consistency.
</Note>

Here's an example response showing both StackOne and remote identifiers:

```json theme={null}
{
    "id": "c28xIQ123ABC",               // StackOne identifier for current resource
    "remote_id": "E123456",             // Provider's original identifier
    "first_name": "John",
    "last_name": "Doe",
    "department_id": "c28xIQ789XYZ",    // StackOne identifier for department
    "remote_department_id": "D789"      // Provider's department identifier
}
```

For further information see [Guides - StackOne Identifiers](/guides/stackone-identifiers)


# Using Expand and Include Parameters
Source: https://docs.stackone.com/iam/common-guide/using-expand-and-include-api-parameters

Learn how to use expand and include parameters to retrieve related data in a single API request.

## Overview

While getting familiar with <Tooltip>Unified API</Tooltip>, you want to extend API functionality. StackOne API allows joining data from different objects into one combined response.

The StackOne implementation adds advanced <Tooltip>query parameters</Tooltip>, `include` or `expand`, to obtain the required information.

## Example scenario

Let's imagine an example:

1. You've acquired a [list of your available Accounts](/platform/api-reference/accounts/list-accounts) (account `id`)

2. Then you've retrieved a [list of employees](/hris/api-reference/employees/list-employees) for a specific `x-account-id` and selected one particular employee by specifying the resource`id` in the path

3. Next you want to [get all available information of that employee](/hris/api-reference/employees/get-employee)

At this point, you're getting basic info, such as name, gender, birthday, email, etc. However, you may be missing information documented in the API reference such as `avatar_url` or additional information about the `work_location` and `employment`. This is where the `include ` and `expand` parameters become handy.

## Including optional params

`include` and `expand` reserved keywords allow retrieving additional information about the employee. As an example, the usage of `include`=`avatar_url` and `expand`=`work_location` returns a link to the employee's avatar and details of work location.

**Include**

Include is meant to return additional fields not included by default for privacy or performance reasons. For example, the `avatar_url` field may require the hosting of the underlying image, which can slow down the response unnecessarily if you do not need it.

**Expand**

Expand, on the other hand, is used to expand objects (also called `models`) for which only the ID would otherwise be given and would therefore require a call to another resource to retrieve the underlying data (such as an employee's employment or work location details )

<Frame>
  <img alt="Expand and Include API Parameters" />
</Frame>

## Supported parameter-value mapping

The supported include and expand parameters are specific to the unified API endpoints. They can be seen within the individual endpoints in the API references (e.g., [List Employees](/hris/api-reference/employees/list-employees))


# Using Postman with StackOne API
Source: https://docs.stackone.com/iam/common-guide/using-postman

Learn how to use Postman to test and explore the StackOne API.

<Warning>
  **Prerequisites**

  Before testing with Postman, set up an integration and link an account following the [Getting Started](/guides/introduction) guide.
</Warning>

## Get the collection

The StackOne public Postman workspace has a pre-configured collection for the Unified APIs (HRIS, ATS, CRM, and more). Fork it into your own workspace to get started:

<a href="https://www.postman.com/stackonehq/stackone-public/collection/8d04033a-b6b1-4c91-8235-729f5c46123a">
  <img alt="Run in Postman" />
</a>

The collection has Basic Auth configured with `{{apiKey}}` as the username, and an `x-account-id` header set to `{{accountId}}`.

## Set up your environment

<Steps>
  <Step title="Create an environment">
    In Postman, click the **Environments** icon in the left sidebar, then **+** to create a new environment. Name it "StackOne" (or similar).
  </Step>

  <Step title="Add your credentials">
    Add these variables to the environment:

    | Variable    | Value                                                                                                        |
    | ----------- | ------------------------------------------------------------------------------------------------------------ |
    | `apiKey`    | Your StackOne API key — find it in the [dashboard](https://app.stackone.com) under **Settings → API Keys**   |
    | `accountId` | The linked account ID you want to target — visible in the [Accounts page](https://app.stackone.com/accounts) |
  </Step>

  <Step title="Select the environment">
    Select your environment from the dropdown in the top-right corner of Postman before sending any request.
  </Step>
</Steps>

## Make a request

With your environment active, open any request in the collection and click **Send**. The `{{apiKey}}` and `{{accountId}}` variables are resolved automatically from your environment.

<Tip>
  Start with **GET /accounts** to confirm your API key is working — it returns all linked accounts for your project.
</Tip>

## Troubleshooting

**`{"error":"Invalid authentication token"}`** — Your `apiKey` variable is missing or incorrect. Check that the right environment is selected and the value matches your key from the dashboard.


# Using the Passthrough Query Parameters
Source: https://docs.stackone.com/iam/common-guide/using-the-passthrough-query-parameters

Learn how to use passthrough query parameters to send custom parameters directly to the underlying provider.

Passthrough query parameters let you inject custom parameters directly into underlying provider APIs. This gives you access to provider-specific features without waiting for Unified API support.

## What is a Passthrough Query Parameter?

When invoking our unified API, you can provide query parameters to customize the API response. A passthrough query parameter is a special parameter that can be included in your API request, which will be directly passed on to the underlying provider API.

## How Does it Work?

The passthrough query mechanism uses a specific parameter pattern – the keyword "proxy" followed by brackets. If any parameter in this format is present in the API call, it will be extracted and passed as a query parameter to the underlying provider API.

**Pattern**: `proxy[custom-query-name]=custom-query-value`

* `custom-query-name`: The name of the custom query parameter.
* `custom-query-value`: The value assigned to the custom query parameter.

<Note>
  Note:

  More advanced filters are also supported: `proxy[filter[eq][age]]=25`.
</Note>

<Warning>
  Using the `proxy` passthrough parameter to set page-related parameter (eg: page limits, offsets, size etc.) may result in unexpected behaviour as it will override the values that StackOne sends with every provider request
</Warning>

## Example

Suppose you use the unified API to get all candidates for <Tooltip>ATS</Tooltip> category. This API already supports some optional filters, such as the `page_size` query parameter. If you know that one of the underlying providers supports a specific filter called `my-custom-filter`, you can use the passthrough query parameter to include this in your request, and it will be used when calling the provider API.

API Request: `https://api.stackone.com/unified/ats/candidates?proxy[my-custom-filter]=123`

With the above request, while the `page_size=20` parameter will be interpreted by our unified API, the `proxy[my-custom-filter]=123` will be extracted and passed directly to the underlying provider API as `my-custom-filter=123`.

<Frame>
  <img alt="Proxy Parameter Mechanism" />
</Frame>

Sorting candidates by the First Name for [TeamTailor API](https://docs.teamtailor.com/):

`https://api.stackone.com/unified/ats/candidates?page_size=20&proxy[sort]=first_name`

<Frame>
  <img alt="TeamTailor sort filter parameter" />
</Frame>

## Benefits

1. **Flexibility**: Developers can maximize the use of underlying provider APIs by tapping into specific features or filters that the unified API might not support directly.
2. **Future-Proofing**: As underlying provider APIs evolve and introduce new query parameters, developers can start using those without waiting for the unified API to offer built-in support.

## Caveats

Although it's great to have the flexibility to use all the filters that the underlying provider supports, you should consider the following caveats when using this functionality:

* These requests will not benefit from the unified vision, so a specific custom request with proxy parameters will not likely be supported between different providers;
* We often need to use some filters in the underlying requests to support the unified models. To keep the response data as unified as possible between different providers, if you passthrough query parameters that are already being used by default, the values that you pass will have less precedence and will not be overridden;
* The filters might be removed or deprecated by the underlying provider without the intervention of the StackOne team, which might break your custom use cases without notice.

## Conclusion

Passthrough query parameters give you direct access to provider-specific features and filters. Keep the tradeoffs in mind when using this mechanism.


# Error Codes and Troubleshooting
Source: https://docs.stackone.com/iam/error-codes-and-troubleshooting

IAM API error codes and troubleshooting guide

Encountering errors while interacting with APIs is a common occurrence. Although the StackOne Unified API will try to remediate issues automatically, it is important to understand what each error code signifies.

This guide lists the error codes you may encounter while using the IAM API, the possible reasons behind these errors, and steps for resolution.

***

<Snippet />

***

## Provider Errors

When the underlying provider API returns an error, the StackOne Unified API includes any data returned by the provider in the `provider_errors` array:

```json theme={null}
{
  "statusCode": 404,
  "message": "Resource not found",
  "provider_errors": [
    {
      "status": 404,
      "url": "/api/v1/users/250",
      "raw": { "error": "User with id 250 does not exist" }
    }
  ]
}
```

<Tip>
  Always check the `provider_errors` array for additional context from the upstream provider. This can help diagnose issues specific to the connected system.
</Tip>

***

## Getting Help

For any unresolved issues or further assistance, contact our support team via your dedicated Slack channel or at [support@stackone.com](mailto:support@stackone.com).

<CardGroup>
  <Card title="Status Page" icon="signal" href="https://status.stackone.com">
    Check system status and incidents
  </Card>

  <Card title="Request Tester" icon="flask" href="/iam/request-tester">
    Debug IAM requests directly in the dashboard
  </Card>

  <Card title="Request Logs" icon="scroll" href="/guides/request-logs">
    View detailed request history
  </Card>

  <Card title="IAM Integration Errors" icon="bug" href="/iam/integration-errors">
    Provider-specific IAM errors
  </Card>

  <Card title="AI Error Explainer" icon="robot" href="/guides/ai-features#error-explainer">
    Get AI-powered error resolution steps
  </Card>
</CardGroup>


# Making your first request
Source: https://docs.stackone.com/iam/first-request

Make your first IAM API request to list users from a connected identity provider

This guide walks you through making your first API request to retrieve data from a linked account.

## Prerequisites

1. [**API Key created in StackOne Dashboard**](/guides/api-keys) and copied to a secure location

2. [**Basic Authentication Setup**](/basic-authentication-with-stackone-api) - Learn how to properly authenticate with StackOne API using your API key

3. Required provider integration enabled

4. Account linked successfully

5. (Optional) Use an [SDK or Postman](/guides/stackone-api-sdks)

## Getting Account ID

<Note>
  **Authentication**: When using `curl -u "$API_KEY:"`, encoding is handled automatically. When setting the `Authorization` header manually, you must base64 encode your API key first. See the [Basic Authentication Guide](/basic-authentication-with-stackone-api) for details.
</Note>

1. List your linked accounts to find the account ID:

```bash theme={null}
curl --request GET \
     --url https://api.stackone.com/accounts \
     --header 'accept: application/json' \
     --header 'authorization: Basic {base64_encoded_api_key}'
```

2. From the response, copy the `id` value for your desired provider account.

<Tip>
  Filter by provider using the `providers` query parameter:

  ```bash theme={null}
  curl --request GET \
       --url 'https://api.stackone.com/accounts?providers={provider_name}' \
       --header 'accept: application/json' \
       --header 'authorization: Basic {base64_encoded_api_key}'
  ```
</Tip>

## Making Your First Request

Now you're ready to make your first IAM API call. Let's list the users from the connected identity provider:

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl --request GET \
      --url 'https://api.stackone.com/unified/iam/users' \
      --header 'accept: application/json' \
      --header 'authorization: Basic {base64_encoded_api_key}' \
      --header 'x-account-id: {account_id}'
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { StackOne } from "@stackone/stackone-client-ts";

    const client = new StackOne({ apiKey: "YOUR_API_KEY" });

    const response = await client.iam.listUsers({
      xAccountId: "your-account-id"
    });

    console.log(response.users);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from stackone_client import StackOne

    client = StackOne(api_key="YOUR_API_KEY")

    response = client.iam.list_users(
        x_account_id="your-account-id"
    )

    print(response.users)
    ```
  </Tab>
</Tabs>

### Example Response

```json theme={null}
{
  "data": [
    {
      "id": "user_123",
      "remote_id": "abc123",
      "primary_email_address": "jane.doe@company.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "username": "jdoe",
      "status": "active",
      "is_bot_user": false,
      "last_login_at": "2024-01-15T10:30:00Z"
    }
  ]
}
```

## Next Steps

<CardGroup>
  <Card title="List Roles" icon="user-shield" href="/iam/api-reference/roles/list-roles">
    Get roles defined in the identity provider
  </Card>

  <Card title="List Groups" icon="users" href="/iam/api-reference/groups/list-groups">
    Retrieve user groups and memberships
  </Card>

  <Card title="Pagination" icon="arrow-right" href="/iam/common-guide/pagination">
    Handle large result sets efficiently
  </Card>

  <Card title="Webhooks" icon="bell" href="/guides/webhooks">
    Get notified when users change
  </Card>
</CardGroup>

## References

* [Basic Authentication with API Keys](/basic-authentication-with-stackone-api)
* [List Accounts](/platform/api-reference/accounts/list-accounts)
* [Libraries & SDKs](/guides/stackone-api-sdks)
* [Connector Profiles](https://app.stackone.com/connector_profiles)


# Unified IAM API
Source: https://docs.stackone.com/iam/introduction

Unified IAM API for identity and access management across providers, with consistent data models for users, roles, groups, organizations, permissions, and credentials.

## What is a Unified API?

A **unified API** provides a single, standardized interface to interact with multiple third-party providers. Instead of learning each provider's unique API format, authentication scheme, and data model, you write code once, and StackOne handles the differences.

**What StackOne normalizes:**

* **Data models** – Consistent field names and structures across providers (e.g., `files` in Google Drive, SharePoint, and Dropbox all return the same schema; `users` in Google Workspace, Okta, and 1Password all return the same schema)
* **Authentication** – OAuth, API keys, and tokens are managed per-provider; you just pass an `x-account-id` header
* **Pagination** – Cursor-based pagination works the same regardless of whether the provider uses offsets, pages, or cursors
* **Error formats** – Standardized error responses with provider-specific details when available

<Tip>
  **Building AI agents?** Use the [MCP Server](/mcp/quickstart), an [AI Toolset SDK](/agents/typescript/introduction), or the [Actions API (RPC)](/platform/api-reference/actions/make-an-rpc-call-to-an-action) instead — same data, optimized for LLM tool calling.
</Tip>

## Entity Model

The IAM API is built around six core entities.

```mermaid theme={null}
erDiagram
    IamUser ||--o{ IamRole : "has roles"
    IamUser ||--o{ IamGroup : "member of"
    IamUser ||--o{ IamPermission : "direct permissions"

    IamGroup ||--o{ IamRole : "has roles"
    IamGroup ||--o{ IamUser : "users (expandable)"
    IamGroup }o--o| IamGroup : "parent"
    IamGroup }o--o| IamOrganization : "belongs to"

    IamRole ||--o{ IamPermission : "grants"
    IamRole }o--o| IamRoleScope : "scope"

    IamPermission ||--o{ IamPermissionScope : "scopes"

    IamOrganization ||--o{ IamUser : "users"
    IamOrganization ||--o{ IamGroup : "groups"

    IamUser {
        string id
        string remote_id
        string primary_email_address
        string first_name
        string last_name
        string name
        string username
        boolean is_bot_user
        enum status
        array roles
        array groups
        array permissions
        datetime last_active_at
        datetime last_login_at
        datetime created_at
        datetime updated_at
        array multi_factor_enabled
        object avatar
    }

    IamRole {
        string id
        string remote_id
        string name
        string description
        enum type
        array permissions
        object scope
        datetime created_at
        datetime updated_at
    }

    IamGroup {
        string id
        string remote_id
        string name
        string description
        enum type
        array roles
        string parent_id
        string remote_parent_id
        array child_group_ids
        string organization_id
        array users
        datetime created_at
        datetime updated_at
    }

    IamOrganization {
        string id
        string remote_id
        string name
        datetime created_at
        datetime updated_at
    }

    IamPermission {
        string id
        string remote_id
        string name
        string description
        enum type
        array scopes
        datetime created_at
        datetime updated_at
    }

    IamPermissionScope {
        string resource_type
        string resource_id
    }

    IamRoleScope {
        string resource_type
        string resource_id
    }
```

<Note>
  IamCredentials is not included in the diagram above. It is a snapshot of the current connection's auth state, not a stored identity object. It carries a user reference when the credential corresponds to a known principal (such as an OAuth user or named service account).
</Note>

| Entity              | Description                                                                                                                                                                                                                                            |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **IamUser**         | An individual with access to the provider. Carries profile fields, activity timestamps, MFA status, and expandable collections of roles, groups, and direct permissions.                                                                               |
| **IamRole**         | A named set of permissions. Roles can be scoped to a specific resource type and ID (`scope`), making them applicable to a particular group, organization, or resource.                                                                                 |
| **IamGroup**        | A collection of users. Groups can nest via `parent_id` and `child_group_ids`, belong to an organization, and carry their own role assignments. Expand `users` to get group members.                                                                    |
| **IamOrganization** | A top-level tenant or workspace. Groups and users are linked to an organization via `organization_id` and filter parameters.                                                                                                                           |
| **IamPermission**   | A specific action type scoped to one or more resource types and optional resource IDs. Targets live on `scopes` (`IamPermissionScope[]`). See [Permission types](#permission-types) for valid `type` values.                                           |
| **IamCredentials**  | The authenticated connection making the request. Returned by `GET /unified/iam/me`. Includes a name, auth type, granted scopes, effective permissions, last-used timestamp, and a user reference when the credential corresponds to a known principal. |

### Permission and scope model

`IamPermission` has a `type` (the action) and a `scopes` array. Each scope entry has a `resource_type` (e.g. `file`, `channel`, `user`) and an optional `resource_id`. When `resource_id` is absent, the permission applies to all resources of that type.

Roles carry the same scoping via `IamRoleScope` on the role itself, allowing a role to be valid only within a specific organizational context.

## Endpoints

| Method | Path                              | Action                        | Description                                                                                                                                             |
| ------ | --------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/unified/iam/users`              | `unified_list_users`          | List users (see [User filters](#user-filters))                                                                                                          |
| GET    | `/unified/iam/users/{id}`         | `unified_get_user`            | Get user by ID                                                                                                                                          |
| PATCH  | `/unified/iam/users/{id}`         | `iam_update_user`             | Update user                                                                                                                                             |
| DELETE | `/unified/iam/users/{id}`         | `iam_delete_user`             | Delete user                                                                                                                                             |
| GET    | `/unified/iam/roles`              | `unified_list_roles`          | List roles                                                                                                                                              |
| GET    | `/unified/iam/roles/{id}`         | `unified_get_role`            | Get role by ID                                                                                                                                          |
| GET    | `/unified/iam/groups`             | `unified_list_groups`         | List groups                                                                                                                                             |
| GET    | `/unified/iam/groups/{id}`        | `unified_get_group`           | Get group by ID                                                                                                                                         |
| GET    | `/unified/iam/organizations`      | `unified_list_organizations`  | List organizations                                                                                                                                      |
| GET    | `/unified/iam/organizations/{id}` | `unified_get_organization`    | Get organization by ID                                                                                                                                  |
| GET    | `/unified/iam/me`                 | `unified_get_me`              | Get current connection credentials                                                                                                                      |
| GET    | `/unified/iam/resource_types`     | `unified_list_resource_types` | List resource type identifiers supported by this connector (see [Resource types](#resource-types))                                                      |
| GET    | `/unified/iam/resource_users`     | `unified_list_resource_users` | List users with access to a specific resource. Requires `resource_type` and `resource_id` (see [Listing users by resource](#listing-users-by-resource)) |

## Permission types

`IamPermission.type` is one of the values below. The OAS admits the full set; providers expose only the permission types that map to their model.

| Value            | Description                               |
| ---------------- | ----------------------------------------- |
| `read`           | Read access                               |
| `read_write`     | Read and write access                     |
| `write`          | Write access                              |
| `comment`        | Comment / annotate                        |
| `create`         | Create new resources                      |
| `edit`           | Edit existing resources                   |
| `approve`        | Approval / workflow rights                |
| `delete`         | Delete access                             |
| `use`            | Use / execute (e.g. run app, use license) |
| `export`         | Export / download                         |
| `unmapped_value` | Provider value did not map to the enum    |
| `null`           | Provider did not provide a value          |

## User filters

`GET /unified/iam/users` accepts the following keys on the `filter` query object. Filter support varies per connector; passing a filter key the connector does not support returns a 400.

| Filter                   | Type               | Notes                       |
| ------------------------ | ------------------ | --------------------------- |
| `filter.updated_after`   | string (date-time) | Supported by all connectors |
| `filter.email`           | string             | Some connectors             |
| `filter.group_id`        | string             | Some connectors             |
| `filter.role_id`         | string             | Some connectors             |
| `filter.organization_id` | string             | Some connectors             |

## Resource types

`GET /unified/iam/resource_types` returns the resource type identifiers a connected provider supports for resource-scoped queries. The response shape is `{ data: string[] }`; values are connector-defined, not a fixed enum.

| Connector        | Example response              |
| ---------------- | ----------------------------- |
| Google Drive     | `["file", "folder", "drive"]` |
| Google Directory | `["group"]`                   |
| Slack            | `["channel", "workspace"]`    |

Use these values as the `resource_type` query parameter on `GET /unified/iam/resource_users`.

The `type` field on an embedded `IamResource` is declared as `oneOf: [string, IamResourceTypeEnum]` in the OAS. Falcon connectors emit a plain string from the connector-defined set returned by this endpoint (e.g. `"file"`, `"channel"`, `"group"`). Legacy V2 connectors emit the `{ value, source_value }` envelope where `value` is from the fixed `IamResourceTypeEnum` set. Parse both shapes when consuming the field.

## Listing users by resource

`GET /unified/iam/resource_users` returns users with access to a specific resource, including their resource-scoped roles. Same response shape as `IamUser`.

**Required query parameters:**

* `resource_type` — one of the values returned by `GET /unified/iam/resource_types` for the connected provider.
* `resource_id` — the raw provider remote\_id of the resource. **Not** a StackOne-encoded id from a list endpoint. Pass the provider's native id (e.g. a Drive file id, Slack channel id, group remote\_id).

Standard pagination, `fields`, and `expand` apply as on the other list endpoints.

## StackOne SDKs & OpenAPI Specification

<p>Use our official SDKs for faster integration. Build with language-native libraries. Full list [here](/guides/stackone-api-sdks).</p>

<CardGroup>
  <Card title="OpenAPI Specification" icon="link" href="https://api.eu1.stackone.com/oas/iam.json" />

  <Card title="Popular SDKs" icon="download">
    [Node.js](https://www.npmjs.com/package/@stackone/stackone-client-ts)
    [Java (JVM)](https://mvnrepository.com/artifact/com.stackone/stackone-client-java)
    [PHP](https://packagist.org/packages/stackone/client-sdk)
    [Ruby](https://rubygems.org/gems/stackone_client)
  </Card>
</CardGroup>


# Request Tester
Source: https://docs.stackone.com/iam/request-tester

Test IAM API requests directly against linked accounts to verify connectivity and debug issues.

The Request Tester lets you execute HTTP requests against any linked account directly from the dashboard. Use it to verify connections, test specific endpoints, and troubleshoot integration issues.

<Note>
  **Unified API Testing**: The Request Tester is the recommended way to test IAM API endpoints against specific accounts. It provides direct access to the API without requiring code or external tools.
</Note>

## Accessing the Request Tester

<Steps>
  <Step title="Navigate to Accounts">
    Go to [Accounts](https://app.stackone.com/accounts) in the StackOne dashboard.
  </Step>

  <Step title="Find your account">
    Locate the linked account you want to test.
  </Step>

  <Step title="Open Request Tester">
    Click the ellipsis menu (⋯) on the account row and select **Request Tester**.
  </Step>
</Steps>

<Tip>
  You can also access the Request Tester from the account detail page by clicking the **Test Request** button.
</Tip>

## Using the Request Tester

### Select an Endpoint

Choose from available IAM endpoints:

| Category | Example Endpoints                                                                             |
| -------- | --------------------------------------------------------------------------------------------- |
| **IAM**  | List Users, Get User, List Groups, Get Group, List Roles, Get Role, List Policies, Get Policy |

### Configure Parameters

Depending on the endpoint, you can configure:

* **Path parameters** – Required IDs like `user_id` or `group_id`
* **Query parameters** – Pagination, filtering, and expansion options
* **Request body** – For POST/PUT/PATCH requests

<AccordionGroup>
  <Accordion title="Common query parameters">
    | Parameter       | Description                                             |
    | --------------- | ------------------------------------------------------- |
    | `page_size`     | Number of results per page (default varies by endpoint) |
    | `next`          | Pagination cursor for fetching next page                |
    | `updated_after` | Filter by modification date                             |
    | `expand`        | Include related resources in response                   |
  </Accordion>

  <Accordion title="Using the expand parameter">
    Some endpoints support expanding related data. For example, when listing users you might expand `groups` or `roles` to include those details inline.

    See [Using Expand and Include Parameters](/guides/using-expand-and-include-api-parameters) for details.
  </Accordion>
</AccordionGroup>

### Execute and Inspect

Click **Send Request** to execute. The response panel shows:

* **Status code** – HTTP status (200, 400, 404, etc.)
* **Response body** – JSON data returned by the API
* **Response headers** – Including rate limit information
* **Timing** – Request duration

## Troubleshooting with Request Tester

The Request Tester is particularly useful for debugging:

<AccordionGroup>
  <Accordion title="Connection issues">
    If an account shows an error status, use the Request Tester to execute a simple request (like listing users). The response will reveal:

    * Authentication failures (401/403)
    * Token expiration
    * Permission issues
    * Provider API errors
  </Accordion>

  <Accordion title="Missing data">
    When expected data isn't appearing:

    1. Test the specific endpoint directly
    2. Check if the data exists in the source system
    3. Review field mappings in the response
    4. Verify scopes/permissions in the integration configuration
  </Accordion>

  <Accordion title="Pagination problems">
    To debug pagination:

    1. Make an initial request with a small `page_size`
    2. Copy the `next` cursor from the response
    3. Make a follow-up request with that cursor
    4. Verify data continuity between pages
  </Accordion>

  <Accordion title="Slow responses">
    If requests are slow:

    * Check the response timing in the panel
    * Try smaller `page_size` values
    * Review [Request Logs](/guides/request-logs) for detailed timing breakdown
  </Accordion>
</AccordionGroup>

## Request Tester vs AI Playground

| Feature              | Request Tester          | AI Playground                |
| -------------------- | ----------------------- | ---------------------------- |
| **Purpose**          | Direct API testing      | Natural language exploration |
| **Best for**         | Debugging, verification | Discovery, prototyping       |
| **Input**            | Structured parameters   | Natural language prompts     |
| **Output**           | Raw API response        | AI-interpreted results       |
| **Unified APIs**     | **Recommended**         | Supported                    |
| **Provider actions** | Supported               | Supported                    |

<Tip>
  Use the **Request Tester** when you need precise control over parameters and want to see exact API responses. Use the **AI Playground** when exploring capabilities or testing complex multi-step workflows.
</Tip>

## Related

<CardGroup>
  <Card title="Accounts" icon="users" href="/guides/accounts-section">
    Manage linked accounts
  </Card>

  <Card title="Request Logs" icon="scroll" href="/guides/request-logs">
    View detailed request history
  </Card>

  <Card title="Error Codes" icon="triangle-exclamation" href="/guides/unified-api-error-codes-and-troubleshooting-guide">
    Understand error responses
  </Card>

  <Card title="AI Playground" icon="message" href="/guides/playground">
    Test with natural language
  </Card>
</CardGroup>


# StackOne 101
Source: https://docs.stackone.com/index

Connect your AI agents to 10,000+ actions across hundreds of SaaS integrations.

<Frame>
  <img alt="StackOne connects AI agents to SaaS systems" />
</Frame>

StackOne is the **AI Integration Gateway**. Connect your AI agents to any SaaS system, yours or your users', with any AI framework or protocol. One gateway. Hundreds of systems. Thousands of actions.

***

## Get Started

<CardGroup>
  <Card title="5-Minute Quickstart" icon="bolt" href="/guides/introduction">
    Get your first integration running with step-by-step instructions
  </Card>

  <Card title="Browse Available Connectors" icon="grid-2" href="/connectors/introduction">
    Explore 200+ supported providers: Salesforce, Workday, Slack, and more
  </Card>
</CardGroup>

## Key Concepts

Before diving in, here are the core building blocks you'll work with:

### Actions

An **Action** is an operation your agent can perform. It's the core unit of work in StackOne.

| Type                 | Description                                                       | Example                                         |
| -------------------- | ----------------------------------------------------------------- | ----------------------------------------------- |
| **Standard Actions** | Provider-specific operations mapping directly to a provider's API | `salesforce_get_contact`, `gmail_list_messages` |
| **Unified Actions**  | Normalized operations with consistent schemas across providers    | `iam_list_users`, `documents_list_files`        |

<Note>
  StackOne provides **10,000+ actions** across all integrations, plus webhooks to receive events from connected systems.
</Note>

<Card title="Connectors" icon="compass" href="/guides/explore-connectors">
  Browse and test all available connector actions in the dashboard
</Card>

### Linked Accounts

A **Linked Account** represents one end-user's authenticated connection to one provider. When your customer connects their Salesforce, Slack, or any other system through the [Integration Hub](/guides/embedding-stackone-hub), StackOne creates a linked account.

| Field             | Description                     | Example              |
| ----------------- | ------------------------------- | -------------------- |
| `account_id`      | Unique identifier for API calls | `acme-corp-bamboohr` |
| `origin_owner_id` | End-user's ID in your system    | `cust_12345`         |
| `provider`        | The connected SaaS system       | `bamboohr`           |

<Card title="Connect Tools Overview" icon="link" href="/guides/connect-tools-overview">
  Learn about tools for connecting end-user accounts
</Card>

### Unified Authentication

One API key authenticates your app. One header routes to the right end-user:

```bash theme={null}
Authorization: Basic {base64_encoded_api_key}
x-account-id: {customer_account_id}
```

No OAuth token refresh logic. No per-provider credential management. Consistent auth across 200+ providers.

***

## The Request Flow

When your agent calls an action, here's what happens behind the scenes:

<Frame>
  <img alt="Request flow diagram" />
</Frame>

1. **Your agent calls an action** with `account_id`, scoping all operations to that end-user's connection
2. **StackOne authenticates** with the provider using stored credentials
3. **StackOne transforms** the request to the provider's API format
4. **Provider returns** raw, provider-specific data
5. **StackOne normalizes** the response for the protocol/SDK being used
6. **Your agent receives** well-scoped data optimized for the use-case at hand

**What StackOne handles:** OAuth token refresh, rate limiting, retry logic, schema normalization, error handling, and audit logging.

***

## Connect Your Agent

<CardGroup>
  <Card title="MCP Server" href="/mcp/quickstart">
    <img alt="MCP Server diagram" />

    Native tool calling via Model Context Protocol for Claude, Cursor, n8n, and any MCP-compatible client.
  </Card>

  <Card title="A2A Protocol" href="/a2a/introduction">
    <img alt="A2A Protocol diagram" />

    Agent-to-Agent communication for orchestrating complex multi-agent workflows.
  </Card>

  <Card title="AI Toolset (SDK)" href="/agents/typescript/introduction">
    <img alt="AI Toolset diagram" />

    Python and TypeScript libraries with built-in tool definitions for LangChain, CrewAI, Vercel AI.
  </Card>
</CardGroup>

<Card title="Compare Agent Protocols" icon="scale-balanced" href="/guides/calling-stackone-actions">
  Not sure which to choose? See detailed comparison with code examples.
</Card>

## Build with APIs

<CardGroup>
  <Card title="Actions API" href="/api/execute-actions">
    <img alt="Actions API diagram" />

    **Execute any of 10,000+ actions** via `POST /actions/rpc`. The same layer that powers MCP and AI Toolset.
  </Card>

  <Card title="Platform API" href="/api/platform-overview#manage-accounts">
    <img alt="Platform API" />

    Manage linked accounts, sessions, and connectors
  </Card>
</CardGroup>

<Accordion title="Unified APIs for cross-provider operations">
  Unified APIs provide consistent REST endpoints when you need the same operation across multiple providers. Useful for building provider-agnostic backends.

  <CardGroup>
    <Card title="Documents" icon="folder" href="/documents/introduction">
      `GET /documents/files` works the same for Google Drive, SharePoint, Dropbox, Box
    </Card>

    <Card title="IAM" icon="users" href="/iam/introduction">
      `GET /iam/users` returns consistent user data from Okta, Azure AD, Google Workspace
    </Card>
  </CardGroup>

  <Info>
    **Legacy Unified APIs:** HRIS and ATS unified endpoints are still available for existing integrations. See the [HRIS API Reference](/hris/api-reference/employees/list-employees) and [ATS API Reference](/ats/api-reference/jobs/list-jobs) for documentation. For new implementations, we recommend using the [Actions API](/api/execute-actions) for greater flexibility.
  </Info>

  <Tip>
    **Actions API vs Unified API:** Use Actions API when you need provider-specific features or want dynamic tool discovery. Use Unified APIs when building traditional REST integrations that must work identically across providers.
  </Tip>
</Accordion>

***

## Organization & Projects

**Organization** is your company's StackOne account. It contains:

* All team members and their roles
* Billing and subscription details
* All projects within your company

**Project** is an isolated workspace within your organization. Each project has:

* Its own API keys (credentials don't cross projects)
* Its own integrations and configurations
* Its own linked accounts (end-user connections)
* Regional data residency settings (US, EU)

<Frame>
  <img alt="Organization and Project hierarchy" />
</Frame>

**Common project strategies:**

| Strategy                | Example                        | Use Case                               |
| ----------------------- | ------------------------------ | -------------------------------------- |
| Environment isolation   | `dev`, `staging`, `production` | Separate test data from real end-users |
| Regional data isolation | `us-prod`, `eu-prod`           | GDPR compliance, data residency        |
| Team separation         | `team-a-sandbox`               | Temporary projects for experimentation |

<Tip>
  Start with a single project for evaluation. You can then create additional projects if needed for production with appropriate regional settings.
</Tip>

## Dashboard & Setup

<CardGroup>
  <Card title="Connectors" href="/guides/explore-connectors">
    <img alt="Connectors" />

    Browse 10,000+ actions across all providers
  </Card>

  <Card title="Creating Connector Profiles" href="/guides/connector-profiles">
    <img alt="Connector Profiles" />

    Enable Connectors by selecting and configuring authentication options
  </Card>

  <Card title="Connecting Accounts" href="/guides/connect-tools-overview">
    <img alt="Integration Hub" />

    Embed the connection flow for end-user onboarding
  </Card>

  <Card title="AI Playground" href="https://app.stackone.com/playground">
    <img alt="AI Playground" />

    Test actions with natural language and see real responses
  </Card>
</CardGroup>

## Build Custom Connectors

<CardGroup>
  <Card title="Connector Engine" icon="wrench" href="/guides/connector-engine/introduction">
    Build and deploy custom connectors with the StackOne CLI
  </Card>

  <Card title="StackOne Agent" icon="robot" href="/guides/connector-engine/stackone-agent">
    AI-assisted connector development
  </Card>
</CardGroup>


# Overview
Source: https://docs.stackone.com/integration-guides/accounting/overview



Most API integrations work without additional configuration using the standard StackOne API [connector configuration](/guides/embedding-stackone-hub). See our standard [connector guides](https://hub.stackone.com/integrations) for setting up a customer account.

For some providers additional setup is required to allow them to communicate with the StackOne platform or to enable new features to the existing integration and workflows beyond the scope of our standard integration offerings.&#x20;

The customer may also be presented with further configuration options to setup the integration to suit their particular environment. Depending on the integration they may also be expected see changes on their front end-use of the underlying systems.

These guides are usually optional and are only required for specific purposes.


# Xero Accounting Integration
Source: https://docs.stackone.com/integration-guides/accounting/xero



Before setting up the Xero integration, you need to create a new OAuth app in the [Xero Developer Portal](https://developer.xero.com/).

<Warning>
  Ensure that you have administrative access to your Xero organization and the ability to create apps in the Xero Developer Portal.
</Warning>

## Create and Configure a Xero OAuth App

<Steps>
  <Step title="Log in to Xero Developer Portal">
    Navigate to the [Xero Developer Portal](https://developer.xero.com/) and log in with your Xero account credentials.

    If you don't have a developer account, you can create one for free.
  </Step>

  <Step title="Create a New App">
    Once logged in, click **My Apps** in the top navigation, then click **New app**.
  </Step>

  <Step title="Configure App Details">
    Fill in your app details:

    * **App name**: Choose a descriptive name for your integration
    * **Integration type**: Web app
    * **Company or application URL**: Your company or product website URL
    * **Redirect URI**: Enter `https://api.stackone.com/connect/oauth2/xero/callback`

    Agree to the terms and conditions and click **Create app**

    <Warning>
      The redirect URI must be exactly `https://api.stackone.com/connect/oauth2/xero/callback` for the StackOne integration to work properly.
    </Warning>
  </Step>

  <Step title="Obtain Client Credentials">
    After creating your app, you should be redirected to **App details**.

    In the left hand menu, navigate to **Configuration**:

    * **Client ID**: Copy existing value.
    * **Client Secret**: Click "Generate a secret" to create a client secret.

    <Warning>
      Store your client secret securely. You won't be able to view it again after leaving the page. If you lose it, you'll need to generate a new one.
    </Warning>

    **Copy** and securely store both values as you'll need them for the StackOne integration configuration.
  </Step>
</Steps>

## Enable the StackOne Xero Integration

<Steps>
  <Step title="Enable the Integration">
    1. Go to the StackOne app > [Connector Profiles](https://app.stackone.com/connector_profiles).
    2. Navigate to **Accounting**.
    3. Find **Xero** and click **+** .
  </Step>

  <Step title="Setup the Integration">
    Enter the following details

    * **Client ID**: The Client ID of the Xero app (from previous steps).
    * **Client Secret**: The Client Secret of the Xero app (from previous steps).
    * **Application Scopes** (optional): The scopes you want the application to use (or if left blank, placeholder scopes will be used). [Xero Scopes](https://developer.xero.com/documentation/guides/oauth2/scopes/)

    Click **Save Changes**.
  </Step>

  <Step title="Integration Enabled">
    The integration is now enabled and your customers will now be able to connect their accounts. See the following for more information:

    * [Generate an Auth Link](https://docs.stackone.com/guides/auth-link)
  </Step>
</Steps>

<br />

Congratulations, you're all set!


# Bullhorn Assessment or Background Check Custom Tab Integration
Source: https://docs.stackone.com/integration-guides/ats/bullhorn-assessment-or-background-check-custom-tab-integration

To set up, activate and use the Bullhorn custom tab for the assessments and background checks integration with StackOne.

## Overview

StackOne allows you to integrate with Bullhorn for Assessment and Background Check to receive webhook notifications whenever a
recruiter sends the test to a candidate, update the test result, and see the result on the candidate profile in Bullhorn.
This guide covers how you can set up custom tabs in Bullhorn and integrate with StackOne.

## Partnership Requirements

No formal partnership is required to configure the Bullhorn custom tab for Assessment & Background Check, however you must have administrative privileges for your Bullhorn account.

## Provider Side Setup

<Steps>
  <Step title="Access View Layout">
    Log in to Bullhorn and click the **Menu** button.

    <Frame>
      <img alt="Bullhorn Menu" />
    </Frame>

    Click the **Admin** button.

    <Frame>
      <img alt="Admin Button" />
    </Frame>

    Click **View Layout**.

    <Frame>
      <img alt="View Layout" />
    </Frame>

    Select the `Candidate` entity from the Field Map Entity dropdown menu.

    <Frame>
      <img alt="Candidate Entity" />
    </Frame>
  </Step>

  <Step title="Add a new Custom Tab">
    Navigate to the **Custom Tab**.

    <Frame>
      <img alt="Custom Tab Button" />
    </Frame>

    Click the **Add New** button and enter the required information in the fields:

    * **Name:** The name of the tab can be any text, e.g. `Assessments` or `Background Checks`
    * **Enabled:** Tick this box to enable the tab
    * **URL:** Enter the endpoint URL along with the query parameter: `externalTriggerToken`

    ```plaintext theme={null}
    https://api.stackone.com/external-trigger/bullhorn_ats?externalTriggerToken=<your-external-trigger-token>
    ```

    <Info>
      The endpoint URL must include the `externalTriggerToken` query parameter, which you will receive from the StackOne Connector Hub. This token verifies requests from Bullhorn for the specific account.
    </Info>

    <Note>
      To obtain the **External Trigger Token**, please follow these steps:

      * [StackOne Configuration](#stackone-configuration)
      * [ATS User Enablement](#ats-user-enablement)
    </Note>

    * **User Types**: Select the user types who will have visibility of this tab.

    <Frame>
      <img alt="Custom Tab Configuration" />
    </Frame>

    Click the **Save** button.

    <Frame>
      <img alt="Save Button" />
    </Frame>
  </Step>

  <Step title="Locate the Custom Tab under Candidates">
    Navigate to the *Candidates List* page, click the `Menu` button, and then click `Primary`.

    <Frame>
      <img alt="Primary Menu" />
    </Frame>

    Click the `Candidates` button.

    <Frame>
      <img alt="Candidates Button" />
    </Frame>

    Click any candidate from the list.

    <Frame>
      <img alt="Candidate List" />
    </Frame>

    You will find the custom tab on the candidate detail page either within the main tab area or under the *More* drop-down.

    <Frame>
      <img alt="Custom Tab on Candidate Page" />
    </Frame>
  </Step>
</Steps>

## StackOne Configuration

<Steps>
  <Step title="Navigate to the ATS category">
    Navigate to the ATS category on the *Integrations* page and enable Bullhorn.

    <Frame>
      <img alt="Bullhorn Integration Setup" />
    </Frame>
  </Step>

  <Step title="Complete the configuration form">
    Fill out the necessary fields in the **Bullhorn - Configuration model**:

    * **Authentication Type:** Select `OAuth2 - Assessments/Background Checks` to utilise the assessments/background checks integrations.

    * **Partner Category:** Bullhorn does not define separate integration categories. You choose which feature to surface in the custom tab. If the tab is for background checks or assessments, select the corresponding category: `Background Checks` or `Assessments`.

    * **Package's List Endpoint URL:** Implement and provide an endpoint to StackOne, which StackOne will use to retrieve the list of packages when the recruiter wants to send a test to a candidate.

      Implement the following POST endpoint:

      ```bash theme={null}
      curl --location 'https://your-domain.com/<route-to-the-post-endpoint>' \
      --header 'Content-Type: application/json' \
      --header 'x-stackone-signature: string' \
      --header 'Authorization: Basic <base64encoded-bullhorn-api-key>' \
      --data '{
        "account_id": "456551489512493413",
        "provider": "bullhorn_ats"
      }'
      ```

      The expected response of the POST endpoint (list of packages). Refer to:

      * [List Assessments Packages](https://docs.stackone.com/ats/api-reference/assessments/packages/list-assessments-packages)
      * [List Background Check Packages](https://docs.stackone.com/ats/api-reference/background-checks/packages/list-background-check-packages)

      Enter the endpoint into the designated field:

      ```plaintext theme={null}
      https://your-domain.com/<route-to-the-post-endpoint>
      ```

    * **Package ID:** If you do not have the Package's List Endpoint URL, you can add a static package ID that will be visible to the recruiter when they want to send a test to the candidate.

      <DifferenceBetweenListEndpointAndStaticIdOfPackage />

      <Frame>
        <img alt="Bullhorn Configuration Form" />
      </Frame>

      Click on the `Confirm` or `Save Changes` button to enable OAuth APIs, which allows users to link their accounts via the StackOne Connector Hub.
  </Step>

  <Step title="Create a Webhook">
    Navigate to the *Webhooks* page, click `+ Add webhook`, and complete the form:

    * **Name:** Enter a recognisable name for your webhook.
    * **URL:** Enter the URL where the webhook will send notifications of enabled events.
      <Frame>
        <img alt="Create Webhook" />
      </Frame>
  </Step>

  <Step title="Select webhook event">
    Navigate to the *Events* tab and enable webhook events for Assessment & Background Check, such as `Assessments Order` & `Background Check Order`.

    <Frame>
      <img alt="Select Webhook Event" />
    </Frame>

    Click the `Confirm` button to save the webhook.
  </Step>
</Steps>

## ATS User Enablement

Navigate to the *Accounts* page or the StackOne Connector Hub to link your Bullhorn account with StackOne.

<Frame>
  <img alt="Link Bullhorn account" />
</Frame>

You will receive the `External Trigger Token`, which must be passed as a query parameter along with the endpoint URL when setting up the custom tab in Bullhorn, as outlined in the [Provider Side Setup](#provider-side-setup).

<Frame>
  <img alt="External Trigger Token" />
</Frame>

## ATS User Experience

After completing the configuration process, users will see the custom tab on the candidate detail page in Bullhorn.

<Frame>
  <img alt="Custom Tab on Candidate Page" />
</Frame>

Users can click on the `Send Assessment/Background Check` button, select one of the packages from the drop-down, and click on the `Send` button to send the assessment/background check test to the candidate.

<Frame>
  <img alt="Send Background Check Button" />
</Frame>

A webhook notification will be triggered and you will receive the notification. On Bullhorn UI, the status will be updated to `Pending`.

<Frame>
  <img alt="Webhook Notification" />
</Frame>

Once the result is updated in Bullhorn’s UI, users will see the updated results.

<Frame>
  <img alt="Updated Results" />
</Frame>

## ATS User Experience Customisation

<Steps>
  <Step title="To Update the result via unified api">
    Utilise the following endpoints to update the results:

    * [Assessment Update Result](https://docs.stackone.com/ats/api-reference/assessments/results/update-assessments-result)
    * [Background Check Update Result](https://docs.stackone.com/ats/api-reference/background-checks/results/update-background-check-result)

    Utilise the following endpoint to get endpoint's metadata to update the result of the assessment or background check:

    * [Connector Meta Information](https://docs.stackone.com/platform/api-reference/connectors/get-connector-meta-information) with the provider key `bullhorn_ats` for model `assessments/results.update` or `background_checks/results.update`

    <div>
      | Fields (when provided) | User sees in Bullhorn                                                       | Comments                                      |
      | ---------------------- | --------------------------------------------------------------------------- | --------------------------------------------- |
      | Score's value          | Score column will reflect the latest score's value                          |                                               |
      | Result                 | Status column will reflect the latest result's status                       | Result enum values from Meta API result field |
      | Submission Date        | Date column will reflect the latest submission date                         |                                               |
      | Result Url             | Results URL column will reflect the latest Result URL as a View Result link |                                               |
    </div>
  </Step>

  <Step title="How will the results of the assessment/background check be displayed to the user in Bullhorn?">
    When a user opens a Assessment/Background Check custom tab, they will see the updated result with their score and status.

    <Frame>
      <img alt="Updated Results" />
    </Frame>
  </Step>
</Steps>

## Testing Checklist

✅ **Provider Setup Validation:**

* Logged-in with Admin account.
* Created and enabled a custom tab with valid user types assigned.
* Added a custom tab for Assessment or Background Check as mentioned in the <a href="#provider-side-setup">Provider Side Setup</a>.
* Valid StackOne URL along with the `externalTriggerToken` query parameter.

✅ **StackOne Configuration Validation:**

* Selected `OAuth2 - Assessments/Background Checks` Authentication Type.
* Package's List Endpoint URL is correct.
* Package's List Endpoint response is expected according to the following endpoint's response:
  * [List Assessments Packages](https://docs.stackone.com/ats/api-reference/assessments/packages/list-assessments-packages)
  * [List Background Check Packages](https://docs.stackone.com/ats/api-reference/background-checks/packages/list-background-check-packages)

✅ **ATS User Activation Validation:**

* Valid `externalTriggerToken` to the query parameter.

✅ **Create a Webhook**

* Added a webhook for Bullhorn and enabled it with the events such as: `Assessments Order` or `Background Check Order`
* Valid webhook URL to receive assessment/background check notifications.

✅ **ATS User Experience:**

* Custom tab is visible in the candidate detail page either within the main tab area or under the *More* dropdown.
* When selecting a package and sending the webhook, the status is updated to `Pending` along with actions that is updated to `Sent`.

✅ **Update Result**

* Success response from the update result endpoint.
* Updated result details to Bullhorn's UI.

## Troubleshooting

<div>
  | Symptom                                                                         | Likely cause                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Fix                                                                                                                                                                                                                                                                                                                                           |
  | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Unable to access/add custom tab                                                 | Logged-in account is not an Admin account                                                                                                                                                                                                                                                                                                                                                                                                                             | Log in with an Admin account                                                                                                                                                                                                                                                                                                                  |
  | External Trigger Token field is not visible at StackOne Connector Hub           | Selected Authentication Type is incorrect.                                                                                                                                                                                                                                                                                                                                                                                                                            | Select Authentication Type `OAuth2 - Assessments/Background Checks` instead.                                                                                                                                                                                                                                                                  |
  | Custom tab is not visible in candidate detail page                              | Enabled checkbox is not checked.                                                                                                                                                                                                                                                                                                                                                                                                                                      | Tick **Enabled** checkbox under the custom tab to enable the custom tab to visible within the candidate detail page.                                                                                                                                                                                                                          |
  | Custom tab is visible however getting 500                                       | **•** Invalid URL. <br /><br /> **•** Invalid External Trigger Token. <br /><br /> **•** Invalid Package's List Endpoint URL.                                                                                                                                                                                                                                                                                                                                         | **•** Verify the StackOne URL. <br /><br /> **•** Verify External Trigger Token. <br /><br /> **•** Verify Package's List Endpoint URL.                                                                                                                                                                                                       |
  | Packages unavailable despite provided endpoint URL                              | Empty Response from the Package's List Endpoint URL.                                                                                                                                                                                                                                                                                                                                                                                                                  | Verify the Package's List Endpoint URL and ensure it returns the expected package data.<br /><br /> <Note>If you don’t have the package list endpoint URL, you can use the Package ID with a static package.</Note>                                                                                                                           |
  | Test notification is not received                                               | **•** External Trigger Token is invalid. <br /><br /> **•** Invalid webhook URL at StackOne. <br /><br /> **•** Enabled events are not as expected.                                                                                                                                                                                                                                                                                                                   | **•** Use a valid External Trigger Token. <br /><br /> **•** Check webhook URL at StackOne. <br /><br /> **•** Check enabled events are expected.                                                                                                                                                                                             |
  | Status updated to `Pending` but record not found when revisiting the custom tab | **•** Either External Trigger Token is updated after notification has been sent. <br /><br /> **•** Enabled events are updated after notification has been sent. <br /><br /> **•** Custom field is updated and not the previous one that is selected at the time of getting notification sent from the StackOne Connector Hub. <br /><br /> **•** Custom Field data is corrupted due to reuse of that custom field at different places or for different custom tabs. | **•** Verify the External Trigger Token. <br /><br /> **•** Check enabled events are expected. <br /><br /> **•** Check the Custom Field data it can be corrupted. <br /><br /> **•** Select the correct custom field from the StackOne Connector Hub. <br /><br /> **•** Utilise a unique custom field and confirm it is not used elsewhere. |
  | Results not updating in Bullhorn                                                | **•** Custom field is updated and not the previous one that was selected at the time of notification sent from the StackOne Connector Hub. <br /><br /> **•** Custom Field data is corrupted due to reuse of that custom field at different places or for different custom tabs.                                                                                                                                                                                      | **•** Select the correct custom field from the StackOne Connector Hub. <br /><br /> **•** Utilise a unique custom field and confirm it is not used elsewhere.                                                                                                                                                                                 |
  | Result URL showing error when opened                                            | Added result URL can be expired or is private.                                                                                                                                                                                                                                                                                                                                                                                                                        | Ensure to add public or signed URLs; verify CORS and expiry.                                                                                                                                                                                                                                                                                  |
</div>

For persistent issues, contact StackOne support with detailed error logs and configuration information.


# Eploy Background Check Partner Integration
Source: https://docs.stackone.com/integration-guides/ats/eploy-background-check-integration-partner

Learn how to set up and use the Eploy Background Check as a Partner Integration with StackOne

## Overview

This guide explains how to configure custom options and fields, add background check packages in Eploy, and integrate with StackOne to receive background check notifications.

## Partner Requirements

Eploy integration partnership is required to proceed with this documentation. Visit [Eploy Technology Partner Support](https://www.eploy.com/partner/technology-partners) to fill out the form and initiate the partnership process. One of the Eploy team members will reach out to you to discuss the partnership and integration process.

### Eploy Approach: Workflow-based Integrations

Eploy enables workflow-based integrations for recruitment, handling tasks like background checks.
The process begins by regularly polling Eploy to identify applicants needing processing. Their data is then extracted to initiate the integration,
which includes creating actions and marking exported applications.

A typical Eploy workflow is structured as follows:

<Frame>
  <img alt="eploy process flow" />
</Frame>

### StackOne's Unified Approach for Integration Partners

StackOne manages the Eploy-required polling internally. The interaction model for this integration follows our standard webhook-based Background Check pattern.
Because Eploy requires polling, there can be a short delay between moving an application into the background check stage and the order being triggered.

<Info>
  **Note:** Repeating the following step is required for each user that you want to connect with Eploy.

  To add your background check integration, please contact [**Eploy Technology Partner Support**](https://www.eploy.com/partner/technology-partners)
</Info>

After your integration app is added as a stage in Eploy, configure the same stage name in StackOne as outlined in the following [steps](#stackone-configuration).

<Frame>
  <img alt="stackone sequence flow" />
</Frame>

## Provider Side Setup

Once the Eploy partnership is established, your Eploy integration app will appear in the [Eploy Marketplace](https://www.eploy.com/product/eploy-marketplace).
After it is enabled for testing, the integration app will be available as a stage option in the Stages dropdown when creating or editing Recruiting Workflows.

<Note>
  Visit the [ATS User Experience](#ats-user-experience) section to be ensure that the integration app is enabled and visible as a stage in a Recruiting Workflow.
</Note>

<Frame>
  <img alt="Eploy Integration app Stage" />
</Frame>

<Note>
  Users must contact you or Eploy to activate the integration partnership. Once activated, your app appears in the Stages dropdown when users create or edit Recruiting Workflows.
</Note>

### Add a custom option for background check packages

Navigate to the *Custom Fields* page by selecting *Customise Fields* from the *Admin* menu

<Frame>
  <img alt="Go to Custom Fields page" />
</Frame>

Navigate to the *User Option Types* tab and click the `New` button to create a new custom option in Eploy

<Frame>
  <img alt="Go to user option types tab" />
</Frame>

Enter the title as `Background Checks` and then click the `Save` button

<Warning>
  Use the name **Background Checks**, as this is necessary to ensure that you receive notifications from Eploy.
</Warning>

<Frame>
  <img alt="add custom option title" />
</Frame>

The newly created `Background Checks` option will be visible in the *User Option Types* grid

<Frame>
  <img alt="added custom option title" />
</Frame>

### Add a custom field within the vacancy group

Navigate to the *Custom Fields* page by selecting *Customise Fields* from the *Admin* menu

<Frame>
  <img alt="Go to Custom Fields page" />
</Frame>

Navigate to the *Fields* tab and click the `New` > `Input Field` button to create a new input field in Eploy

<Frame>
  <img alt="Go to fields tab" />
</Frame>

Select the field values according to the instructions below:

<Warning>
  Ensure you select the same values as suggested to receive Eploy notifications.
</Warning>

* **Field Group:** Select `Additional Details (Vacancies)`
* **Field Type:** Select `Input - Drop-down`
* **Display Format:** Select `Hierarchy List Searchable`
* **Option Type:** Select `Background Checks` (as created in the [previous step](#add-a-custom-option-for-background-check-packages))
* **Insert Below:** You can select any value here; it will determine where the field appears in the form
* **Active:** Ensure this field is marked as **active**
* **Field Label:** Select `Background Checks`
* **Help Description:** You may include any relevant description

Click the `Save` button

<Frame>
  <img alt="add custom field" />
</Frame>

The newly created `Background Checks` field will be visible in the *Fields* grid

<Frame>
  <img alt="added custom field title" />
</Frame>

### Add background check packages

<Info>
  You can use the [Create Background Check Package](https://docs.stackone.com/ats/api-reference/background-checks/packages/create-background-check-package) unified endpoint to add background check packages, or follow the steps outlined below to add them manually.
</Info>

Navigate to the *Drop Down Lists* page located in the *Admin* menu to add background check packages through the Eploy user interface

<Frame>
  <img alt="navigate to dropdown list" />
</Frame>

Select `Background Checks` and click the `New` button to create a new package in Eploy

<Frame>
  <img alt="select background checks" />
</Frame>

Enter the following field values:

* **Description:** This will be the label displayed in the dropdown list.
* **Reference:** This can be any string and will not appear in the dropdown list.

Click the `Save` button.

<Frame>
  <img alt="click on save" />
</Frame>

The newly created background check package will be visible in the grid

<Frame>
  <img alt="added background checks field" />
</Frame>

### Configure the background check package for the vacancy

<Info>
  Users will need to select the background check package for each vacancy to associate the relevant background check.
</Info>

Go to the *Additional Details* page for job vacancies created within the Recruitment Workflow that includes the background check integration stage.

<Note>
  Visit the [ATS User Experience](#ats-user-experience) section to see how to create a vacancy in a workflow that includes the background check integration stage.
</Note>

<Frame>
  <img alt="Eploy navigate to additional details page of vacancy" />
</Frame>

Edit *Additional Details* to select the background check package.

<Frame>
  <img alt="Eploy navigate to additional details page of vacancy" />
</Frame>

The selected background check package will be displayed on the *Additional Details* page.

<Frame>
  <img alt="Eploy selected background check package" />
</Frame>

## StackOne Configuration

<Steps>
  <Step title="Navigate to enable Eploy in StackOne">
    Go to the ATS category on the *Integrations* page and find Eploy.

    <Frame>
      <img alt="enable eploy" />
    </Frame>
  </Step>

  <Step title="Configure Eploy in StackOne">
    Fill out the necessary fields in the **Eploy - Configuration** modal:

    * **Authentication Type:** Select `OAuth2`.
    * **Integration Stage Name:** Enter the stage name exactly as your integration app's stage name in Eploy to trigger the Background Check.

    <Frame>
      <img alt="configure eploy" />
    </Frame>

    Click `Confirm` or `Save Changes` to enable your OAuth APIs, which allows end-users to link their accounts via the Hub.
  </Step>

  <Step title="Add a Webhook">
    Navigate to the *Webhooks* page, click `Add webhook`, and fill out the form:

    * **Name:** A recognisable name for the webhook.
    * **URL:** The endpoint that will receive notifications for enabled events.

    <Frame>
      <img alt="Add Webhook form" />
    </Frame>

    Enable webhook events in the `Events` tab for Background Check, such as `Background Check Order`.

    <Frame>
      <img alt="Select webhook events" />
    </Frame>

    Click `Confirm` and then `Save` to add the webhook.
  </Step>
</Steps>

## ATS User Enablement

To enable the Eploy Technology Partner app and make it available as a stage within a Recruitment Workflow, go to the [Eploy Marketplace](https://www.eploy.com/product/eploy-marketplace).

<Frame>
  <img alt="Eploy Marketplace" />
</Frame>

Click the listed partner's app in the Marketplace. It will direct you to the [Integrate your Eploy with Partner form](https://www.eploy.com/partner/technology-partners). Fill out the form to initiate your request to enable the integration for your Eploy account.

<Frame>
  <img alt="Eploy Marketplace" />
</Frame>

Once the partner's app is enabled, it appears in the Stages dropdown when creating or editing Recruitment Workflows.

<Note>
  Visit the [ATS User Experience](#ats-user-experience) section to verify if the partner's integration app is enabled and visible in the Stages dropdown.
</Note>

## ATS User Experience

### Add a Recruitment Workflow

Navigate to the *Recruitment Workflow* page from the *Admin* menu.

<Frame>
  <img alt="Eploy Integration app Stage" />
</Frame>

Click the `+ New` button to create a new workflow.

<Frame>
  <img alt="Eploy Integration app Stage" />
</Frame>

Fill out the necessary fields in the *Create Recruitment Workflow* form as per the requirements, and click `Save`.

<Frame>
  <img alt="Eploy Integration app Stage" />
</Frame>

Scroll down and click the `Add` button to add stages in the workflow.

<Frame>
  <img alt="Eploy Integration app Stage" />
</Frame>

User can choose various stages as per the requirements and select the partner's integration app stage from the Stages dropdown to trigger the background check notification.

For the partner's integration app stage, select the following values:

* **Stage Name:** Select the partner's integration app name.

<Frame>
  <img alt="Eploy Integration app Stage" />
</Frame>

* **Stage Type:** Select `Actions`.
* **Action Type:** Select the partner's integration app name.

User may configure other settings as per the requirements and click `Save` to add this stage to the workflow.

<Frame>
  <img alt="Eploy Integration app Stage" />
</Frame>

After saving, the stage appears in the workflow.

<Frame>
  <img alt="Eploy integration stage" />
</Frame>

Ensure the workflow is set to `Active` to be visible when creating a vacancy.

<Frame>
  <img alt="Eploy activate workflow" />
</Frame>

The newly created workflow appears in the *Recruitment Workflow* grid.

<Frame>
  <img alt="Eploy saved workflow" />
</Frame>

### Create a Vacancy in the Workflow

Navigate to the *Vacancy* page via `+` button in the top menu.

<Frame>
  <img alt="Eploy navigate to vacancies" />
</Frame>

Fill out the vacancy form by choosing the **Recruitment Workflow** that includes the partner's integration app stage user added earlier. User can also configure other fields as per the requirements and click `Save`.

<Frame>
  <img alt="Eploy create vacancy" />
</Frame>

User will be directed to the vacancy page after saving.

<Frame>
  <img alt="Eploy create vacancy" />
</Frame>

User can see the partner's integration app stage in the vacancy's talent pipeline by navigating to `Work on Vacancy` > `Go to Pipeline`.

<Frame>
  <img alt="Eploy integration stage in talent pipeline" />
</Frame>

The stage appears in the vacancy's talent pipeline.

<Frame>
  <img alt="Eploy integration stage in talent pipeline" />
</Frame>

### Select a Background Check package to associate with the vacancy

Navigate to the *Additional Details* page of the vacancy to select and associate the background check package.

<Frame>
  <img alt="Eploy navigate to additional details page of vacancy" />
</Frame>

Edit the *Additional Details*, select the background check package from the `Background Checks` dropdown, and `Save` the changes.

<Frame>
  <img alt="Eploy select background check package" />
</Frame>

The selected background check package will appear on the *Additional Details* page.

<Frame>
  <img alt="Eploy selected background check package" />
</Frame>

### Create a Candidate and add as an applicant to the vacancy

Navigate to the *Candidate* page via `+` button in the top menu.

<Frame>
  <img alt="Eploy navigate to candidates" />
</Frame>

Fill out the necessary details in the **Create Candidate** form and `Save`.

<Frame>
  <img alt="Eploy create candidate" />
</Frame>

User will be directed to the candidate's profile page after saving, where they can initiate the candidate's application by clicking `Application` under the `+` button menu.

<Frame>
  <img alt="Eploy create vacancy" />
</Frame>

Select the **Vacancy** and **Stage**, and then `Save` to add the candidate as an applicant to the vacancy.

<Frame>
  <img alt="Eploy apply to vacancy" />
</Frame>

User can see the candidate added as an applicant to the vacancy by navigating to the vacancy's talent pipeline.

<Frame>
  <img alt="Eploy candidate added to vacancy" />
</Frame>

The candidate appears in the **Stage** user selected when creating the application.

<Frame>
  <img alt="Eploy candidate in pipeline" />
</Frame>

User can move the candidate's application to the partner's integration app stage to trigger the background check.

<Note>
  Because Eploy requires polling, there can be a short delay between moving an application into the background check stage and the order being triggered.
</Note>

### Send test to the candidate

<Frame>
  <video />
</Frame>

### User will see after test has been sent

When a user sends the background check test to a candidate, a success message is shown on the candidate's application.

<Frame>
  <img alt="Eploy sent test view" />
</Frame>

## ATS User Experience Customisation

<Steps>
  <Step title="Update the result via Unified API">
    Use the following endpoint to update the results:

    * [Background Check Update Result](https://docs.stackone.com/ats/api-reference/background-checks/results/update-background-check-result)

    Use the following endpoint to get metadata needed to update the background check result:

    * [Connector Meta Information](https://docs.stackone.com/platform/api-reference/connectors/get-connector-meta-information) with the provider key `eploy` for model `background_checks/results.update`

    <div>
      | Fields (when provided) | User sees in Eploy                                                 |
      | ---------------------- | ------------------------------------------------------------------ |
      | Score label & value    | Score label and value will appear together in Eploy                |
      | Submission date        | Submission date will appear above or below the result detail block |
      | Summary                | Summary will appear above the package name                         |
      | Result URL             | Result URL will appear within the `View Results` link              |
    </div>
  </Step>

  <Step title="How will the results of the background check be displayed to the user in Eploy?">
    When a user opens a candidate application, the updated results are visible.

    <Frame>
      <img alt="Eploy update result view" />
    </Frame>
  </Step>
</Steps>

## Testing Checklist

✅  **Provider Setup:**

* Ensure the Eploy Partner Integration app is enabled for your Eploy Sandbox account.
* Add the `Background Checks` custom option in User Option Types. See <a href="#add-a-custom-option-for-background-check-packages">this</a> step.
* Add a custom input field for the vacancy group; it appears under *Additional Details*. See <a href="#add-a-custom-field-within-the-vacancy-group">this</a> step.
* Add background check packages; they appear in the custom field dropdown. See <a href="#add-background-check-packages">this</a> step.
* Associate a background check package with the vacancy. See <a href="#configure-the-background-check-package-for-the-vacancy">this</a> step.

✅  **StackOne Configuration:**

* Enter a valid `Integration Stage Name` that exactly matches your integration app's stage name in Eploy.

✅  **ATS User Enablement:**

* The partner app is enabled by Eploy and visible in the Stages dropdown to add within a workflow.
* The user associates the background check package for the vacancy.

✅  **Create a Webhook:**

* Add a webhook for Eploy with a valid URL and enable expected Background Check events, such as `Background Check Order`.

✅  **ATS User Experience:**

* Go to *Vacancy* > *Additional Details* and select a background check package to associate with the vacancy.
* The integration stage is visible when the vacancy is created in a workflow that includes the background check stage.
  * The user can move the application to the integration stage.
  * The user can see the sent test details in the candidate's application.

✅  **Update Result:**

* Receive a success response from the update result endpoint.
* Updated result details appear in Eploy's UI.

## Troubleshooting

<div>
  | Symptom                                                                                                                 | Likely cause                                                                        | Fix                                                                                                                                                       |
  | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Unable to find your Integration app in the [Eploy Marketplace](https://www.eploy.com/product/eploy-marketplace).        | Eploy Partner Integration is not published/approved.                                | Contact Eploy support for partnership status.                                                                                                             |
  | Integration partner app not visible under stage list dropdown.                                                          | Integration app is not active for your eploy account.                               | Contact Eploy support for partnership status.                                                                                                             |
  | Integration partner app not visible as a stage in vacancy pipeline.                                                     | Integration app is not selected as a stage in vacancy's workflow.                   | Navigate to vacancy's workflow and add integration as a stage. please refer to <a href="#ats-user-experience">this</a> steps.                             |
  | Unable to see the `Background Checks` custom field in Additional Details page of the vacancy.                           | Custom field is not created or configured incorrectly.                              | Create a custom field as per the instructions in the [Add a custom field within the vacancy group](#add-a-custom-field-within-the-vacancy-group) section. |
  | Unable to see the list of packages in the `Background Checks` dropdown field in Additional Details page of the vacancy. | Packages are not added for background checks custom fields.                         | Add background check packages as mentioned in the [Add background check packages](#add-background-check-packages) section.                                |
  | Test notification is not received.                                                                                      | **•** Invalid webhook URL. <br /><br /> **•** Incorrect webhook events are enabled. | **•** Verify webhook URL. <br /><br /> **•** Enable expected events as mentioned in the [StackOne Configuration](#stackone-configuration).                |
  | Unable to update result.                                                                                                | Invalid payload format.                                                             | Check Connector Meta API endpoint for payload format.                                                                                                     |
</div>

For persistent issues, contact StackOne support with detailed error logs and configuration information.


# Greenhouse Partner Integration API
Source: https://docs.stackone.com/integration-guides/ats/greenhouse-partner-api

To activate the Greenhouse Partner integration in StackOne for assessments and background checks., please follow the necessary steps.

## Overview

StackOne enables integration with Greenhouse for Assessment and Background Check, allowing you to receive webhook notifications whenever a recruiter sends a test to a candidate, updates the test result, and views the result on the candidate’s profile in Greenhouse.
This guide covers how to set up and use the Greenhouse Integration Partner with StackOne.

## Partnership Requirements

<Warning>
  A partnership with Greenhouse Integration Partner is required to proceed with this documentation.
</Warning>

<Steps>
  <Step title="Apply to the Greenhouse Integration Partner Program">
    Visit the [Greenhouse Integration Partner application page](https://www.greenhouse.com/integration-partner#apply-now) and begin the partner application process.
  </Step>

  <Step title="Select Integration Types">
    On the application form, select <b>Assessment API</b>, <b>Webhook</b>, and <b>Harvest API</b> as your integration types.<br />
    When you select <b>Assessment API</b>, you will be prompted to provide specific API endpoint URLs (see the screenshot attached with the next step).
  </Step>

  <Step title="Provide StackOne Endpoint URLs in the form">
    **list\_tests**

    ```plaintext theme={null}
    https://api.stackone.com/external-trigger/greenhouse/list_tests?tenant-id=YOUR_GREENHOUSE_TENANT_ID
    ```

    **send\_test**

    ```plaintext theme={null}
    https://api.stackone.com/external-trigger/greenhouse/send_test?tenant-id=YOUR_GREENHOUSE_TENANT_ID
    ```

    **test\_status**

    ```plaintext theme={null}
    https://api.stackone.com/external-trigger/greenhouse/test_status?tenant-id=YOUR_GREENHOUSE_TENANT_ID
    ```

    **response\_error**

    ```plaintext theme={null}
    https://api.stackone.com/external-trigger/greenhouse/response_error?tenant-id=YOUR_GREENHOUSE_TENANT_ID
    ```

    <Note>
      **About the Tenant ID**: The `tenant-id` parameter in these URLs should be replaced with a unique identifier of your choice.
      This ID is **not provided by Greenhouse** and is **not generated by StackOne**. You can use any unique value (e.g., your company name such as `example-inc` or `acme-corp`).
      This parameter is used by Greenhouse to create uniquely routed endpoints and distinguish between different integrations. Choose a value that makes sense
      for your organisation and use it consistently across all endpoints.
    </Note>

    <Frame>
      <img alt="Greenhouse Assessment API Endpoint Form" />
    </Frame>

    <Info>
      Greenhouse reviews applications on the first Monday of every month. A member of their Partnerships team will contact you with next steps.
    </Info>
  </Step>

  <Step title="Receive Partnership Credentials">
    Once approved, Greenhouse will provide you with:

    * Partner Username
    * Partner Password
    * Any additional credentials needed

    Use these credentials to complete the [StackOne Configuration](#stackone-configuration).

    <Info>
      To test your integration app through your Greenhouse Sandbox, please contact Greenhouse Support and provide the **External Trigger Token** to enable the integration.

      <Note>
        To obtain the **External Trigger Token**, please follow these steps:

        * [StackOne Configuration](#stackone-configuration)
        * [ATS User Enablement](#ats-user-enablement)
      </Note>
    </Info>
  </Step>
</Steps>

## Provider Side Setup

You need to submit a request for Greenhouse Integration Partner as mentioned in [Partnership Requirements](#partnership-requirements) to obtain the Greenhouse Integration Partnership,
and provide the **External Trigger Token** required to enable your integration if you want to test your integration app via the Greenhouse Sandbox.

<Note>
  To obtain the **External Trigger Token**, please follow these steps:

  * [StackOne Configuration](#stackone-configuration)
  * [ATS User Enablement](#ats-user-enablement)
</Note>

Once your integration is enabled by Greenhouse, it will be available to add as a stage under *Jobs > Interview Plans*.

## StackOne Configuration

<Steps>
  <Step title="Navigate to enable the Greenhouse at StackOne">
    Go to the ATS category on the *Integrations* page and enable Greenhouse.

    <Frame>
      <img alt="Configuration" />
    </Frame>
  </Step>

  <Step title="Enable and Configure Greenhouse in StackOne">
    Fill out the necessary fields in the **Greenhouse - Configuration** modal:

    * **Authentication Type** - Select `Public + Partner API` or `Partner API` to integrate with Greenhouse (for Assessment/Background Check integration).
      <DifferenceBetweenPublicAndPartnerAPI />
      <Note>
        * If you select `Public + Partner API`, the hiring team's data will be included in the webhook notification.<br />
        * If you select `Partner API`, the hiring team's data will not be included in the webhook notification.
      </Note>

    * **Partner Category** - Select the appropriate category based on your integration's classification as a partner for Greenhouse. e.g.: `Assessments` or `Background Checks`

    * **Package's List Endpoint URL** - Implement and provide an endpoint to StackOne that StackOne will use to retrieve the list of packages when the recruiter wants to send a test to a candidate.

      Implement the following POST endpoint:

      ```bash theme={null}
      curl --location 'https://your-domain.com/<route-to-the-post-endpoint>' \
      --header 'Content-Type: application/json' \
      --header 'x-stackone-signature: string' \
      --header 'Authorization: Basic <base64encoded-api-key>' \
      --data '{
          "account_id": "456551489512493411",
          "provider": "greenhouse"
      }'
      ```

      The expected response of the POST endpoint (list of packages). Refer to:

      * [List Assessments Packages](https://docs.stackone.com/ats/api-reference/assessments/packages/list-assessments-packages)
      * [List Background Check Packages](https://docs.stackone.com/ats/api-reference/background-checks/packages/list-background-check-packages)

      Enter the endpoint into the designated field:

      ```plaintext theme={null}
      https://your-domain.com/<route-to-the-post-endpoint>
      ```

    * **Partner's Username** - You will receive the `username` from Greenhouse support as mentioned in the previous step.

    * **Partner's Password** - The `password` will also be provided by Greenhouse support as mentioned in the previous step.

    * **Package ID** - If you do not have the Package's List Endpoint URL, you can specify a particular package ID that will be visible to the recruiter when they wish to send the test to the candidate.

    <DifferenceBetweenListEndpointAndStaticIdOfPackage />

    <Frame>
      <img alt="Greenhouse Configuration Form" />
    </Frame>

    Click on the `Confirm` or `Save Changes` button to enable Greenhouse, which allows end-users to link their accounts via the StackOne Connector Hub.
  </Step>

  <Step title="Add a Webhook">
    Navigate to the *Webhooks* page, click on `Add webhook` and fill out the form:

    * **Name:** Enter your webhook with a recognisable name.
    * **URL:** Enter the URL where the webhook will send the notification of the enabled events.

    <Frame>
      <img alt="Add Webhook form" />
    </Frame>

    Enable webhook events from the `Events` tab for Assessment & Background Check, such as `Assessments Order` & `Background Check Order`.

    <Frame>
      <img alt="Select webhook events" />
    </Frame>

    Click the `Confirm` and `Save` buttons to add the webhook.
  </Step>
</Steps>

## ATS User Enablement

Navigate to the *Accounts* page or the StackOne Connector Hub to link your Greenhouse account with StackOne.

<Frame>
  <img alt="Link Greenhouse Account" />
</Frame>

Once your Greenhouse Integration app is published in the [Greenhouse Marketplace/Partner Directory](https://integrations.greenhouse.com), the user will need to provide an **External Trigger Token** to Greenhouse Support. This token serves as an API key to enable the integration, which can be obtained from the StackOne Connector Hub during the connection process.

<Info>
  **For Partners:** To test your integration app using the Greenhouse Sandbox, you need to provide an **External Trigger Token** to Greenhouse support as an API key in order to connect your integration app.

  **For Users:** Each user must provide an **External Trigger Token** to Greenhouse support in order to connect with your integration app.
</Info>

<Frame>
  <img alt="Greenhouse User view of External-trigger" />
</Frame>

When Greenhouse completes the configuration process, the user will see your integration as a stage in Jobs > Interview Plan and can use it to send assessments or background checks to the candidate.

<Frame>
  <img alt="User view of integration stage" />
</Frame>

## ATS User Experience

### Send the test to the candidate from Greenhouse

<Frame>
  <video />
</Frame>

<Note>
  Follow the [Greenhouse Assessment or Background Check](https://hub.stackone.com/integration-configuration-concepts/ats/greenhouse-assessment-background-check) guide regarding how to send the test from Greenhouse.
</Note>

### User will see after test has been sent

When a user sends an assessment or background check to a candidate, they will see an 'Awaiting candidate’s submission' message in the candidate application.

<Frame>
  <img alt="Send Webhook Success" />
</Frame>

## ATS User Experience Customisation

<Steps>
  <Step title="To Update the result via unified api">
    Utilise the following endpoints to update the results:

    * [Assessment Update Result](https://docs.stackone.com/ats/api-reference/assessments/results/update-assessments-result)
    * [Background Check Update Result](https://docs.stackone.com/ats/api-reference/background-checks/results/update-background-check-result)

    Utilise the following endpoint to get metadata to update the result of the assessment or background check:

    * [Connector Meta Information](https://docs.stackone.com/platform/api-reference/connectors/get-connector-meta-information) with the provider key `greenhouse` for model `assessments/results.update` or `background_checks/results.update`

    <div>
      | Fields (when provided) | User sees in Greenhouse                                                                                             |
      | ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
      | Result URL             | Shows a **View Report** link in the Grading Instructions tab (under `Go to Interview Kit`) and a `Go to Test` link. |
      | Score value            | Displays the **Score** in the Grading Instructions tab (under `Go to Interview Kit`).                               |
      | Start Date             | Displays the **Started At** value in the Grading Instructions tab (under `Go to Interview Kit`).                    |
      | Submission Date        | Displays the **Completed At** value in the Grading Instructions tab (under `Go to Interview Kit`).                  |
      | Summary                | Displays the **Notes** value in the Grading Instructions tab (under `Go to Interview Kit`).                         |
    </div>
  </Step>

  <Step title="How will the results of the assessment/background check be displayed to the user in Greenhouse?">
    When a user opens a candidate's application, they will see the updated score along with its application stage.

    <Frame>
      <img alt="Updated Result" />
    </Frame>

    Click the `Go to Interview Kit` link to access more detailed test results.

    <Frame>
      <img alt="Detailed Result" />
    </Frame>

    <Note>
      By default, the test result status will be sent as `complete`. Multiple updates are not allowed for a test.
    </Note>
  </Step>
</Steps>

## Testing Checklist

✅  **Provider Setup:**

* Once the integration is published by Greenhouse, it is visible in the [Greenhouse Marketplace/Partner Directory](https://integrations.greenhouse.com) under Assessments or Background Checks categories.

✅  **StackOne Configuration:**

* Selected `Public + Partner API` or `Partner API`
* Package's List Endpoint URL is correct.
* Valid Partner's Username and Password
* Package's List Endpoint response is expected according to the following endpoint's response:
  * [List Assessments Packages](https://docs.stackone.com/ats/api-reference/assessments/packages/list-assessments-packages)
  * [List Background Check Packages](https://docs.stackone.com/ats/api-reference/background-checks/packages/list-background-check-packages)

✅  **ATS User Enablement:**

* Shared the `External Trigger Token` to the Greenhouse support, and they have enabled the partner integration app for your Greenhouse account.
* Once the app is enabled by Greenhouse for the user, the integration is visible to add as a stage in Jobs > Interview Plan under the specific Job.

✅  **Create a Webhook**

* Added a webhook for Greenhouse and enable it with the events such as: `Assessment Order` or `Background Check Order`
* Valid webhook URL to receive assessment/background check notifications.

✅  **ATS User Experience:**

* Navigate to specific *Job > Interview Plan > Add Stage > Select enabled Integration* app as a stage that will be visible under the candidate application.
* If you've configured Package's List Endpoint URL, a list of packages is visible in the dropdown field when you click the `Send test to candidate` link.
* If you've configured Static Package ID, a single package is visible in the dropdown field when you click the `Send test to candidate` link.
* Select a package, click `Send Test`, and send the webhook. A message **Submitted tests** will appear if the notification has been sent.

✅  **Update Result**

* Success response from the update result endpoint.
* Updated result details to Greenhouse’s UI.

## Troubleshooting

<div>
  | Symptom                                                                                                                 | Likely cause                                                                                                                                                                                                                             | Fix                                                                                                                                                                                                                                                                                                                      |
  | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  | Unable to find your Integration app in [Greenhouse Marketplace/Partner Directory](https://integrations.greenhouse.com). | Greenhouse Partner Integration is not published/approved.                                                                                                                                                                                | Contact Greenhouse support for partnership status.                                                                                                                                                                                                                                                                       |
  | Integration partner app not visible under *Jobs > Interview Plan* to add.                                               | **•** Integration app is not active. <br /><br /> **•** Invalid External Trigger Token.                                                                                                                                                  | Contact Greenhouse support for partnership status & provide External Trigger Token.                                                                                                                                                                                                                                      |
  | Unable to open prompt to select package & Getting `Sorry, we encountered an error. Please try again.` message.          | **•** Package's List Endpoint URL or Static Package ID is missing from StackOne Configuration. <br /><br /> **•** Invalid response getting from the Package's List Endpoint URL. <br /><br /> **•** Invalid Package's List Endpoint URL. | **•** Add Static Package ID if you don't have Package's List Endpoint URL. <br /><br /> **•** Response format should be expected as mentioned in the [StackOne Configuration](#stackone-configuration). <br /><br /> **•** Check Package's List Endpoint URL implementation at your end. <br /><br /> **•** Verify CORS. |
  | Test notification is not received.                                                                                      | **•** Invalid webhook URL. <br /><br /> **•** Incorrect webhook events are enabled.                                                                                                                                                      | **•** Verify webhook URL. <br /><br /> **•** Enable expected events as mentioned in the [StackOne Configuration](#stackone-configuration).                                                                                                                                                                               |
  | The job's hiring team data is not be included in test notification.                                                     | `Partner API` authentication type selected instead of `Public + Partner API`.                                                                                                                                                            | Select authentication type `Public + Partner API` instead.                                                                                                                                                                                                                                                               |
  | Unable to update result.                                                                                                | Invalid payload format.                                                                                                                                                                                                                  | Check Connector Meta API endpoint for payload format.                                                                                                                                                                                                                                                                    |
  | Unable to update result details again.                                                                                  | Attempting multiple result updates for the same test which has already been updated.                                                                                                                                                     | Update only final results in Greenhouse for the tests. <br /> <Note>By default, the test result status will be sent as `complete`. Multiple updates are not allowed for a test.</Note>                                                                                                                                   |
</div>

For persistent issues, contact StackOne support with detailed error logs and configuration information.


# Overview
Source: https://docs.stackone.com/integration-guides/ats/overview



Most API integrations work without additional configuration using the standard StackOne API [connector configuration](/guides/embedding-stackone-hub). See our standard [connector guides](https://hub.stackone.com/integrations) for setting up a customer account.

For some providers additional setup is required to allow them to communicate with the StackOne platform or to enable new features to the existing integration and workflows beyond the scope of our standard integration offerings.&#x20;

The customer may also be presented with further configuration options to setup the integration to suit their particular environment. Depending on the integration they may also be expected see changes on their front end-use of the underlying systems.

These guides are usually optional and are only required for specific purposes.


# Recruitee Partner API Integration
Source: https://docs.stackone.com/integration-guides/ats/recruitee-partner-api

Learn how to set up and use the Recruitee Partner API integration with StackOne

## Overview

This guide provides step-by-step instructions for setting up and using the Recruitee Partner API integration with StackOne.
It covers how to request and activate the integration, configure settings within StackOne, connect your Recruitee integration,
and how users can access and utilise your integration’s features.

## Partner Requirements

<Warning>
  A partnership with Recruitee is required to proceed with this documentation.
</Warning>

To become a Marketplace Technology Partner of Recruitee, navigate to [Marketplace integrations](https://support.recruitee.com/en/collections/2544984-marketplace-integrations).
Click on [Become a Marketplace Technology Partner](https://support.recruitee.com/en/articles/5907305-become-a-marketplace-technology-partner), then click on `Technology partnership request` to request a partnership with Recruitee.

<Frame>
  <img alt="Become a Marketplace Technology Partner" />
</Frame>

You will be redirected to the [Technology partner request form](https://tellent.com/technology-partner-application) page. Please complete the form and submit it to Recruitee for review.
Recruitee will review your Marketplace Technology Partner request, and their Technology Partnership Team will respond depending on the type of integration to progress the partnership.

<Note>
  Once you have obtained the Recruitee partnership, follow the steps below to connect your integration with StackOne for Assessment & Background Check.
</Note>

## Provider Side Setup

You need to submit a request for Recruitee Integration Partner as mentioned in [Partner Requirements](#partnership-requirements).
Once approved, you can utilise the **External Trigger Token** to activate your integration app if you wish to test the app via the Recruitee Sandbox.

<Note>
  To obtain the **External Trigger Token**, please follow these steps:

  * [StackOne Configuration](#stackone-configuration)
  * [ATS User Enablement](#ats-user-enablement)
</Note>

## StackOne Configuration

<Note>
  The deletion of a partner integration on **Recruitee** is currently not supported through **StackOne** configuration. To delete an integration, please contact the **StackOne support team**.
</Note>

<Steps>
  <Step title="Navigate to enable the Recruitee at StackOne">
    Go to the ATS category on the *Integrations* page and enable Recruitee.

    <Frame>
      <img alt="Configuration" />
    </Frame>
  </Step>

  <Step title="Enable and Configure Recruitee in StackOne">
    Complete the necessary fields in the **Recruitee - Configuration** modal:

    * **Authentication Type:** Select `Public + Partner API` to integrate with Recruitee (for Assessment/Background Check integration).

      <DifferenceBetweenPublicAndPartnerAPI title="Difference between Public API & Public + Partner API" />

    * **Environment Type:** If you have a Release Candidate (RC) environment account on Recruitee, select **Staging** as the environment type; otherwise, select **Production**.

    * **Partner Category:** Select the appropriate category based on your integration's classification as a partner for Recruitee, e.g. `Assessments` or `Background Checks`.

    * **Package's List Endpoint URL:** Implement and provide an endpoint to StackOne that StackOne will use to retrieve the list of packages when the recruiter wants to send a test to a candidate.

      Implement the following POST endpoint:

      ```bash theme={null}
      curl --location 'https://your-domain.com/<route-to-the-post-endpoint>' \
      --header 'Content-Type: application/json' \
      --header 'x-stackone-signature: string' \
      --header 'Authorization: Basic <base64encoded-api-key>' \
      --data '{
          "account_id": "456551489512493414",
          "provider": "recruitee"
      }'
      ```

      The expected response of the POST endpoint (list of packages). Refer to:

      * [List Assessments Packages](https://docs.stackone.com/ats/api-reference/assessments/packages/list-assessments-packages)
      * [List Background Check Packages](https://docs.stackone.com/ats/api-reference/background-checks/packages/list-background-check-packages)

      Enter the endpoint into the designated field:

      ```plaintext theme={null}
      https://your-domain.com/<route-to-the-post-endpoint>
      ```

    * **Package ID:** If you do not have the Package's List Endpoint URL, you can specify a particular package ID that will be visible to the recruiter when they wish to send the test to the candidate.

      <Accordion title="How is the Package's List Endpoint URL different from a Static Package ID?">
        <Info>
          The Package's List Endpoint URL allows StackOne to fetch a list of available packages from your system, while the Static Package ID is fixed and available for users to select on the provider's side.
        </Info>

        * When you have a Package's List Endpoint URL, a list of packages will be available to select in Recruitee.

        <Frame>
          <img alt="Dynamic Package ID" />
        </Frame>

        * When you have a Static Package ID, a static package ID will be available to select in Recruitee.
      </Accordion>

      <Note>
        At least one field is necessary for making packages available in the provider's UI. Preference will be given to the <b>Package's List Endpoint URL</b> if both fields are configured.
      </Note>

    * **Partner Codename:** A unique identifier for the partner, used to identify your integration on the Recruitee marketplace. It must consist of lowercase letters and dashes (-) and be globally unique.

    * **Name:** The name of your integration that will be displayed on the Recruitee dashboard.

    * **Description:** A brief overview of your integration that will be displayed on the Recruitee dashboard.

    * **Logo:** The logo of your integration that will be displayed on Recruitee.

    <Frame>
      <img alt="Recruitee Configuration Form" />
    </Frame>

    <Frame>
      <img alt="Recruitee Configuration Form" />
    </Frame>

    Click the `Confirm` or `Save Changes` button to enable Recruitee, which allows end-users to link their accounts via the StackOne Connector Hub.
  </Step>

  <Step title="Add a Webhook">
    Navigate to the *Webhooks* page, click on `Add webhook` and fill out the form:

    * **Name:** Enter a recognisable name for your webhook.
    * **URL:** Enter the URL where the webhook will send notifications for the enabled events.

      <Frame>
        <img alt="Add Webhook form" />
      </Frame>

    Enable webhook events from the `Events` tab for Assessment and Background Check, such as `Assessments Order` and `Background Check Order`.

    <Frame>
      <img alt="Select webhook events" />
    </Frame>

    Click the `Confirm` and `Save` buttons to add the webhook.
  </Step>
</Steps>

## ATS User Enablement

<Steps>
  <Step title="To obtain the External Trigger Token">
    Navigate to the *Accounts* page or the StackOne Connector Hub to link your Recruitee account with StackOne.

    <Frame>
      <img alt="Link Recruitee Account" />
    </Frame>

    Users will receive the **External Trigger Token** required to activate the integration from the Recruitee Marketplace.

    <Frame>
      <img alt="Recruitee User view of External-trigger" />
    </Frame>
  </Step>

  <Step title="Go to Recruitee Marketplace">
    Navigate to *Marketplace* page, select either `Assessments` or `Background Checks` from **Categories**.

    <Frame>
      <img alt="Maintain Assessment Status" />
    </Frame>
  </Step>

  <Step title="To activate the integration">
    Search for your integration partner's name in the search bar.

    <Frame>
      <img alt="Edit/View Assessment/Background check Status ID" />
    </Frame>

    Click on the integration app, then click `Integrate` button to proceed further,

    <Frame>
      <img alt="Edit/View Assessment/Background check Status ID" />
    </Frame>

    A pop-up will appear displaying the details of the integration along with an `Accept and Integrate` button. Click on the button to proceed to the next step.

    <Frame>
      <img alt="Edit/View Assessment/Background check Status ID" />
    </Frame>

    <Info>
      **For Partners:** To test your integration using the Recruitee Sandbox, you need to input an **External Trigger Token** into the integration from the marketplace to integrate.

      **For Users:** Each user needs to input an **External Trigger Token** to connect with your integration.
    </Info>

    The user will enter the `External Trigger Token` retrieved from the StackOne Connector Hub as mentioned in the <a href="#ats-user-enablement">above</a> steps, then click on `Integrate` to activate the integration app.

    <Frame>
      <img alt="Edit/View Assessment/Background check Status ID" />
    </Frame>

    The user can modify the permissions for different roles associated with this integration. Once done, click the `Save` button to apply the changes.

    <Frame>
      <img alt="Edit/View Assessment/Background check Status ID" />
    </Frame>

    <Note>
      The user can refer to the <a href="https://hub.stackone.com/integration-configuration-concepts/ats/recruitee-assessment-background-checks">Recruitee Assessment or Background Check Guide</a> for instructions on how to activate the Recruitee integration app from the Marketplace.
    </Note>
  </Step>
</Steps>

## ATS User Experience

<Steps>
  <Step title="Select Candidate from the Candidates">
    Navigate to the <i>Candidates</i> page and select the candidate.

    <Frame>
      <img alt="Maintain Assessment Status" />
    </Frame>
  </Step>

  <Step title="Send test notification">
    Click on the `menu` icon, then select integration app to proceed.

    <Frame>
      <img alt="Edit/View Assessment/Background check Status ID" />
    </Frame>

    A pop-up will appear, allowing users to select the assessments test.

    <Frame>
      <img alt="Edit/View Assessment/Background check Status ID" />
    </Frame>

    Select the assessments test, wait a few seconds for the `Send` button to become enabled, and then click `Send` to dispatch the notification.

    <Frame>
      <img alt="Edit/View Assessment/Background check Status ID" />
    </Frame>

    Once the assessments test notification is successfully sent, users can view the test status on the candidate’s profile as shown below:

    <Frame>
      <img alt="Edit/View Assessment/Background check Status ID" />
    </Frame>
  </Step>
</Steps>

## ATS User Experience Customisation

<Steps>
  <Step title="To Update the result via unified api">
    Utilise the following endpoints to update the results:

    * [Assessment Update Result](https://docs.stackone.com/ats/api-reference/assessments/results/update-assessments-result)
    * [Background Check Update Result](https://docs.stackone.com/ats/api-reference/background-checks/results/update-background-check-result)

    Utilise the following endpoint to get metadata to update the result of the assessment or background check:

    * [Connector Meta Information](https://docs.stackone.com/platform/api-reference/connectors/get-connector-meta-information) with the provider key `recruitee` for model `assessments/results.update` or `background_checks/results.update`

    <div>
      | Fields (when provided) | User sees in Recruitee                                               |
      | ---------------------- | -------------------------------------------------------------------- |
      | Result URL             | Visible as an **Open** link                                          |
      | Score's Value          | Visible as a percentage alongside the package's name.                |
      | Result Status          | Visible within the score's tooltip, if the user hovers on the score. |
    </div>
  </Step>

  <Step title="How will the results of the assessment/background check be displayed to the user in Recruitee?">
    Navigate to the candidate profile, where you will see the updated results along with the score from the previously sent test. This information will be available once the candidate has completed the assessment and background check.

    <Frame>
      <img alt="View Assessment/Background check Updated Results" />
    </Frame>
  </Step>
</Steps>

## Testing Checklist

✅  **Provider Setup:**

* Once the integration is approved/published by Recruitee, it is visible in the [Recruitee Marketplace](https://marketplace.tellent.com) under Assessments or Background Checks categories.

✅  **StackOne Configuration:**

* Selected `Public + Partner API` as the Authentication Type.
* Package's List Endpoint URL is correct.
* Package's List Endpoint response is as expected according to the following endpoint's response:
  * [List Assessments Packages](https://docs.stackone.com/ats/api-reference/assessments/packages/list-assessments-packages)
  * [List Background Check Packages](https://docs.stackone.com/ats/api-reference/background-checks/packages/list-background-check-packages)
* Valid partner codename and other details, as mentioned <a href="#stackone-configuration">here</a>.

✅  **ATS User Enablement:**

* Valid `External Trigger Token` to activate the partner integration.
* Once activated, the integration will be available for selection under the candidate's profile.

✅  **Create a Webhook**

* Added a webhook for Recruitee and enabled it with the events such as: `Assessment Order` or `Background Check Order`.
* Valid webhook URL to receive assessment/background check notifications.

✅  **ATS User Experience:**

* Once activated, the integration will be available for selection under the candidate's profile.
* If you have configured the Package's List Endpoint URL, a list of packages is visible in the dropdown field when the user initiates sending the test to the candidate.
* If you have configured a Static Package ID, a single package is visible in the dropdown field when the user initiates sending the test to the candidate.
* Select a package, click `Send Test`, and send the webhook. A `Pending` icon as a status along with the assessment package name will appear if the notification has been sent.

✅  **Update Result**

* Success response from the update result endpoint.
* Updated result details to Recruitee’s UI.

## Troubleshooting

<div>
  | Symptom                                                                                          | Likely cause                                                                                                                                                                                                                             | Fix                                                                                                                                                                                                                                                                                                                      |
  | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  | Unable to find your Integration app in [Recruitee Marketplace](https://marketplace.tellent.com). | Recruitee Partner Integration is not published/approved.                                                                                                                                                                                 | Contact Recruitee support for partnership status.                                                                                                                                                                                                                                                                        |
  | Integration partner app not visible on candidate profile to select.                              | **•** Integration app is not activated. <br /><br /> **•** Invalid External Trigger Token.                                                                                                                                               | **•** Activate your integration app from marketplace. <br /><br /> **•** Provide valid External Trigger Token.                                                                                                                                                                                                           |
  | Getting error message on pop-up when user selects the integration app to send the test.          | **•** Package's List Endpoint URL or Static Package ID is missing from StackOne Configuration. <br /><br /> **•** Invalid response getting from the Package's List Endpoint URL. <br /><br /> **•** Invalid Package's List Endpoint URL. | **•** Add Static Package ID if you don't have Package's List Endpoint URL. <br /><br /> **•** Response format should be expected as mentioned in the [StackOne Configuration](#stackone-configuration). <br /><br /> **•** Check Package's List Endpoint URL implementation at your end. <br /><br /> **•** Verify CORS. |
  | Test notification is not received.                                                               | **•** Invalid webhook URL. <br /><br /> **•** Incorrect webhook events are enabled.                                                                                                                                                      | **•** Verify webhook URL. <br /><br /> **•** Enable expected events as mentioned in the [StackOne Configuration](#stackone-configuration).                                                                                                                                                                               |
  | Unable to update result.                                                                         | Invalid payload format.                                                                                                                                                                                                                  | Check Connector Meta API endpoint for payload format.                                                                                                                                                                                                                                                                    |
</div>

For persistent issues, contact StackOne support with detailed error logs and configuration information.


# Bullhorn Recruitment Cloud - Salesforce Integration
Source: https://docs.stackone.com/integration-guides/ats/salesforce-bullhorn

Technical guide for integrating with Bullhorn Recruitment Cloud using Salesforce REST API and SOQL queries

## Overview

The StackOne Salesforce-Bullhorn integration uses Salesforce's REST API and SOQL queries to provide unified access to Bullhorn data. This guide covers the technical implementation details for integration partners.

## API Architecture

The integration uses **Salesforce's REST API** and [**SOQL queries**](https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql.htm) to retrieve and manipulate data from Bullhorn instances running on Salesforce.

## Custom Fields

Custom fields are supported for the **Application**, **Candidate**, and **Job** models.

### Account-Specific Custom Fields

When connecting a Bullhorn account, customers can specify which model fields they wish to include as custom fields in their Account connection screen.

<Frame>
  <img alt="Salesforce Bullhorn Custom Fields Account Configuration" />
</Frame>

### Unified Custom Fields

Request additional fields for unified custom fields (not account-specific) using the `proxy[fields]` query parameter:

```bash theme={null}
curl "https://api.stackone.com/unified/ats/candidates?proxy[fields]=TR1__Reject_Action__c,TR1__Submit_And_Email_Action__c" \
  -u "$STACKONE_API_KEY:" \
  -H "x-account-id: YOUR_ACCOUNT_ID"
```

Example fields:

* `TR1__Reject_Action__c`
* `TR1__Submit_And_Email_Action__c`

## Custom Filtering

Apply additional SOQL filters using the `proxy[filter]` query parameter:

```bash theme={null}
curl "https://api.stackone.com/unified/ats/applications?proxy[filter]=ai_Job_Match_Score__c%20%3E%3D%203" \
  -u "$STACKONE_API_KEY:" \
  -H "x-account-id: YOUR_ACCOUNT_ID"
```

This enables filtering on custom fields and additional data points beyond the standard unified API capabilities.

## Applications

The integration supports two application types:

### Application Types

1. **TR1\_\_Application\_\_c** - Shortlist Application
2. **TR1\_\_Job\_Board\_Application\_\_c** - Job Board Application

<Info>
  Applications queries will include both TR1\_\_Application\_\_c and TR1\_\_Job\_Board\_Application\_\_c models by default.
</Info>

To only include Applications of the TR1\_\_Job\_Board\_Application\_\_c type, set the filter\[stage] parameter to "null".

### Moving Applications

Convert a **Job Board Application** to a **Shortlist Application** using the move endpoint:

**Endpoint:** `PATCH /ats/applications/:id/move`

**Request:**

```json theme={null}
{
  "interview_stage_id": "Application"
}
```

This operation:

* Creates a new `TR1__Application__c` record
* Returns the new record's ID
* Updates the `TR1__ATS_Stage__c` field

  Only Job Board Applications (**TR1\_\_Job\_Board\_Application\_\_c**) can be moved to Shortlist Applications. The **interview\_stage\_id** value must be set to **"Application"**. Other **TR1\_\_Application\_\_c** records can also be moved using this endpoint, but the behavior is restricted.

### Passthrough Support

The `passthrough` property is supported for:

* **Application Move endpoint** (`PATCH /ats/applications/:id/move`)
* **Application Update endpoint** (`PATCH /ats/applications/:id`)

Use the passthrough parameter to update additional Salesforce properties not covered by the unified API:

```json theme={null}
{
  "interview_stage_id": "Application",
  "passthrough": {
    "Custom_Field__c": "value",
    "Another_Field__c": 123
  }
}
```

## Best Practices

1. **Test custom fields** before implementing in production to ensure the field names are correct
2. **Validate SOQL filter syntax** using the `proxy[filter]` parameter against Salesforce documentation
3. **Handle errors gracefully** when moving applications - not all application types support this operation

## Related Resources

* [ATS API Reference](/ats/api-reference)
* [Using Passthrough Query Parameters](/guides/using-the-passthrough-query-parameters)
* [Unified API Error Codes and Troubleshooting](/guides/unified-api-error-codes-and-troubleshooting-guide)


# SAP SuccessFactors Assessment through a third-party vendor
Source: https://docs.stackone.com/integration-guides/ats/sapsuccessfactors-assessment

Learn how to set up and configure a third-party assessment vendor in SAP SuccessFactors for integration with StackOne.

## Overview

This document outlines the procedure for configuring a third-party assessment vendor within SAP SuccessFactors and integrating it with StackOne.
The guide details adding a vendor, uploading assessment packages, and customising job requisition templates to include assessment fields.
Finally, it explains how to set up external event notifications to trigger assessments and utilise the StackOne Unified API to return the results to SAP SuccessFactors.

## Partner Requirements

There are no formal partnership requirements for assessment vendor integration with SAP SuccessFactors.
You must have access to the Provisioning Account to create an integration user and grant the necessary permissions.

### Required Permissions for Vendor Assessment in SAP SuccessFactors

<Note>
  If you don't have access to the Provisioning Account, contact your SAP SuccessFactors customer and ask them to follow the instructions below to grant you the necessary permissions.
</Note>

In the Provisioning Account, create an **Integration User** and assign the following permissions to enable effective collaboration with third-party assessment vendors
and SAP SuccessFactors.

<AccordionGroup>
  <Accordion title="Recruiting Assessment Permissions">
    * SFAPI Retrieve Assessment Order Permission
    * SFAPI Update Assessment Report Permission
  </Accordion>

  <Accordion title="Permissions Required for Assessment Configurations">
    * Ensure recruiting users are granted the Manage Assessment Vendors permission.
    * In *Provisioning > Company Settings*, enable the following options:
      * Enable Assessment Integration
      * SFAPI
      * Enable SFAPI Web Services
    * Grant the following permissions to the SFAPI integration user:
      * Access to Event Notification Subscription
      * Retrieve Assessment Order
      * Update Assessment Report
    * Enable Assessment Integration (which requires Candidate Workbench) from the Provisioning Account.
  </Accordion>
</AccordionGroup>

## Provider Side Setup

### Add the integration user to the SAP SuccessFactors API login exceptions list

Navigate to *Admin Center > Tools > Password & Login Policy Settings > Set API Login Exceptions*, then **Add** the following information:

* **Username:** Select the SFAPI integration user.
* **Maximum Password Age (days):** Set to -1.
* **IP Address Restrictions:** Specify the designated IP addresses or address range for the integration.

### Add your vendor and upload the assessment vendor packages

<Steps>
  <Step title="Add a Vendor for Assessment">
    Go to *Manage Assessment Vendors*, Click `Export` to download the CSV file. Add your vendor with a unique `clientId` and mark it as active by entering `Y` in the active column.

    <Frame>
      <img alt="Add a Vendor" />
    </Frame>

    Select an updated file to import the Assessment Vendor List into SAP SuccessFactors.

    <Frame>
      <img alt="Upload a file of vendor" />
    </Frame>
  </Step>

  <Step title="Upload the assessment vendor packages">
    <Note>
      If you do not have access to the Provisioning Account, please contact your SAP SuccessFactors customer. Provide them with the CSV file of the assessment vendor package and request that they upload it. Alternatively, you can ask them to follow the instructions below for uploading the file.
    </Note>

    Assessment vendor packages will be uploaded from *Provisioning Account > Managing Recruiting > Import/Export Assessment Vendor Packages*. Prepare a CSV file with the required columns and values, as illustrated in the image.

    * **vendorId:** Identifies the assessment vendor (must be the same as the `clientId`).
    * **packageCode:** Identifies an assessment package for the order.
    * **shortName:** A shortened name for the package, for use on the candidate summary page.
    * **Label:** The language in which the assessment is displayed.

    <Frame>
      <img alt="Import/Export Assessment Vendor Packages" />
    </Frame>

    Choose the file to import the assessment vendor packages list into SAP SuccessFactors.
  </Step>
</Steps>

### Create a subscriber and set up an external event

<Steps>
  <Step title="Create a subscriber">
    Go to the *Event Notification Subscription* page. Under the *Subscriber* tab, add a subscriber using your `Subscriber Id` and `Client Id`.
    Note that your `clientId` must match the one uploaded with your vendor's name in the previous <a href="#add-your-vendor-and-upload-the-assessment-vendor-packages">step</a>.

    <Frame>
      <img alt="Create a Subscriber" />
    </Frame>

    <Note>
      If multiple subscribers are created using the same `client_id`, an error will occur when sending the assessment notification.
    </Note>
  </Step>

  <Step title="Set up an external event to receive notifications">
    Navigate to the *External Event* tab and click `+ Add New` to add a new external event.

    <Frame>
      <img alt="Add New external event" />
    </Frame>

    Select the values for the specified fields:

    * **Event Type:** Select `rcm_assessment_alert_v2`.
    * **Subscriber:** Select the subscriber you created in the previous <a href="#add-your-vendor-and-upload-the-assessment-vendor-packages">step</a>.
    * **Protocol:** Select `SOAP_OVER_HTTP_HTTPS`.
    * **Endpoint URL:** Enter the endpoint URL, including the `externalTriggerToken` query parameter, which will be used to receive assessment order requests.

    ```plaintext theme={null}
    https://api.stackone.com/external-trigger/sapsuccessfactors_ats?externalTriggerToken=<external-trigger-token>
    ```

    <Info>
      The endpoint URL must include the query parameter `externalTriggerToken`, which you will receive from the StackOne Connection Hub. This token verifies requests from SAP SuccessFactors for that specific vendor.
    </Info>

    <Note>
      To obtain the **External Trigger Token**, please follow these steps:

      * [StackOne Configuration](#stackone-configuration)
      * [ATS User Enablement](#ats-user-enablement)
    </Note>

    * **Authentication:** Select `NO`.

    <Frame>
      <img alt="Setup external event" />
    </Frame>

    Click `Save` to save the configuration for the external event.
  </Step>
</Steps>

### Manage fields for the Job Requisition template

<Steps>
  <Step title="Go to Manage Templates">
    Navigate to *Admin Center* and search for *Manage Templates*.

    <Frame>
      <img alt="Navigate to Job Requisition template" />
    </Frame>

    Navigate to the *Recruiting Management* tab, select *Job Requisition*, and choose the template in use for the specific job requisition, such as `Standard Job Requisition`.

    <Accordion title="How to Locate the Job Requisition Template Name">
      Go to *Recruiting* and select any specific job requisition.

      <Frame>
        <img alt="Specific Job Requistion" />
      </Frame>

      Click on the `i` icon to view the Job Requisition Template.

      <Frame>
        <img alt="JR Info" />
      </Frame>
    </Accordion>

    <Frame>
      <img alt="Standard Job Requisition" />
    </Frame>
  </Step>

  <Step title="Add assessment field in template">
    To add or update fields, navigate to the specific *Job Requisition Template*, select `Fields Defined`, and then click `Add Standard Field`.

    * **Field-ID:** Select `assessment`.
    * **Field Type:** Select `Derived`.
    * **Field Label:** Enter a relevant label, such as `Assessment association`.
    * **Field Description:** Enter a relevant description, such as `Assessmentasso`.
    * **Required:** Select the checkbox to make this field mandatory, as per your requirement.

    <Accordion title="You can also specify the standard `assessment` field using the Job Requisition XML.">
      <Warning>
        This approach should only be used if you have permission to upload the Job Requisition template via an XML file; otherwise, you can add the fields manually and click `Publish`.
      </Warning>

      ```XML theme={null}
        <field-definition id="assessment" type="derived" required="true" custom="false">
          <field-label><![CDATA[Assessment assocication]]></field-label>
          <field-description><![CDATA\[Assessmentasso]]></field-description>
        </field-definition>
        <field-permission type="write">
          <description><![CDATA[job code permissions]]></description>
          <role-name><![CDATA[R]]></role-name>
          <status><![CDATA[pre-approved]]></status>
          <field refid="assessment"/>
        </field-permission>
      ```
    </Accordion>

    <Frame>
      <img alt="Add a field from JR field template" />
    </Frame>

    <Info>
      This `assessment` field enables the user to select a specific assessment to associate with the job requisition.
    </Info>
  </Step>
</Steps>

### Manage the permissions for the assessment feature

<Steps>
  <Step title="Go to Manage Templates">
    To add or update feature permissions, navigate to the specific *Job Requisition Template* > *General Settings* > *Application Status Configuration*, select `Feature Permissions Defined`, and then click `Add Feature Permission`.

    * **Feature Permission Description:** Enter a relevant description.
    * **Feature Permission Type:** Select `assessmentIntegration`.
    * **Feature Permission Role Name:** Select `All`.
    * **Feature Permission Status:** Select the talent pipeline stage at which you want to initiate the assessment.

    <Info>
      You can add multiple feature permissions for `assessmentIntegration` for a specific talent pipeline stage.
    </Info>

    <Accordion title="You can also specify the feature permissions for `assessmentIntegration` using the Job Requisition XML.">
      <Warning>
        This approach should only be used if you have permission to upload the Job Requisition template via an XML file; otherwise, you can add the permissions manually and click `Publish`.
      </Warning>

      ```XML theme={null}
        <feature-permission type="assessmentIntegration">
          <description><\!\[CDATA\[Operators with below roles can see Assessment detail report for the applicant when the application is in Scheduled Status\]\]></description>
          <role-name><\!\[CDATA\[S\]\]></role-name>
          <role-name><\!\[CDATA\[T\]\]></role-name>
          <role-name><\!\[CDATA\[O\]\]></role-name>
          <role-name><\!\[CDATA\[R\]\]></role-name>
          <role-name><\!\[CDATA\[G\]\]></role-name>
          <status><\!\[CDATA\[Scheduled\]\]></status>  // You can choose any stage from the options provided; for this document, we have selected "Scheduled."
        </feature-permission>
        <feature-permission type="assessmentIntegration">
          <description><\!\[CDATA\[Operators with below roles can see Assessment detail report for the applicant when the application is in New Application Status \]\]></description>
          <role-name><\!\[CDATA\[S\]\]></role-name>
          <role-name><\!\[CDATA\[T\]\]></role-name>
          <role-name><\!\[CDATA\[O\]\]></role-name>
          <role-name><\!\[CDATA\[R\]\]></role-name>
          <role-name><\!\[CDATA\[G\]\]></role-name>
          <status><\!\[CDATA\[Default\]\]></status>
        </feature-permission>
      ```
    </Accordion>

    After adding the feature permissions, click `Done`, and then click `Publish` to save your changes.

    <Frame>
      <img alt="Add feature permission from the JR template" />
    </Frame>

    <Tip>
      When an assessment is configured in `Default` or `New Applicant`, it is triggered when the candidate applies for the job. Immediately after applying and passing any prescreening questions, the candidate will be redirected to an assessment vendor site. After completing the assessment, the candidate is redirected back to the career site.
    </Tip>
  </Step>
</Steps>

### Assessment fields under Job Requisition

<Steps>
  <Step title="Go to Job Requisition">
    Access the specific *Job Requisition* that uses the template where you configured the Assessment in the previous <a href="#manage-the-permissions-for-the-assessment-feature">steps</a>. Hover over the job requisition title to open the Actions menu, then select `View or Edit Requisition`.

    <Frame>
      <img alt="Go to Actions menu" />
    </Frame>

    To add an Assessment association row, click the `Add More Assessments` link and select the details below.

    <Frame>
      <img alt="add a row of fields" />
    </Frame>

    The following fields will be visible on the job requisition:

    * **Status:** Select the stage where you have set up the assessment integration feature, as described in the previous <a href="#manage-the-permissions-for-the-assessment-feature">step</a>.
    * **Vendor:** Select the vendor, for example, `STACK_ASSESSMENT_TEST`.
    * **Assessment:** Select the specific assessment package to be sent to the candidate.
    * **Email Template:** Select the email template to be sent to the candidate once the assessment is triggered.

    <Accordion title="If the fields are not visible after you have added them and set the permissions in the previous steps">
      Navigate to *Admin Center* and search for `OData API Metadata Refresh and Export`.

      <Frame>
        <img alt="OData API Metadata Refresh and Export" />
      </Frame>

      Click the `Refresh` button next to Cache.

      <Frame>
        <img alt="Refresh button" />
      </Frame>
    </Accordion>
  </Step>
</Steps>

## StackOne Configuration

<Steps>
  <Step title="Enable SAP SuccessFactors in StackOne">
    Go to the ATS category on the *Integrations* page and enable SAP SuccessFactors.

    <Frame>
      <img alt="Activate SAP SuccessFactors" />
    </Frame>
  </Step>

  <Step title="Complete the configuration form">
    Fill out the required fields in the **SAP SuccessFactors - Configuration** modal:

    * **Authentication Type** - Select `Client Application`.
    * **Integration Category** - Select `Assessments`.

    <Frame>
      <img alt="Activate SAP SuccessFactors" />
    </Frame>

    Click `Confirm` or `Save Changes` to enable the SAP SuccessFactors integration, allowing end-users to link their accounts via the StackOne Connector Hub.
  </Step>

  <Step title="Add a Webhook">
    Navigate to the *Webhooks* page, click `Add webhook`, and complete the form:

    * **Name:** Enter a recognisable name for your webhook.
    * **URL:** Enter the URL where the webhook will send notifications of enable events.

    <Frame>
      <img alt="Add Webhook form" />
    </Frame>

    Enable the webhook event from the `Events` tab for Assessment, such as `Assessment Order`.

    <Frame>
      <img alt="Select webhook events" />
    </Frame>
  </Step>
</Steps>

## ATS User Enablement

<Note>
  Users can obtain an **External Trigger Token** if they wish to use a different token from another StackOne project.
  Users can then update the `externalTriggerToken` in the query parameter of the endpoint URL. Please refer to <a href="#create-a-subscriber-and-set-up-an-external-event">these</a> steps.
</Note>

Navigate to the *Accounts* page or the StackOne Connector Hub to link your SAP SuccessFactors account with StackOne.

<Frame>
  <img alt="Link SAP SuccessFactors account" />
</Frame>

You will receive the `External Trigger Token`, which must be passed as a query parameter with the endpoint URL when setting up the external event in SAP SuccessFactors, as outlined in the previous <a href="#create-a-subscriber-and-set-up-an-external-event">steps</a>.

<Frame>
  <img alt="External Trigger Token" />
</Frame>

## ATS User Experience

<Steps>
  <Step title="Go to Job Requisition">
    Navigate to the relevant *Job Requisition*, hover over the requisition title to open the Actions menu, and then select `View or Edit Requisition`.

    <Frame>
      <img alt="Go to Actions menu" />
    </Frame>

    Users will see the option to add an Assessment association row. By clicking `Add More Assessments`, users can select the details.

    <Frame>
      <img alt="add a row of fields" />
    </Frame>

    The following fields will be visible to users on the job requisition to associate an assessment with it:

    * **Status:** Select the stage where you have set up the assessment integration feature, as described in the previous <a href="#manage-the-permissions-for-the-assessment-feature">step</a>.
    * **Vendor:** Select the vendor, for example, `STACK_ASSESSMENT_TEST`.
    * **Assessment:** Select the specific assessment package to be sent to the candidate.
    * **Email Template:** Select the email template to be sent to the candidate once the assessment is triggered.

    <Accordion title="If fields are not visible after adding them and setting permissions in the above steps">
      Navigate to *Admin Center* and search for `OData API Metadata Refresh and Export`.

      <Frame>
        <img alt="OData API Metadata Refresh and Export" />
      </Frame>

      Click the `Refresh` button next to Cache.

      <Frame>
        <img alt="Refresh button" />
      </Frame>
    </Accordion>
  </Step>

  <Step title="Move candidate to the assessment-configured stage">
    Go to the `Candidates` tab located within the Job Requisition section.

    <Frame>
      <img alt="job requisition candidate tab" />
    </Frame>

    You will receive the list of candidates who applied for the job. Move candidates to the stage where you previously configured the assessment, as described in the <a href="#manage-the-permissions-for-the-assessment-feature">steps</a>.

    <Frame>
      <img alt="Job requisition talent pipeline" />
    </Frame>
  </Step>

  <Step title="Visibility of the Initiate Assessment option">
    <Warning>
      If you see the message below in the candidate's application, the assessment will not be sent.<br />

      ⚠️ **Non Applicant**<br />
      **This candidate has been forwarded to this job by \[recruiter] and added to this job but has not yet applied for it.**

      The assessment will only be sent to the candidate when they apply for the job.
    </Warning>

    The assessment will be sent to the candidate automatically when they are moved to the assessment-configured stage in the talent pipeline.

    <Frame>
      <img alt="Take Actions menu" />
    </Frame>

    <Info>
      The `Initiate Assessment` option under the `Take Actions` menu will only be visible if the assessment fails to send, allowing it to be re-initiated.
    </Info>
  </Step>
</Steps>

### Send the test to the candidate from SAP SuccessFactors

<Frame>
  <video />
</Frame>

<Note>
  Follow the [SAP SuccessFactors Assessment](https://hub.stackone.com/integration-configuration-concepts/ats/sapsuccessfactors-assessment) guide for instructions on how to send the test from SAP SuccessFactors.
</Note>

### User experience after the assessment has been sent

When an assessment is sent to the candidate, the user will see the `Initiated` status along with the Assessment Package in the Assessment Portlet on the candidate's application.

<Frame>
  <img alt="Job Requisition Fields" />
</Frame>

## ATS User Experience Customisation

<Steps>
  <Step title="Update the result via Unified API">
    Utilise the following endpoints to update the results:

    * [Assessment Update Result](https://docs.stackone.com/ats/api-reference/assessments/results/update-assessments-result)

    Utilise the following endpoint to get metadata to update the result of the assessment:

    * [Connector Meta Information](https://docs.stackone.com/platform/api-reference/connectors/get-connector-meta-information) with the provider key `sapsuccessfactors_ats` for the `assessments/results.update` model.

    #### User sees the updated results with different conditions of the assessment in SAP SuccessFactors

    |                                                                                                          |
    | -------------------------------------------------------------------------------------------------------- |
    | When the result is `completed` with all details        <br /> <img alt="completed with all details" />   |
    | When the result is `completed` without other details   <br /> <img alt="completed without score" />      |
    | When the result does not include a Result URL          <br /> <img alt="completed without result url" /> |
  </Step>
</Steps>

## Testing Checklist

✅  **Provider Setup:**

* You have all the necessary permissions mentioned in the [Partner Requirements](#partner-requirements) section.
* A vendor for Assessment with a unique `clientId` has been added with an active `Y` status.
* The vendor's assessment packages have been uploaded with a valid `vendorId`.
* A subscriber has been created with a unique `Subscriber Id` and a valid `Client Id` (same as `vendorId`).
* An external event has been created with the correct and valid endpoint URL, including a valid `externaltriggerToken` in the query parameter.
* The `assessment` field has been added to the Job Requisition template with the necessary permissions.
* The feature permission for `assessmentIntegration` has been granted to the job requisition template.
* The `Add More Assessments` link and Assessment fields are visible to users during the creation/editing of the Job Requisition, as mentioned in <a href="#ats-user-experience">this</a> step.

✅  **StackOne Configuration:**

* The integration category `Assessments` is selected.

✅  **ATS User Activation:**

* A valid `externalTriggerToken` is provided in the query parameter along with the endpoint URL.

✅  **Create a Webhook:**

* A webhook for SAP SuccessFactors has been added and enabled with the `Assessment Order` event.
* A valid webhook URL has been added to receive assessment notifications.

✅  **ATS User Experience:**

* The `Assessment` stage is visible in the talent pipeline for the job requisition.
* The `Add More Assessments` link and Assessment fields are visible to users during the creation/editing of the Job Requisition, as mentioned in <a href="#ats-user-experience">this</a> step.
* After sending the assessment to a candidate, the user can see the `Initiated` status along with the Assessment Package in the Assessment Portlet on the candidate's application.

✅  **Update Result:**

* A success response is received from the update result endpoint.
* The updated result details are visible in the SAP SuccessFactors UI.

## Troubleshooting

<div>
  | Symptom                                                                                                           | Likely Cause                                                                                                                                                                                                                                                         | Fix                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
  | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Unable to access some of the navigations necessary for configuration.                                             | **•** Insufficient permissions. <br /><br /> **•** The logged-in account is not an Admin account.                                                                                                                                                                    | **•** Ensure the account has the <a href="#partner-requirements">necessary permissions</a>. <br /><br /> **•** Log in with an Admin account.                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
  | The `Add More Assessments` link and Assessment fields are not visible when creating/editing the Job Requisition.  | **•** Fields are not configured in the Job Requisition template. <br /><br /> **•** Fields do not have the necessary permissions in the Job Requisition template. <br /><br /> **•** The OData API cache has not been refreshed after adding fields and permissions. | **•** Add the `assessment` field and its permissions in the Job Requisition template. <br /> Please refer to the following sections: <br />- <a href="#manage-fields-for-the-job-requisition-template">Manage fields for the Job Requisition template</a>. <br />- <a href="#manage-the-permissions-for-the-assessment-feature">Manage permissions for the assessment feature</a>. <br />- <a href="#if-the-fields-are-not-visible-after-you-have-added-them-and-set-the-permissions-in-the-previous-steps">Refresh the OData API cache</a>.                                                          |
  | Packages are not available to select from the `Assessment` field when creating/editing the Job Requisition.       | **•** The assessment vendor package list has not been uploaded. <br /><br /> **•** Invalid `clientId` or `vendorId`.                                                                                                                                                 | **•** Upload the assessment vendor packages list from the Provisioning Account. <br /><br /> **•** Ensure the `clientId` and `vendorId` are valid.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
  | The `Initiate Assessment` option is not visible under the `Take Actions` menu within the candidate's application. | **•** The user does not have the necessary permissions to initiate assessments. <br /><br /> **•** The `Initiated Assessment` button will only be visible if the assessment initiation fails when moving the candidate to the configured assessment stage.           | **•** Add the Assessment feature permission to the Job Requisition template. Please refer to <a href="#manage-the-permissions-for-the-assessment-feature">this</a> section.                                                                                                                                                                                                                                                                                                                                                                                                                           |
  | **•** Error when sending the assessment. <br /><br /> **•** Test notification not received.                       | **•** Insufficient permissions. <br /><br /> **•** Multiple subscribers with same `client_id`. <br /><br /> **•** Invalid Endpoint URL or other configurations under External Event. <br /><br /> **•** Invalid External Trigger Token.                              | **•** Add the Assessment feature permission to the Job Requisition template. Please refer to <a href="#manage-the-permissions-for-the-assessment-feature">this</a> section. <br /><br /> **•** To add a subscriber, please provide a unique `client_id`. For instructions, visit <a href="#create-a-subscriber-and-set-up-an-external-event">Create a Subscriber</a>. <br /><br /> **•** Verify the Endpoint URL with all other valid configurations, as mentioned <a href="#create-a-subscriber-and-set-up-an-external-event">here</a>. <br /><br /> **•** The External Trigger Token must be valid. |
  | Unable to update the result.                                                                                      | Invalid payload format.                                                                                                                                                                                                                                              | Check the [Connector Meta Information](https://docs.stackone.com/platform/api-reference/connectors/get-connector-meta-information) endpoint for the correct payload format.                                                                                                                                                                                                                                                                                                                                                                                                                           |
  | The result URL shows an error when opened.                                                                        | The result URL may have expired or is private.                                                                                                                                                                                                                       | Ensure you add public or signed URLs; verify CORS and expiry.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
</div>

For persistent issues, contact StackOne support with detailed error logs and configuration information.


# SAP SuccessFactors Background Check Integration
Source: https://docs.stackone.com/integration-guides/ats/sapsuccessfactors-background-check

Learn how to set up and configure the Background Check integration in SAP SuccessFactors to integrate with StackOne.

## Overview

This document provides a comprehensive, step-by-step guide for integrating SAP SuccessFactors with StackOne for background checks.
It covers enabling the `Background Check Vendor` option, configuring integration templates in SAP SuccessFactors, mapping the required
fields, and setting up permissions and picklists. The guide also details how to activate the integration in StackOne, obtain the necessary
tokens, and ensure users can initiate and view background checks directly within the SAP SuccessFactors user interface.

## Partner Requirements

There is no formal or explicit partnership requirement with SAP SuccessFactors for this integration. However, you must have administrative privileges with the necessary permissions to access various features in SAP SuccessFactors.

You will need the following mandatory permissions to access and utilise the **Integration Center** for modelling and executing the integration:

* **Admin access to MDF OData API**
* **Access to Integration Center**
* **Access to non-Secured Objects**

## Provider Side Setup

### Enable the Other Background Check Vendor option

<Steps>
  <Step title="Background Check Central Configuration">
    Go to the *Admin Center* and search for *Background Check Central*

    <Frame>
      <img alt="Search for BC Central" />
    </Frame>

    Enable Background Check in Recruiting and choose `Other Background Check Vendor`.

    <Frame>
      <img alt="Enable Background Check in Recruiting" />
    </Frame>
  </Step>
</Steps>

### Select the type of integration template for the external background check

<Steps>
  <Step title="Go to Integration Center">
    Navigate to the *Admin Center* and search for *Integration Center*.

    <Frame>
      <img alt="Go to Integration Center" />
    </Frame>

    To view the list of available integrations, click on `My Integrations`.

    <Frame>
      <img alt="My Integrations" />
    </Frame>
  </Step>

  <Step title="Select the Type of Integration Center Template">
    Click the `+ Create` button and select *More Integration Types* to access the list of available integration types.

    <Frame>
      <img alt="Select More Integration Types" />
    </Frame>

    Select the following values from the modal:

    * **Application/UI** for **Trigger Type**
    * **SuccessFactors** for **Source Type**
    * **REST** for **Destination Type**
    * **JSON** for **Format**

    Click the `Create` button.

    <Frame>
      <img alt="Select correct values from the Modal" />
    </Frame>

    Use the search box to find the entity called `JobApplicationBackgroundCheckRequest`, and then select it from the search results.

    <Frame>
      <img alt="Search for JobApplicationBackgroundCheckRequest" />
    </Frame>
  </Step>
</Steps>

### Create and configure an integration template for background checks

<Steps>
  <Step title="Options Step">
    Enter the name of the integration, then click the `Next` button to proceed with further configuration steps. You may also click the `Save` button to save the current step's configuration.

    <Frame>
      <img alt="Select More Integration Types" />
    </Frame>
  </Step>

  <Step title="Configure Fields Step">
    Click the `+` button > *Insert Sibling Element*, then click on the inserted element to open a prompt where you can enter the name of the element.

    <Info>
      Please refer to the mapping listed <a href="#please-follow-the-mapping-below-to-receive-the-correct-order-notification">here</a>.
    </Info>

    <Frame>
      <img alt="Select option to map fields" />
    </Frame>

    Click the `+` button > *Add Child Element* for the added element, then click on the inserted element to open a prompt where you can enter the name of the child element.

    <Frame>
      <img alt="Select option to map child fields" />
    </Frame>

    To set the association for the added element, click on the `Set as Associated Field` icon.

    <Frame>
      <img alt="Open Modal to select association" />
    </Frame>

    Choose the specific fields to map, which can be found in the *Entity Tree View*.

    <Frame>
      <img alt="Open Modal to select association" />
    </Frame>

    Select the field and click on the `Change Association` button.

    <Frame>
      <img alt="Click on the change association" />
    </Frame>

    You will notice that the association has been updated for the data field.

    <Frame>
      <img alt="Updated data field association" />
    </Frame>

    Map the properties of the data fields to their corresponding properties in the OData API.

    <Accordion title="Please follow the mapping below to receive the correct order notification">
      | Expected properties of data fields                | To | Corresponding properties in the OData API entity                  |
      | ------------------------------------------------- | -- | ----------------------------------------------------------------- |
      | backgroundCheckInfo/requestId                     | -> | requestId                                                         |
      | backgroundCheckInfo/bgiAccountId                  | -> | jobApplication/jobRequisition/bgiAccountId/id                     |
      | backgroundCheckInfo/packageId                     | -> | jobApplication/jobRequisition/packageId/id                        |
      | backgroundCheckInfo/packageExternalCode           | -> | jobApplication/jobRequisition/packageId/externalCode              |
      | backgroundCheckInfo/packageLocaleLabel            | -> | jobApplication/jobRequisition/packageId/localeLabel               |
      | createdByUserInfo/userId                          | -> | createdByUserNav/userId                                           |
      | createdByUserInfo/firstName                       | -> | createdByUserNav/firstName                                        |
      | createdByUserInfo/lastName                        | -> | createdByUserNav/lastName                                         |
      | createdByUserInfo/email                           | -> | createdByUserNav/email                                            |
      | createdByUserInfo/jobRole                         | -> | createdByUserNav/jobRole                                          |
      | createdDateTime                                   | -> | createdDateTime                                                   |
      | lastModifiedDateTime                              | -> | lastModifiedDateTime                                              |
      | orderStatus                                       | -> | orderStatus                                                       |
      | responseCode                                      | -> | responseCode                                                      |
      | responseDetail                                    | -> | responseDetail                                                    |
      | vendorCode                                        | -> | vendorCode                                                        |
      | vendorOrderNo                                     | -> | vendorOrderNo                                                     |
      | applicationInfo/applicationId                     | -> | jobApplication/applicationId                                      |
      | applicationInfo/appStatusName                     | -> | jobApplication/jobAppStatus/appStatusName                         |
      | jobRequisitionInfo/jobReqId                       | -> | jobApplication/jobReqId                                           |
      | jobRequisitionInfo/externalTitle                  | -> | jobApplication/jobRequisition/jobReqLocale/externalTitle          |
      | jobRequisitionInfo/hiringManager/usersSysId       | -> | jobApplication/jobRequisition/hiringManager/usersSysId            |
      | jobRequisitionInfo/hiringManager/firstName        | -> | jobApplication/jobRequisition/hiringManager/userNav/firstName     |
      | jobRequisitionInfo/hiringManager/lastName         | -> | jobApplication/jobRequisition/hiringManager/userNav/lastName      |
      | jobRequisitionInfo/hiringManager/email            | -> | jobApplication/jobRequisition/hiringManager/userNav/email         |
      | jobRequisitionInfo/hiringManager/operatorRole     | -> | jobApplication/jobRequisition/hiringManager/operatorRole          |
      | jobRequisitionInfo/hiringManagerTeam/usersSysId   | -> | jobApplication/jobRequisition/hiringManagerTeam/usersSysId        |
      | jobRequisitionInfo/hiringManagerTeam/firstName    | -> | jobApplication/jobRequisition/hiringManagerTeam/userNav/firstName |
      | jobRequisitionInfo/hiringManagerTeam/lastName     | -> | jobApplication/jobRequisition/hiringManagerTeam/userNav/lastName  |
      | jobRequisitionInfo/hiringManagerTeam/email        | -> | jobApplication/jobRequisition/hiringManagerTeam/userNav/email     |
      | jobRequisitionInfo/hiringManagerTeam/operatorRole | -> | jobApplication/jobRequisition/hiringManagerTeam/operatorRole      |
      | candidateInfo/candidateId                         | -> | jobApplication/candidate/candidateId                              |
      | candidateInfo/firstName                           | -> | jobApplication/candidate/firstName                                |
      | candidateInfo/lastName                            | -> | jobApplication/candidate/lastName                                 |
      | candidateInfo/primaryEmail                        | -> | jobApplication/candidate/primaryEmail                             |
      | candidateInfo/contactEmail                        | -> | jobApplication/candidate/contactEmail                             |
    </Accordion>

    <Frame>
      <img alt="After mapping will look like" />
    </Frame>
  </Step>

  <Step title="Response Fields Step">
    Click on the `Switch to Field Mapping View` option,

    <Frame>
      <img alt="Change the mapping view" />
    </Frame>

    Click the `+` button and select the `JobApplicationBackgroundCheckRequest` entity. Then click `Add` and proceed by clicking the `Next` button.

    <Frame>
      <img alt="After adding will look like this response mapping" />
    </Frame>
  </Step>

  <Step title="Filter and Sort Step">
    You do not need to set anything on the Filter and Sort step. Simply click the `Next` button.

    <Frame>
      <img alt="Change the mapping view" />
    </Frame>
  </Step>

  <Step title="Destination Settings Step">
    Select the option for `REST Server Settings` and enter the following details:

    * **Connection Name:** You may choose any name you prefer.

      * **REST API URL:** This is the endpoint URL provided by StackOne, which will be used to receive background check order requests.

      ```plaintext theme={null}
      https://api.stackone.com/external-trigger/sapsuccessfactors_ats
      ```

      * **Authentication Type:** Select `Basic Authentication` from the dropdown menu.
      * **Username:** Enter the `External Trigger Token` that you will receive from the `StackOne Connector Hub` during the connection.

      <Note>
        To obtain the **External Trigger Token**, follow these steps:

        * [StackOne Configuration](#stackone-configuration)
        * [ATS User Enablement](#ats-user-enablement)
      </Note>

    * **Password:** This field can be left empty.

    * **HTTP Method:** Choose the `POST` method under REST Operation Settings.

    Click the `Next` button to proceed.

    <Frame>
      <img alt="Change the mapping view" />
    </Frame>
  </Step>

  <Step title="Review and Run Step">
    Review the template structure in the *Review and Run* step. To save it, select the `Save` option. After creation, the template will run in the background, so there is no need to click `Run Now`.

    <Frame>
      <img alt="Review and Run" />
    </Frame>

    <Info>
      You can access the logs by clicking on the `Last Run Time` link.
    </Info>

    You can confirm the integration by returning to *Integration Center* > *My Integrations*.
  </Step>
</Steps>

### Create Vendor from Recruiting External Vendor

<Steps>
  <Step title="Go to Manage Data">
    Navigate to *Manage Data* and select `Recruiting External Vendor` from the *Create New* dropdown.

    <Frame>
      <img alt="Recruiting External Vendor" />
    </Frame>

    Enter the External Code, Vendor Name, and select `Background Check` as the Integration Type from the dropdown menu. Click `Save` to create the vendor.

    <Warning>
      `External Code` refers to a text string that serves as a code for the background check vendor. The OData API entities use this value to facilitate communication between the third-party vendor and SAP SuccessFactors. If this information is not entered correctly, certain integration scenarios may fail to function properly.
    </Warning>

    <Frame>
      <img alt="Enter all required details of Recruiting External Vendor" />
    </Frame>
  </Step>
</Steps>

### Create Recruiting Vendor Integration Mapping

<Steps>
  <Step title="Go to the Manage Data">
    Navigate to *Manage Data* and select `Recruiting Vendor Integration Mapping` from *Create New* dropdown

    <Frame>
      <img alt="Recruiting Vendor Integration Mapping" />
    </Frame>

    Complete the following fields:

    * **External Code:** Enter a unique identifier code.
    * **Vendor Name:** Select your vendor name from the dropdown menu created in the previous step.
    * **Integration Name:** Choose your integration name from the dropdown menu.
    * **Default Integration:** Select `Yes`.
    * **Hours Before User Can Reinitiate:** This field currently has no functionality in SAP SuccessFactors. You may enter `0`.

      <Frame>
        <img alt="Enter all required details of Recruiting Vendor Integration Mapping" />
      </Frame>

    Click `Save` to save the mapping between the vendor and the integration.

    <Info>
      Only one `Recruiting Vendor Integration Mapping` can be active at a time. To activate the selected vendor integration for the instance, choose `Yes` in the **Default Integration** field. Additionally, ensure that `No` is selected for all other Recruiting Vendors you may have created.
    </Info>
  </Step>
</Steps>

### Manage fields for the Job Requisition template

<Steps>
  <Step title="Go to Manage Templates">
    Navigate to *Admin Center* and search for *Manage Templates*.

    <Frame>
      <img alt="Navigate to Job Requisition template" />
    </Frame>

    Go to the *Recruiting Management* tab, select *Job Requisition*, and choose the template in use for the relevant job requisition, such as `Standard Job Requisition`.

    <Accordion title="How to Locate the Job Requisition Template Name">
      Go to *Recruiting* and select any specific job requisition.

      <Frame>
        <img alt="Specific Job Requisition" />
      </Frame>

      Click on the `i` icon to view the Job Requisition Template.

      <Frame>
        <img alt="JR Info" />
      </Frame>
    </Accordion>

    <Frame>
      <img alt="Standard Job Requisition" />
    </Frame>
  </Step>

  <Step title="Add bgiAccountId & packageId fields in template">
    Add the following fields, which you will receive in the order request:

    * **bgiAccountId:** This field allows you to create multiple accounts with a single third-party background check vendor. It enables users to select which account to use.
    * **packageId:** This field allows users to choose the package they wish to associate with a specific job requisition.

      <Accordion title="You can specify the standard fields `bgiAccountId` and `packageId` using the Job Requisition XML as well.">
        <Warning>
          This approach should only be used if you have permission to upload the Job Requisition template via an XML file; otherwise, you can manually add the fields and click the `Publish` button.
        </Warning>

        ```XML theme={null}
          <field-definition id="bgiAccountId" type="picklist" required="false" custom="false"> 
            <field-label><![CDATA[Account ID]]></field-label>
            <field-description><![CDATA[Account ID]]></field-description> 
            <picklist-id>accountId</picklist-id> 
          </field-definition>

          <field-definition id="packageId" type="picklist" required="false" custom="false">
            <field-label><![CDATA[packageId]]></field-label>
            <field-description><![CDATA[package]]></field-description>
            <picklist-id>packageId</picklist-id>
          </field-definition>
        ```
      </Accordion>

      <Frame>
        <img alt="Add two fields from JR field template" />
      </Frame>

      In the next step, update the permissions to ensure the fields are visible during Job Requisition creation or updates.

      <Note>
        The fields `bgiAccountId` and `packageId` will only be accessible for Job Requisitions that utilise a specific Job Requisition template where these fields are configured.
      </Note>
  </Step>
</Steps>

### Manage the permissions for the fields added to the Job Requisition template

<Steps>
  <Step title="Go to Manage Templates">
    To add or update field permissions, navigate to the relevant Job Requisition Template, select `Field Permissions Defined`, and then click `Add Field Permission` in the modal.

    * **Field Permission Description:** Enter any description.
      * **Field Permission Type:** Select `Write Permission`.
      * **Field Permission Role Name:** Select `Recruiter`.
      * **Field Reference ID:** Select the `bgiAccountId` and `packageId` fields.
      * **Field Permission Status:** Select `All` or `pre-approved` from the dropdown menu.

    After adding the fields, click `Publish` to save your changes.

    <Frame>
      <img alt="Add field permissions from the JR template" />
    </Frame>

    Once the permissions have been updated, the fields will be visible in the Job Requisition during creation or editing.
  </Step>
</Steps>

### Grant Background Check Initiate Permission

<Note>
  Recruiters must have the necessary permissions to initiate background checks.
</Note>

Go to the specific *Job Requisition Template* > *Template Settings* > *Application Status Configuration* and add the feature permission block for background check to the job requisition template.

<Frame>
  <img alt="Apply Updates" />
</Frame>

Alternatively, you can add permissions via the Job Requisition template XML file:

```XML theme={null}
<feature-permission type="backgroundCheck">
    <description><![CDATA[R can launch Background Check during statuses with screening category.]]></description>
    <role-name><![CDATA[T]]></role-name>
    <role-name><![CDATA[O]]></role-name>
    <role-name><![CDATA[R]]></role-name>
    <role-name><![CDATA[S]]></role-name>
    <status><![CDATA[Background Check]]></status>
</feature-permission>
```

Once the `Background Check Initiate` permission is assigned, the user will be able to execute "Application/UI" or "Event-based" integrations.

### Add background check accounts from the PickList Center

<Steps>
  <Step title="Go to background check accounts">
    <Info>
      You can create multiple accounts with a single third-party background check vendor. All accounts added in this picklist will be available for users to select as the Background Check Account under the Job Requisition details.
    </Info>

    Go to *Admin Center* and search for `PickList Center`.

    <Frame>
      <img alt="Navigate to PickList Center" />
    </Frame>

    Search for `bgiAccountId`.

    <Frame>
      <img alt="Search for bgiAccountId" />
    </Frame>
  </Step>

  <Step title="Add New Accounts">
    Click on `bgiAccountId`. This will take you to the Picklist Values page, where you can add different `Background Check Accounts`.

    <Frame>
      <img alt="Add new accounts for background check" />
    </Frame>
  </Step>
</Steps>

### Add background check packages from the PickList Center

<Steps>
  <Step title="Go to the packages">
    Go to *Admin Center* and search for `PickList Center`.

    <Frame>
      <img alt="navigate to Picklist center" />
    </Frame>

    Search for `packageId`.

    <Frame>
      <img alt="Search for packageId" />
    </Frame>
  </Step>

  <Step title="Add New Packages">
    Click on `packageId` to go to the Picklist Values page, where you can add different `Background Check Packages`.

    <Frame>
      <img alt="Add new Packages" />
    </Frame>

    <Info>
      All packages added in this picklist will be available for users to select as the Background Check Package to associate with Job Requisitions.
    </Info>
  </Step>
</Steps>

### Include a Background Check stage in the Talent Pipeline

<Warning>
  You may skip this step if users already have a separate `Background Check` stage in the talent pipeline for the Job Requisition.
</Warning>

<Steps>
  <Step title="Go to Applicant Status Configuration">
    Go to *Admin Center* and search for `Edit Applicant Status Configuration`. Select the specific Applicant Status Set currently in use for the job requisition, such as the `Standard Status Set`.

    <Frame>
      <img alt="Navigate to Applicant Status Configuration" />
    </Frame>

    This will take you to the page for the `Standard Status Set`.

    <Frame>
      <img alt="Direct to status set page" />
    </Frame>
  </Step>

  <Step title="Edit Applicant Status Set configurations">
    Locate the `Background Check` stage, edit it, and select `none` from the `Status Group` dropdown. This will make the Background Check visible as a separate stage in the Job Requisition's Talent Pipeline.

    <Frame>
      <img alt="Edit Applicant Status Set configurations" />
    </Frame>

    Click the `Save and Finish` button to save your changes.

    <Frame>
      <img alt="Save and finish" />
    </Frame>
  </Step>

  <Step title="Where can you verify the added stage">
    Navigate to *Job Requisition* > *Candidates*. At the top, you will see the updated talent pipeline.

    <Frame>
      <img alt="Where can you verify the added stage" />
    </Frame>

    You can now move candidates to the Background Check stage.
  </Step>
</Steps>

### Background Check fields visibility under the Job Requisition

<Steps>
  <Step title="Go to Job Requisition">
    Navigate to the relevant *Job Requisition*, hover over the requisition title to open the Actions menu, and then select `View or Edit Requisition`.

    <Frame>
      <img alt="Go to Actions menu" />
    </Frame>

    Both *Account ID* and *Package ID* fields will be visible, allowing the user to select the account and package to associate the background check with the job.

    <Accordion title="If fields are not visible after adding fields & permissions in the above steps">
      Navigate to *Admin Center* and search for `OData API Metadata Refresh and Export`

      <Frame>
        <img alt="OData API Metadata Refresh and Export" />
      </Frame>

      Click the `Refresh` button next to Cache.

      <Frame>
        <img alt="Refresh button" />
      </Frame>
    </Accordion>

    <Frame>
      <img alt="Both fields are visible" />
    </Frame>
  </Step>

  <Step title="Visibility of Initiate Background Check option">
    The `Initiate Background Check` option will be visible to users under the `Take Actions` menu within the candidate's application.

    <Note>
      If the `Initiate Background Check` option is not visible, please ensure that the user has been granted the necessary permissions to initiate background checks as outlined in the previous <a href="#grant-background-check-initiate-permission">step</a>.
    </Note>

    <Frame>
      <img alt="Take Actions menu" />
    </Frame>
  </Step>
</Steps>

## StackOne Configuration

<Steps>
  <Step title="Enable SAP SuccessFactors in StackOne">
    Go to the ATS category on the *Integrations* page and enable SAP SuccessFactors.

    <Frame>
      <img alt="Activate SAP SuccessFactors" />
    </Frame>
  </Step>

  <Step title="Complete the configuration form">
    Fill out the required fields in the **SAP SuccessFactors - Configuration** model:

    * **Authentication Type:** Select `Client Application`.
    * **Integration Category:** Select `Background Checks`.

    <Frame>
      <img alt="Activate SAP SuccessFactors" />
    </Frame>

    Click `Confirm` or `Save Changes` to enable the SAP SuccessFactors integration, allowing end users to link their accounts via the StackOne Connector Hub.
  </Step>

  <Step title="Add a Webhook">
    Navigate to the *Webhooks* page, click `Add webhook`, and complete the form:

    * **Name:** Enter a recognisable name for your webhook.
    * **URL:** Enter the URL where the webhook will send notifications of enable events.

      <Frame>
        <img alt="Add Webhook form" />
      </Frame>

      Enable webhook events from the `Events` tab for Background Check, such as `Background Check Order`.

      <Frame>
        <img alt="Select webhook events" />
      </Frame>
  </Step>
</Steps>

## ATS User Enablement

Navigate to the *Accounts* page or the StackOne Connector Hub to link your SAP SuccessFactors account with StackOne.

<Frame>
  <img alt="Link SAP SuccessFactors account" />
</Frame>

You will receive the `External Trigger Token`, which must be entered as the username during the `Destination Settings` step under <a href="#create-and-configure-an-integration-template-for-background-checks">configure an integration template</a> in SAP SuccessFactors.

<Frame>
  <img alt="External Trigger Token" />
</Frame>

## ATS User Experience

<Steps>
  <Step title="Go to Job Requisition">
    Navigate to the relevant *Job Requisition*, hover over the requisition title to open the Actions menu, and then select `View or Edit Requisition`.

    <Frame>
      <img alt="Go to Actions menu" />
    </Frame>

    Select values for the *Account ID* and *Package ID* fields. Click the `Save Changes` button.

    <Accordion title="If fields are not visible after adding fields & permissions in the above steps">
      Navigate to *Admin Center* and search for `OData API Metadata Refresh and Export`.

      <Frame>
        <img alt="OData API Metadata Refresh and Export" />
      </Frame>

      Click the `Refresh` button next to Cache.

      <Frame>
        <img alt="Refresh button" />
      </Frame>
    </Accordion>

    <Frame>
      <img alt="Both fields are visible" />
    </Frame>
  </Step>

  <Step title="Move candidate within the Talent Pipeline">
    Navigate to the *Candidates* tab. Select the candidate, then choose the `Move Candidate` option from the Take Action menu.

    <Frame>
      <img alt="Go to Talent Pipeline" />
    </Frame>

    Choose `Background Check` from the dropdown menu, then click `Apply Updates` to move the candidate forward.

    <Frame>
      <img alt="Apply Updates" />
    </Frame>
  </Step>

  <Step title="Visibility of Initiate Background Check option">
    The `Initiate Background Check` option will be visible to users under the `Take Actions` menu within the candidate's application.

    <Frame>
      <img alt="Take Actions menu" />
    </Frame>
  </Step>
</Steps>

### Send the test to the candidate from SAP SuccessFactors

<Frame>
  <video />
</Frame>

<Note>
  Follow the [SAP SuccessFactors Background Check](https://hub.stackone.com/integration-configuration-concepts/ats/sapsuccessfactors-background-check) guide for instructions on how to send the test from SAP SuccessFactors.
</Note>

### User experience after the background check has been sent

When a user sends a background check to a candidate, they will see the `Request Submitted` status along with the background check portlet in the candidate's application.

<Frame>
  <img alt="Job Requisition Fields" />
</Frame>

## ATS User Experience Customisation

<Steps>
  <Step title="Update the result via Unified API">
    Utilise the following endpoints to update the results:

    * [Background Check Update Result](https://docs.stackone.com/ats/api-reference/background-checks/results/update-background-check-result)

    Utilise the following endpoint to get metadata to update the result of the background check:

    * [Connector Meta Information](https://docs.stackone.com/platform/api-reference/connectors/get-connector-meta-information) with the provider key `sapsuccessfactors_ats` for model `background_checks/results.update`

    <div>
      | Fields (when provided) | User sees in SAP SuccessFactors                                            | Comments                                      |
      | ---------------------- | -------------------------------------------------------------------------- | --------------------------------------------- |
      | Result                 | Final Status will be visible corresponding to the `Background Check` label | Result enum values from Meta API result field |
      | Result Url             | Visible as a View Report link corresponding to the `View Status` label     |                                               |
    </div>
  </Step>

  <Step title="How are background check results displayed to the user in SAP SuccessFactors?">
    When a user opens a candidate's application, they will see the updated results with the background check status from the previously sent background check under the Background Check portlet.

    <Frame>
      <img alt="Job Requisition Fields" />
    </Frame>
  </Step>
</Steps>

## Testing Checklist

✅  **Provider Setup:**

* You have all the necessary permissions mentioned in the [Partner Requirements](#partner-requirements) section.
* The `Other Background Check Vendor` option is enabled from Background Check Central as mentioned in [Enable the Other Background Check Vendor option](#enable-the-other-background-check-vendor-option) step.
* A valid integration template is selected for the external background check.
* Valid configurations exist in the integration template for background checks, with a valid StackOne endpoint URL and valid External Trigger Token.
* A vendor has been created from Recruiting External Vendor with `Background Check` as the Integration Type.
* A Recruiting Vendor Integration Mapping has been created with the vendor and integration from the previous steps.
* The `bgiAccountId` and `packageId` fields have been added to the Job Requisition template with the necessary permissions.
* Accounts have been added in the `bgiAccountId` picklist and packages in the `packageId` picklist.
* A `Background Check` stage has been added to the talent pipeline for the job requisition, if not already present.
* The feature permission for `Background Check Initiate Permission` has been granted to the job requisition template.
* Account ID and Package ID fields are visible to users during creation/editing of the Job Requisition.
* The `Initiate Background Check` option is visible to users under the `Take Actions` menu within the candidate’s application, as mentioned in <a href="#grant-background-check-initiate-permission">this</a> step.

✅  **StackOne Configuration:**

* The integration category `Background Checks` is selected.

✅  **ATS User Activation:**

* A valid `External Trigger Token` is entered as the username during the `Destination Settings` step under <a href="#create-and-configure-an-integration-template-for-background-checks">configure an integration template</a>.
* A single `Recruiting Vendor Integration Mapping` is activated to use the background check integration. Please refer <a href="#create-recruiting-vendor-integration-mapping">this</a> step.

✅  **Create a Webhook:**

* A webhook for SAP SuccessFactors has been added and enabled with the `Background Check Order` event.
* A valid webhook URL has been added to receive background check notifications.

✅  **ATS User Experience:**

* The `Background Check` stage is visible in the talent pipeline for the job requisition.
* Account ID and Package ID fields are visible to users during creation/editing of the Job Requisitions.
* The `Initiate Background Check` option is visible to users under the `Take Actions` menu within the candidate’s application, as mentioned in <a href="#grant-background-check-initiate-permission">this</a> step.
* After sending the background check to a candidate, the user can see the `Request Submitted` status along with the background check portlet in the candidate's application.

✅  **Update Result:**

* A success response is received from the update result endpoint.
* Updated result details are visible in SAP SuccessFactors's UI.

## Troubleshooting

<div>
  | Symptom                                                                                                             | Likely cause                                                                                                                                                                                                                                               | Fix                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
  | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Unable to access Integration Center.                                                                                | **•** Insufficient permissions. <br /><br /> **•** Logged-in account is not an Admin account.                                                                                                                                                              | **•** Ensure the account has the <a href="#partner-requirements">necessary permissions</a>. <br /><br /> **•** Log in with an Admin account.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
  | `Account ID` and `Package ID` fields are not visible during creation/editing of the Job Requisition.                | **•** Fields are not configured in the Job Requisition template. <br /><br /> **•** Fields do not have the necessary permissions in the Job Requisition template. <br /><br /> **•** OData API cache is not refreshed after adding fields and permissions. | **•** Add `bgiAccountId` and `packageId` field configurations in the Job Requisition template. Please refer <a href="#manage-fields-for-the-job-requisition-template">this</a>. <br /><br /> **•** Add the necessary permissions for both fields. Please refer <a href="#manage-the-permissions-for-the-fields-added-to-the-job-requisition-template">this</a>. <br /><br /> **•** Refresh the OData API cache from `OData API Metadata Refresh and Export`. Please refer <a href="#if-fields-are-not-visible-after-adding-fields-and-permissions-in-the-above-steps">this</a>. |
  | **Accounts** and **Packages** are not available to select during creation/editing of the Job Requisition.           | **•** No values are added in the `bgiAccountId` and `packageId` picklists.                                                                                                                                                                                 | **•** Add values in the `bgiAccountId` and `packageId` picklists from PickList Center. <br /> Please refer following sections: <br /> - <a href="#add-background-check-accounts-from-the-picklist-center">Add background check accounts from the PickList Center</a>. <br /> - <a href="#add-background-check-packages-from-the-picklist-center">Add background check packages from the PickList Center</a>.                                                                                                                                                                    |
  | Background Check stage is not visible in the talent pipeline for the Job Requisition.                               | **•** Background Check stage is not added in the talent pipeline. <br /><br /> **•** Background Check stage is added but not configured properly.                                                                                                          | **•** Add a Background Check stage in the talent pipeline for the job requisition. Please refer <a href="#include-a-background-check-stage-in-the-talent-pipeline">this</a>. <br /><br /> **•** Ensure the correct configurations for the Background Check stage, please refer <a href="#include-a-background-check-stage-in-the-talent-pipeline">this</a>.                                                                                                                                                                                                                     |
  | `Initiate Background Check` option is not visible under the `Take Actions` menu within the candidate's application. | **•** User does not have the necessary permissions to initiate background checks. <br /><br /> **•** Background Check feature permission is not added to the Job Requisition template.                                                                     | **•** Add the Background Check feature permission to the Job Requisition template. Please refer <a href="#grant-background-check-initiate-permission">this</a>.                                                                                                                                                                                                                                                                                                                                                                                                                 |
  | Error when sending the background check.                                                                            | **•** Invalid REST API URL. <br /><br /> **•** Invalid External Trigger Token. <br /><br /> **•** Invalid configurations in the integration template for background checks.                                                                                | **•** Verify the REST API URL. <br /><br /> **•** The External Trigger Token should be valid. <br /><br /> **•** Ensure all configurations are correct for the background check integration template. Please refer <a href="#create-and-configure-an-integration-template-for-background-checks">this</a>.                                                                                                                                                                                                                                                                      |
  | Test notification is not received.                                                                                  | **•** Multiple `Recruiting Vendor Integration Mapping` records are activated for the Background Check integration. <br /><br /> **•** Invalid webhook URL. <br /><br /> **•** Incorrect webhook events are enabled.                                        | **•** Ensure only a single <a href="#create-recruiting-vendor-integration-mapping">Recruiting Vendor Integration Mapping</a> is activated for the expected Background Check integration. <br /><br /> **•** Verify the webhook URL. <br /><br /> **•** Enable the expected events as mentioned in the [StackOne Configuration](#stackone-configuration).                                                                                                                                                                                                                        |
  | Test notification data is not correct.                                                                              | Invalid mappings of fields in the integration template for background checks.                                                                                                                                                                              | Ensure all field mappings are correct for the background check integration template. Please refer <a href="#create-and-configure-an-integration-template-for-background-checks">this</a>.                                                                                                                                                                                                                                                                                                                                                                                       |
  | Unable to update result.                                                                                            | Invalid payload format.                                                                                                                                                                                                                                    | Check the [Connector Meta Information](https://docs.stackone.com/platform/api-reference/connectors/get-connector-meta-information) endpoint for the payload format.                                                                                                                                                                                                                                                                                                                                                                                                             |
  | Result URL shows an error when opened.                                                                              | The result URL may have expired or is private.                                                                                                                                                                                                             | Ensure you add public or signed URLs; verify CORS and expiry.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
</div>

For persistent issues, contact StackOne support with detailed error logs and configuration information.


# SAP SuccessFactors Permission Configuration
Source: https://docs.stackone.com/integration-guides/ats/sapsuccessfactors-permission-configuration

Configuration of Permissions in SAP SuccessFactors

<Warning>
  The following guidance assumes you have Admin privileges for your SAP SuccessFactors account.
</Warning>

## Permission Settings

### Step 1: Role Configuration

<Steps>
  <Step title="Log in to SuccessFactors as an administrator" />

  <Step title="Navigate to Admin Center." />

  <Step title="In the Tools search bar, search for Manage Permission Roles." />

  <Step title="Choose an existing role or create a new role." />

  <Step title="If you choose a new role, on the Role Details page, enter the role name.">
    On the `Permission Role Details` page, enter the `Role Name` and `Description` in the first section.
  </Step>
</Steps>

### Step 2: Permission Configuration For Role

<Steps>
  <Step title="Select the Permission">
    On the `Permission Role Details` page, click the `Permissions` button in the second section.
  </Step>

  <Step title="Select the Module">
    Select the `module` for which you want to configure permissions. For example, to configure permissions for `Recruiting entities` such as Applications, Jobs, and Assessments, you can select `Recruiting Permissions`.
  </Step>

  <Step title="Select the Entity">
    On the left side of the page, you will find a list of all entities for which you can configure `read (view)` and `write (edit)` permissions.

    * Selecting the View checkbox allows users to read data from a specific entity using the OData API.
    * Selecting the Edit checkbox grants users permission to write data to that entity using the Write OData API.
  </Step>

  <Step title="Click on Done" />
</Steps>

### Step 3: Assign Role

<Steps>
  <Step title="Assign the Role">
    On the Permission Role Details page, click the `Assignments` tab in `Manage Permission Roles` to assign this role to a group of users.
  </Step>

  <Step title="Select the Group">
    Click the `Add Role Assignment` button, select the `Role`, and then click the `Next` button.
  </Step>

  <Step title="Select the Users">
    In the next tab, select the `Employees` or `Groups` to which you want to assign the role.
  </Step>

  <Step title="Click on Save">
    In the final step, click the `Save` button to save your changes.
  </Step>
</Steps>

### Step 4: Click the `Save Changes` button on the Permission Role Details page to save all changes.

<br />

<br />

## Required configuration for resource mapping via StackOne APIs

### ATS Resource and Permissions Configuration

To access the ATS OData APIs in Recruiting, ensure the following permissions are granted:

<AccordionGroup>
  <Accordion title="Applications">
    | Category               | Permission                                                                                                                                                                                                               |
    | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | Recruiting Permissions | `OData API Application Export`, `OData API Application Create`, `OData API Application Update`, `OData API Candidate Export`, `OData API Candidate Create`, `OData API Candidate Update`, `Candidate Tagging Permission` |
  </Accordion>

  <Accordion title="Applications > Documents">
    | Category                 | Permission                                                                                     |
    | ------------------------ | ---------------------------------------------------------------------------------------------- |
    | Recruiting Permissions   | `OData API Application Export`, `OData API Application Create`, `OData API Application Update` |
    | Manage Integration Tools | `OData API Attachment Export`, `OData API Attachment Import`                                   |
  </Accordion>

  <Accordion title="Applications > Notes">
    | Category               | Permission                                                                                                                           |
    | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
    | Recruiting Permissions | `OData API Application Export`, `OData API Application Create`, `OData API Application Update`, `OData API Application Audit Export` |
  </Accordion>

  <Accordion title="Applications > Offers">
    | Category               | Permission                                                                                              |
    | ---------------------- | ------------------------------------------------------------------------------------------------------- |
    | Recruiting Permissions | `OData API Offer Approval Export`, `OData API Offer Approval Create`, `OData API Offer Approval Update` |
  </Accordion>

  <Accordion title="Assessments">
    | Category               | Permission                                                                                     |
    | ---------------------- | ---------------------------------------------------------------------------------------------- |
    | Recruiting Permissions | `OData API Application Export`, `OData API Application Create`, `OData API Application Update` |
  </Accordion>

  <Accordion title="BackgroundChecks">
    | Category               | Permission                                                                                     |
    | ---------------------- | ---------------------------------------------------------------------------------------------- |
    | Recruiting Permissions | `OData API Application Export`, `OData API Application Create`, `OData API Application Update` |
  </Accordion>

  <Accordion title="Candidates">
    | Category               | Permission                                                                                                               |
    | ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
    | Recruiting Permissions | `OData API Candidate Export`, `OData API Candidate Create`, `OData API Candidate Update`, `Candidate Tagging Permission` |
  </Accordion>

  <Accordion title="Candidates > Notes">
    | Category               | Permission                                                                                                               |
    | ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
    | Recruiting Permissions | `OData API Candidate Export`, `OData API Candidate Create`, `OData API Candidate Update`, `Candidate Tagging Permission` |
  </Accordion>

  <Accordion title="Custom Field Definitions > Applications">
    | Category               | Permission                                                                                     |
    | ---------------------- | ---------------------------------------------------------------------------------------------- |
    | Recruiting Permissions | `OData API Application Export`, `OData API Application Create`, `OData API Application Update` |
  </Accordion>

  <Accordion title="Custom Field Definitions > Candidates">
    | Category               | Permission                                                                                                               |
    | ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
    | Recruiting Permissions | `OData API Candidate Export`, `OData API Candidate Create`, `OData API Candidate Update`, `Candidate Tagging Permission` |
  </Accordion>

  <Accordion title="Custom Field Definitions > Jobs">
    | Category               | Permission                                                                                     |
    | ---------------------- | ---------------------------------------------------------------------------------------------- |
    | Recruiting Permissions | `OData API Requisition Export`, `OData API Requisition Create`, `OData API Requisition Update` |
  </Accordion>

  <Accordion title="Interviews">
    | Category               | Permission                                                                                                  |
    | ---------------------- | ----------------------------------------------------------------------------------------------------------- |
    | Recruiting Permissions | `OData API Application Export`, `OData API Application Update`, `OData API Interview Central Create/Update` |
  </Accordion>

  <Accordion title="Job Postings">
    | Category               | Permission                                                                                     |
    | ---------------------- | ---------------------------------------------------------------------------------------------- |
    | Recruiting Permissions | `OData API Requisition Export`, `OData API Requisition Create`, `OData API Requisition Update` |
  </Accordion>

  <Accordion title="Jobs">
    | Category               | Permission                                                                                     |
    | ---------------------- | ---------------------------------------------------------------------------------------------- |
    | Recruiting Permissions | `OData API Requisition Export`, `OData API Requisition Create`, `OData API Requisition Update` |
  </Accordion>

  <Accordion title="Offers">
    | Category               | Permission                                                                                              |
    | ---------------------- | ------------------------------------------------------------------------------------------------------- |
    | Recruiting Permissions | `OData API Offer Approval Export`, `OData API Offer Approval Create`, `OData API Offer Approval Update` |
  </Accordion>

  <Accordion title="Department">
    | Category               | Permission                                                                                             |
    | ---------------------- | ------------------------------------------------------------------------------------------------------ |
    | MDF Foundation Objects | `Actions`, `View Current`, `View History`, `Create`, `Insert`, `Correct`, `Delete`, `Import`, `Export` |
  </Accordion>

  <Accordion title="Location">
    | Category                | Permission                                                                                             |
    | ----------------------- | ------------------------------------------------------------------------------------------------------ |
    | MDF Foundation Objects  | `Actions`, `View Current`, `View History`, `Create`, `Insert`, `Correct`, `Delete`, `Import`, `Export` |
    | Foundation Object Types | `View`, `Create`, `Insert`, `Correct`, `Delete`                                                        |
  </Accordion>
</AccordionGroup>


# SmartRecruiters Assessment or Background Check Integration
Source: https://docs.stackone.com/integration-guides/ats/smartrecruiters-assessment-or-background-check-integration

Learn how to set up and configure the SmartRecruiters integration for assessments and background checks

## Purpose & Scope

StackOne allows you to integrate with SmartRecruiters for Assessment and Background Check to receive webhook notifications whenever a user sends the test to a candidate, update the test result, and see the result on the candidate profile in SmartRecruiters. This guide covers the Assessments and Background Checks unified use case. For the end-to-end flow, see the [Unified Use Case](https://docs.stackone.com/ats/use-cases/assessment-flow) Overview.

This guide covers how you can set up/configure integration at SmartRecruiters and integrate with StackOne.

## Partnership Requirements

### SmartRecruiters Marketplace Partnership

To integrate with SmartRecruiters for assessments and background checks, you must apply to become a partner through the SmartRecruiters Marketplace:

* **Partnership Required**: Yes, formal partnership application required
* **Marketplace Application**: [SmartRecruiters Marketplace](https://marketplace.smartrecruiters.com/)
* **Plan Requirements**: Partnership approval required regardless of SmartRecruiters plan tier
* **Support Contact**: Available through marketplace partner portal after approval

### Application Process

<Steps>
  <Step title="Submit Partnership Application">
    1. Visit the [SmartRecruiters Marketplace](https://marketplace.smartrecruiters.com/)
    2. Click on `Get started` or `Join the Marketplace`
    3. Complete the partnership application form with your company details
  </Step>

  <Step title="Approval and Onboarding">
    Upon approval, you'll receive:

    * Access to SmartRecruiters Partner Portal
    * API credentials and documentation
    * Marketplace listing guidelines
    * Technical support contact information
  </Step>
</Steps>

<Warning>
  Partnership approval is mandatory before proceeding with the technical integration.
</Warning>

## Provider Side Setup

### SmartRecruiters Configuration

Once your application is listed on the SmartRecruiters Marketplace, no additional external setup is required on the provider side. End users will be able to and enable your integration directly from the marketplace and proceed with the configuration.
To allow end users to start the assessment flow, the assessment partner only needs to complete the StackOne Configuration. Once the StackOne configuration is completed, assessment users will be able to enable the integration from the marketplace and begin using it.

### SmartRecruiters API Documentation

For detailed API specifications, refer to:

* [SmartRecruiters Developer Documentation](https://developers.smartrecruiters.com/reference/apply-api)
* [SmartRecruiters API Reference](https://developers.smartrecruiters.com/reference)

## StackOne Configuration

<Warning>
  The assessment partner must complete the StackOne configuration before proceeding with the assessment users or initiating the assessment integration process. Otherwise, the integration will not be activated from the marketplace.The assessment partner must complete the StackOne configuration before assessment users can enable the integration from the marketplace. Otherwise, the integration will not be activated from the marketplace.
</Warning>

### Enable SmartRecruiters in StackOne Dashboard

<Steps>
  <Step title="Navigate to Integrations">
    1. Log into your StackOne Dashboard
    2. Navigate to the ATS category on the Integrations page
    3. Find and enable SmartRecruiters

    <Frame>
      <img alt="SmartRecruiters Integration Setup" />
    </Frame>
  </Step>

  <Step title="Complete Configuration Form">
    Fill in the SmartRecruiters Configuration form with the following details:

    * **Authentication Type**: Select `OAuth2 - Assessments/Background checks` for standard integration
    * **Partner Category**: Select `Assessment` or `Background Check` based on your integration type
    * **Partner Client ID**: Enter your SmartRecruiters `Client ID` from Partner Portal
    * **Partner Client Secret**: Enter your SmartRecruiters `Client Secret` from Partner Portal
    * **Package's List Endpoint URL**: Implement and provide an endpoint to StackOne that StackOne will use to retrieve the list of packages when the recruiter wants to send a test to a candidate.

    Implement the following POST endpoint:

    ```bash theme={null}
    curl --location 'https://your-domain.com/<route-to-the-post-endpoint>' \
    --header 'Content-Type: application/json' \
    --header 'x-stackone-signature: string' \
    --header 'Authorization: Basic <base64-encoded-api-key>' \
    --data '{
        "job_id": "49201091",
        "account_id": "456551489512493412",
        "provider": "teamtailor"
    }'
    ```

    The expected response of the POST endpoint (list of packages). Refer to:

    * [List Assessments Packages](https://docs.stackone.com/ats/api-reference/assessments/packages/list-assessments-packages)
    * [List Background Check Packages](https://docs.stackone.com/ats/api-reference/background-checks/packages/list-background-check-packages)

    Enter the endpoint into the designated field:

    ```plaintext theme={null}
    https://your-domain.com/<route-to-the-post-endpoint>
    ```

    * **Package ID**: If you do not have the Package List Endpoint URL, you can specify a particular package ID that will be visible to the recruiter when they wish to send the test to the candidate

    <DifferenceBetweenListEndpointAndStaticIdOfPackage />

    * **SmartRecruiters Supported Assessment Types**: Please select one of the assessment types supported by SmartRecruiters

    <Frame>
      <img alt="SmartRecruiters Configuration Form" />
    </Frame>
  </Step>

  <Step title="Save Configuration">
    Click `Confirm` or `Save Changes` to enable your OAuth APIs and allow end-users to link their SmartRecruiters accounts via the StackOne Hub.
  </Step>

  <Step title="Enable Webhook Events">
    Configure webhook notifications for the following events based on your selected integration category:

    * `assessment.created` - When a recruiter sends an assessment to a candidate
    * `background_check.created` - When a recruiter initiates a background check

    <Steps>
      <Step title="Add a Webhook">
        Navigate to the Webhooks page, click on `Add webhook`.

        <Frame>
          <img alt="Navigate to Webhooks" />
        </Frame>

        Fill out the form:

        * **Name**: Enter your webhook with a recognisable name
        * **URL**: Enter the URL where the webhook will send the notification of the enabled events

        <Frame>
          <img alt="Add Webhook Form" />
        </Frame>
      </Step>

      <Step title="Configure Event">
        Enable webhook events from the Events tab for Assessment & Background Check, such as Assessments Order & Background Check Order

        <Frame>
          <img alt="Configure Webhook Events" />
        </Frame>
      </Step>

      <Step title="Save Configuration">
        Click `Save` button to save your webhook config.

        <Frame>
          <img alt="Save Webhook Configuration" />
        </Frame>
      </Step>
    </Steps>
  </Step>
</Steps>

## ATS User Enablement

### User Activation Flow

<Steps>
  <Step title="Obtain External Trigger Token">
    Users get the External Trigger Token from StackOne:

    1. Navigate to the StackOne Hub
    2. Copy the external trigger token

    <Frame>
      <img alt="External Trigger Token" />
    </Frame>
  </Step>

  <Step title="Access SmartRecruiters Marketplace">
    Users access the SmartRecruiters Marketplace through:

    1. SmartRecruiters admin dashboard → `Settings` → `Apps and Integrations`

    <Frame>
      <img alt="Access Settings" />
    </Frame>

    <Frame>
      <img alt="Integration Page" />
    </Frame>
  </Step>

  <Step title="Select Integration">
    Navigate to specific integration from the list of available integrations in SmartRecruiters account.

    1. Search for your integration by name
    2. Click on your integration tile to view details

    <Frame>
      <img alt="Select Integration" />
    </Frame>
  </Step>

  <Step title="View Details">
    Review the integration details and click on `Connect`.

    <Frame>
      <img alt="View Integration Details" />
    </Frame>
  </Step>

  <Step title="Enable Integration">
    1. Review permissions
    2. Click `Allow and Continue` button

    <Frame>
      <img alt="Enable Integration" />
    </Frame>
  </Step>

  <Step title="Input external trigger token into form">
    Users will see a verification form where they need to enter their `External Trigger Token` received in the previous step along with their `Email Address`. After filling in the details, click the `Submit` button to verify and continue.

    <Frame>
      <img alt="Input External Trigger Token" />
    </Frame>
  </Step>

  <Step title="Verify Connection">
    Once submitted credentials are verified successfully, user will see a message on the top right corner of the screen that says: `StackOne Assessments is connected`.

    <Frame>
      <img alt="Integration Connected Successfully" />
    </Frame>
  </Step>
</Steps>

## ATS User Experience

This section covers how recruiters use the integration to send assessments or background checks to candidates.

SmartRecruiters supports two assessment delivery modes: <b>Ad-hoc</b> (manual per candidate) and <b>Auto Trigger</b> (auto‑triggered by workflow configuration).

### Ad-hoc Assessments

<Steps title="Ad-hoc Assessments">
  <Step title="Access Job Application">
    1. User logs into SmartRecruiters
    2. Navigates to `People`
    3. Selects a specific candidate profile

    <Frame>
      <img alt="User Configuration Form" />
    </Frame>
  </Step>

  <Step title="Initiate Assessment/Background Check">
    From the candidate profile, look for the assessment section.

    <Info>
      If a candidate has multiple jobs, the `Assessments` section won't appear directly on their profile. To access the assessments in this case, please follow these steps to navigate to the `Assessments` section for that candidate.

      <AccordionGroup>
        <Accordion title="How to navigate to Assessments section for candidates with multiple jobs">
          **Step 1: Navigate to Person profile**

          Navigate the `Person profile` and click on `Job` for which you want to add the assessment.

          <Frame>
            <img alt="Enable Integration" />
          </Frame>

          **Step 2: Find Assessments Section**

          Once you open the `Job` for the candidate, you will find the `Assessments section` there, specific to that particular job application.

          <Frame>
            <img alt="Input External Trigger Token" />
          </Frame>
        </Accordion>
      </AccordionGroup>
    </Info>

    Click `Order Assessments` button.

    <Frame>
      <img alt="Send Assessment Button" />
    </Frame>
  </Step>

  <Step title="Select Package">
    In the assessment form:

    1. **Select Assessment Partner**: Select your assessment partner
    2. **Select Package**: Choose from available test packages
    3. **Click Continue**: Click on continue button

    <Note>
      If a user selects multiple packages for a candidate, the assessment partner will receive multiple assessment orders.
    </Note>

    <Frame>
      <img alt="Package Selection Form" />
    </Frame>
  </Step>

  <Step title="Send to Candidate">
    1. Review the test details and candidate information
    2. Click `Send` button
    3. Candidate receives email notification with test link and instructions

    <Frame>
      <img alt="Package Selection Form" />
    </Frame>
  </Step>
</Steps>

### Auto Trigger Assessments

Configure an assessment that auto‑triggers when a candidate is added to a job or moved into the assessment stage:

<Steps title="Auto Trigger Assessments">
  <Step title="Open Settings">
    User opens the profile menu and selects `Settings`.

    <Frame>
      <img alt="Access Admin Settings" />
    </Frame>
  </Step>

  <Step title="Open Hiring Process">
    In `Settings`, user clicks `Hiring Process`.

    <Frame>
      <img alt="Access Hiring Process" />
    </Frame>
  </Step>

  <Step title="Select Hiring Process">
    User creates a `New Hiring Process` or selects `Default`, then clicks the `Edit` icon to modify it.

    <Frame>
      <img alt="Select Hiring Process Type" />
    </Frame>
  </Step>

  <Step title="Add step">
    User clicks `Add Step` and chooses `Skills Test` or any other `Stage` on which you want to configure the `Assessments`.

    <Frame>
      <img alt="Add Select Step" />
    </Frame>

    Once the user selects the step, it will be added to the hiring process.

    <Frame>
      <img alt="Selected Step" />
    </Frame>

    User can also add a `Custom Stage` by selecting the `Add Custom` button.

    <Frame>
      <img alt="Selected Step" />
    </Frame>

    Enter the name of the `Stage`.

    <Frame>
      <img alt="Selected Step" />
    </Frame>

    Once the user clicks the `Add` button, the step will be added to the hiring process.

    <Frame>
      <img alt="Selected Step" />
    </Frame>
  </Step>

  <Step title="Save Hiring Process">
    User clicks `Save Hiring Process` to persist changes.

    <Frame>
      <img alt="Save Hiring Process" />
    </Frame>
  </Step>

  <Step title="Add Assessment Entry">
    Inside the `Skills Test` step, user clicks the `Menu` icon and selects `Assessments`.

    <Frame>
      <img alt="Add Assessments" />
    </Frame>
  </Step>

  <Step title="Configure Assessment">
    User clicks `Configure`.

    <Frame>
      <img alt="Configure Assessments" />
    </Frame>

    User selects the `Assessment Partner`, `Assessment Type`, and `Assessment Package`, then clicks `Save`.

    <Frame>
      <img alt="Select Assessment Package Configuration" />
    </Frame>
  </Step>

  <Step title="Enable Auto-trigger">
    After saving, user returns to the `Config` page and enables the `Auto-triggered` toggle for the selected package.

    <Frame>
      <img alt="Enable Auto Trigger" />
    </Frame>
  </Step>

  <Step title="Add Candidate">
    User clicks the `+` icon (top right) and selects `Add Candidate`.

    <Frame>
      <img alt="Add Candidate" />
    </Frame>

    User may upload files/folders or add a candidate manually (example below):

    <Frame>
      <img alt="Manually Added Candidate" />
    </Frame>

    User completes the candidate form and clicks `Add Candidate`.

    <Frame>
      <img alt="Candidate Form" />
    </Frame>
  </Step>

  <Step title="Move Candidate to Assessment Stage">
    User opens `People`, selects the candidate.

    <Frame>
      <img alt="Select Candidate for Stage" />
    </Frame>

    Clicks `Convert` button under the `Applicant profile` section.

    <Frame>
      <img alt="Select Candidate for Stage" />
    </Frame>

    Clicks `Move Forward`, and chooses `Skills Test` under the `In Review` stage

    <Frame>
      <img alt="Select Assessment Stage" />
    </Frame>

    A checkmark appears on `Skills Test` once the assessment order is sent.

    <Frame>
      <img alt="Inline Stage Sent" />
    </Frame>
  </Step>
</Steps>

### User experience after test has been sent and results updated

<Steps>
  <Step title="User Experience after the assessment has been sent">
    When an assessment is sent to the candidate, the user will see the assessment status in the candidate's application profile.

    <Frame>
      <img alt="Assessment Sent Status" />
    </Frame>
  </Step>
</Steps>

## ATS User Experience Customisation

<Steps>
  <Step title="Update the result via Unified API">
    Utilise the following endpoints to update the results:

    * [Assessment Update Result](https://docs.stackone.com/ats/api-reference/assessments/results/update-assessments-result)
    * [Background Check Update Result](https://docs.stackone.com/ats/api-reference/background-checks/results/update-background-check-result)

    Utilise the following endpoint to get metadata to update the result of the assessment or background check:

    * [Connector Meta Information](https://docs.stackone.com/platform/api-reference/connectors/get-connector-meta-information) with the provider key `smartrecruiters` for model `assessments/results.update` or `background_checks/results.update`

    ### Payload to UI Mapping

    The following shows how different payload fields and conditions affect what users see in the SmartRecruiters UI when updating test results:

    <AccordionGroup>
      <Accordion title="result[pending]">
        **What users see in SmartRecruiters UI:** Grey icon, `Pending` status

        **Notes:** Shows test has been pending

        <Frame>
          <img alt="Pending Status" />
        </Frame>
      </Accordion>

      <Accordion title="result[in_progress]">
        **What users see in SmartRecruiters UI:** Yellow icon, `In Progress` status

        **Notes:** Shows ongoing test status

        <Frame>
          <img alt="In Progress Status" />
        </Frame>
      </Accordion>

      <Accordion title="result[completed]">
        **What users see in SmartRecruiters UI:** Green checkmark, `Completed` status

        **Notes:** Shows successful completion status

        <Frame>
          <img alt="Completed Status" />
        </Frame>
      </Accordion>

      <Accordion title="result[failed]">
        **What users see in SmartRecruiters UI:** Red icon, `Rejected` status

        **Notes:** Indicates test failure or rejection

        <Frame>
          <img alt="Rejected Status" />
        </Frame>
      </Accordion>

      <Accordion title="result[expired]">
        **What users see in SmartRecruiters UI:** Yellow icon, `Expired` status

        **Notes:** Shows test has expired without completion

        <Frame>
          <img alt="Expired Status" />
        </Frame>
      </Accordion>

      <Accordion title="score[value,min,max]">
        **What users see in SmartRecruiters UI:** Numerical score displayed prominently

        **Notes:** Value, min, and max are all required fields for score display.

        <Frame>
          <img alt="Score Value" />
        </Frame>
      </Accordion>

      <Accordion title="score[label]">
        **What users see in SmartRecruiters UI:** Custom score label or description

        **Notes:** Optional descriptive label for the score

        <Frame>
          <img alt="Score Label" />
        </Frame>
      </Accordion>

      <Accordion title="result_url & attachments[content_type,url]">
        **What users see in SmartRecruiters UI:** `Download Reports` section with file links

        **Notes:** Both content\_type and url fields are required to attach report documents. For result\_url, you only need to provide the report link in the result\_url field. Both types of documents will be displayed in the same section.

        <Frame>
          <img alt="Attachments" />
        </Frame>
      </Accordion>

      <Accordion title="summary">
        **What users see in SmartRecruiters UI:** Not currently visible in UI

        **Notes:** ***Optional field*** - Summary of the results.
      </Accordion>

      <Accordion title="start_date">
        **What users see in SmartRecruiters UI:** Not currently visible in UI

        **Notes:** ***Optional field*** - Assessment start timestamp (when the assessment was initiated)
      </Accordion>

      <Accordion title="submission_date">
        **What users see in SmartRecruiters UI:** Not currently visible in UI

        **Notes:** ***Optional field*** - Completion timestamp (when the assessment was submitted)
      </Accordion>
    </AccordionGroup>
  </Step>
</Steps>

## Testing Checklist

✅  **Partnership & Provider Setup:**

* Partnership application approved by SmartRecruiters Marketplace.
* Integration is listed and discoverable in SmartRecruiters Marketplace.

✅  **StackOne Configuration:**

* SmartRecruiters integration enabled in StackOne Dashboard.
* Authentication Type `OAuth2 - Assessments/Background checks` is selected.
* Partner Category (Assessment or Background Check) is correctly configured.
* Valid Partner Client ID and Client Secret from SmartRecruiters Partner Portal are provided.
* Package's List Endpoint URL is implemented and returning valid response format, or Static Package ID is configured.
* SmartRecruiters Supported Assessment Types are selected.

✅  **Webhook Configuration:**

* Webhook is created with valid URL.
* Correct webhook events are enabled (`assessment.created` or `background_check.created`).

✅  **ATS User Enablement:**

* External Trigger Token is successfully obtained from StackOne Connector Hub.
* StackOne account is connected successfully.
* Integration can be found and selected in SmartRecruiters Marketplace.
* Integration connection is successfully established after providing External Trigger Token and Email Address.
* Success message `StackOne Assessments is connected` is displayed.

✅  **ATS User Experience - Ad-hoc & Auto Trigger Assessments:**

* **Ad-hoc Assessments:**
  * `Order Assessment` button is visible on candidate profile.
  * Package selection dropdown displays available packages (from endpoint or static package).
  * Assessment order is successfully sent to candidate.
  * Assessment status updates are visible in candidate profile (Pending, In Progress, Completed, etc.).
* **Auto Trigger Assessments:**
  * Hiring Process is configured with Skills Test or Custom Stage.
  * Assessment is configured within the stage with correct partner and package.
  * Auto-triggered toggle is enabled for the assessment.
  * Assessment order is automatically triggered when candidate is moved to configured stage.
  * Assessment status updates are visible in candidate profile (Pending, In Progress, Completed, etc.).

✅  **Result Update:**

* Success response is received from the update result endpoint.
* Updated result status (pending, in\_progress, completed, failed, expired) is visible in SmartRecruiters UI.
* Score values (value, min, max) are displayed correctly when provided.
* Summary section displays rich text summary when provided.
* Result URL and attachments are accessible in the `Download Reports` section.

## Troubleshooting

<div>
  | Symptom                                                                                                                                                                                         | Likely Cause                                                                                                                                                                                                           | Fix                                                                                                                                                                                                                                                                                              |
  | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  | Integration not appearing in SmartRecruiters marketplace                                                                                                                                        | Partnership not approved or marketplace listing incomplete                                                                                                                                                             | Verify partnership status in SmartRecruiters Partner Portal. Complete marketplace listing requirements.                                                                                                                                                                                          |
  | `Order Assessment` button missing from candidate profile                                                                                                                                        | Integration not properly activated or insufficient permissions                                                                                                                                                         | Check integration status in SmartRecruiters Active Apps. Verify user has recruiter permissions.                                                                                                                                                                                                  |
  | Getting `List displays incomplete data. An error occurred while fetching one or more packages from partner. Click 'Reload' button to try to fetch packages again` on `Order Assessments` pop-up | Package's List Endpoint URL or Static Package ID is missing from StackOne Configuration. <br /><br /> Invalid response getting from the Package's List Endpoint URL. <br /><br /> Invalid Package's List Endpoint URL. | Add Static Package ID if you don't have Package's List Endpoint URL. <br /><br /> Response format should be expected as mentioned in the [StackOne Configuration](#stackone-configuration). <br /><br /> Check Package's List Endpoint URL implementation at your end. <br /><br /> Verify CORS. |
  | External Trigger Token field is not visible at StackOne Connector Hub                                                                                                                           | Selected Authentication Type is incorrect                                                                                                                                                                              | Select Authentication Type `OAuth - Assessments/Background Checks` instead                                                                                                                                                                                                                       |
  | Test notification is not received                                                                                                                                                               | Invalid webhook URL <br /><br /> Incorrect webhook events are enabled.                                                                                                                                                 | Verify webhook URL <br /><br /> Enable expected events as mentioned in the [StackOne Configuration](#stackone-configuration).                                                                                                                                                                    |
  | Unable to update result                                                                                                                                                                         | Invalid payload format                                                                                                                                                                                                 | Check [Connector Meta API](https://docs.stackone.com/platform/api-reference/connectors/get-connector-meta-information) endpoint for payload format.                                                                                                                                              |
  | Result URL or Attachment's URL showing error when opened.                                                                                                                                       | Added result URL can be expired or is private.                                                                                                                                                                         | Ensure to add public or signed URLs; verify CORS and expiry.                                                                                                                                                                                                                                     |
</div>


# Teamtailor Partner API
Source: https://docs.stackone.com/integration-guides/ats/teamtailor-partner-api

To activate the Teamtailor Partner API or Public + Partner API in StackOne for integrating your Teamtailor Marketplace Integration, please follow the necessary steps.

## Overview

StackOne allows you to integrate your Teamtailor integration app with the Assessment and Background Check categories.
This guide covers how you can set up/configure integration at Teamtailor and integrate with StackOne.

## Partnership Requirements

<Warning>
  The partnership with Teamtailor Integration is necessary to proceed with this documentation.
</Warning>

To become a Teamtailor Integration Partner, navigate to [resource partnership](https://www.teamtailor.com/en/resources/partnerships),
then click on `Apply today` which will scroll down to the Integration Partner section that contains a `Find out more` button to
direct you to the [Integrate with Teamtailor](https://teamtailor.notion.site/Integrate-with-Teamtailor-3919690568754aaaa7ffd681afe955f2) page.

<Frame>
  <img alt="Integrate with Teamtailor page" />
</Frame>

Click on `Apply as Tech Partner!` button to fill out the **Teamtailor - Tech Partner Integration Request Form**.

<Note>
  Once you have obtained the Teamtailor partnership, follow the steps below to create an integration with Teamtailor for the Assessment & Background Check categories.
</Note>

## StackOne approach for Teamtailor Integration

Once you <a href="#provider-side-setup">Create an Integration Partner</a> in Teamtailor, the next step is to enable and configure Teamtailor in StackOne. This process will generate an **External Trigger Token** for users, which acts as a key to activate/enable your integration through the Teamtailor Marketplace.

Users will utilise this **External Trigger Token** to integrate the Assessment/Background Check partner application into their job stage workflow.

<Frame>
  <img alt="StackOne approach" />
</Frame>

## Provider Side Setup

<Steps>
  <Step title="Navigate to Integration's hub">
    Log into your Teamtailor account. To access the *Integration Hub*, select the **Settings** option in the top-right corner.

    <Frame>
      <img alt="navigate to settings" />
    </Frame>
  </Step>

  <Step title="Start creating the Integration Partner">
    To add a new partner, click on the `CREATE A NEW PARTNER` button.

    <Frame>
      <img alt="create a partner" />
    </Frame>
  </Step>

  <Step title="Fill out the form to create a partner app">
    Complete the New Partner's form by filling out all the required fields:

    * **Partner's Name** - Enter the name of the integration partner.
    * **Partner Base URL** - Enter the endpoint URL provided by StackOne that will be used to fetch the input field configurations with the list of packages and to send candidate test notifications.

    ```plaintext theme={null}
    https://api.stackone.com/external-trigger/teamtailor
    ```

    <Frame>
      <img alt="new partner" />
    </Frame>

    * **Category in marketplace** - The integration will be categorised and displayed under the chosen category, such as Assessments or Background Checks, on Teamtailor's Marketplace.
    * **Additional options (Activation Form)** - Enter the following JSON into the activation form field:

    <Frame>
      <img alt="Activation Form" />
    </Frame>

    ```plaintext theme={null}
    {
       "config":{
          "fields":[
             {
                "type":"infobox",
                "content":"<a href='https://hub.stackone.com/integration-configuration-concepts/ats/teamtailor-assessment-or-background-check'>Click</a> here to learn how to use this integration",
                "icon":"info"
             },
             {
                "id":"externalTriggerToken",
                "type":"password",
                "label":"External Trigger Token",
                "required":true,
                "description":"The token to be used to trigger the workflow externally"
             }
          ]
       }
    }
    ```

    <Note>
      This **External Trigger Token** field will be visible to the user when enabling the integration from the Teamtailor Marketplace.
    </Note>

    After saving, the partner integration will be successfully created.
  </Step>
</Steps>

### To obtain the credentials for partner integration

<Steps>
  <Step title="Find your Integration credentials">
    Next to your partner Integration's name on the Grid, you will find the Integration ID.

    <Frame>
      <img alt="Integration hub" />
    </Frame>

    By clicking on `Show Details`, you will be able to access the **API Key**.

    <Frame>
      <img alt="Api Key" />
    </Frame>
  </Step>
</Steps>

## StackOne Configuration

<Steps>
  <Step title="Navigate to enable the Teamtailor at StackOne">
    Go to the ATS category on the *Integrations* page and activate Teamtailor

    <Frame>
      <img alt="To Enable Teamtailor" />
    </Frame>
  </Step>

  <Step title="Enable and Configure Teamtailor in StackOne">
    Fill out the necessary fields in the **Teamtailor - Configuration** modal:

    * **Authentication Type**: Select either `Public + Partner API` or `Partner API` to integrate with Teamtailor (for Assessment/Background Check integration).

    <DifferenceBetweenPublicAndPartnerAPI />

    <Note>
      * If you select `Public + Partner API`, the hiring team's data will be included in the webhook notification.<br />
      * If you select `Partner API`, the hiring team's data will not be included in the webhook notification.
    </Note>

    * **Partner Category**: Select the category that corresponds to your integration on Teamtailor's Marketplace page. For instance, if your integration is listed under the Assessments category, please select **Assessment** from the dropdown menu.
    * **Package's List Endpoint URL** - Implement and provide an endpoint to StackOne that StackOne will use to retrieve the list of packages when the recruiter wants to send a test to a candidate.

    Implement the following POST endpoint:

    ```bash theme={null}
    curl --location 'https://your-domain.com/<route-to-the-post-endpoint>' \
    --header 'Content-Type: application/json' \
    --header 'x-stackone-signature: string' \
    --header 'Authorization: Basic <base64-encoded-api-key>' \
    --data '{
        "job_id": "49201091",
        "account_id": "456551489512493412",
        "provider": "teamtailor"
    }'
    ```

    The expected response of the POST endpoint (list of packages). Refer to:

    * [List Assessments Packages](https://docs.stackone.com/ats/api-reference/assessments/packages/list-assessments-packages)
    * [List Background Check Packages](https://docs.stackone.com/ats/api-reference/background-checks/packages/list-background-check-packages)

    Enter the endpoint into the designated field:

    ```plaintext theme={null}
    https://your-domain.com/<route-to-the-post-endpoint>
    ```

    * **Partner Integration ID**: You can find the Integration ID next to the Integration Name under **Settings > Integrations Hub** in Teamtailor.
    * **Partner Integration API Key**: The API key can be found in the Integration details under **Settings > Integrations Hub** in Teamtailor.

    <Info>
      To get Partner Integration ID & API Key, [check this](#to-obtain-the-credentials-for-partner-integration)
    </Info>

    * **Package ID** - If you do not have the Package's List Endpoint URL, you can specify a particular package ID that will be visible to the recruiter when they wish to send the test to the candidate.

    <DifferenceBetweenListEndpointAndStaticIdOfPackage />

    <Frame>
      <img alt="Teamtailor Configuration Model" />
    </Frame>

    Click on the `Confirm` or `Save Changes` button to enable your Partner APIs, allowing end-users to link their accounts through the Hub.
  </Step>

  <Step title="Add a Webhook">
    Navigate to the *Webhooks* page, click on `Add webhook` and fill out the form:

    * **Name:** Enter your webhook with a recognisable name.
    * **URL:** Enter the URL where the webhook will send the notification of the enable events.

    <Frame>
      <img alt="Add Webhook form" />
    </Frame>

    Enable webhook events from the `Events` tab for Assessment & Background Check, such as `Assessments Order` & `Background Check Order`.

    <Frame>
      <img alt="Select webhook events" />
    </Frame>
  </Step>
</Steps>

## ATS User Enablement

Navigate to the *Accounts* page or the StackOne Connector Hub to link your Teamtailor account with StackOne.

<Frame>
  <img alt="Link Teamtailor account" />
</Frame>

Users will get the **External Trigger Token** that is required to enable the integration from the Teamtailor Marketplace.

<Frame>
  <img alt="Teamtailor User view of External-trigger" />
</Frame>

<Note>
  Follow the [Teamtailor Assessment or Background Check](https://hub.stackone.com/integration-configuration-concepts/ats/teamtailor-assessment-or-background-check) guide regarding how to enable the Teamtailor integration from the Marketplace.
</Note>

## ATS User Experience

### Send the test to the Candidate from Teamtailor

<Frame>
  <video />
</Frame>

<Note>
  Follow the [Teamtailor Assessment or Background Check](https://hub.stackone.com/integration-configuration-concepts/ats/teamtailor-assessment-or-background-check) guide regarding how to send the test from Teamtailor.
</Note>

### User will see after test has been sent

When a user sends an assessment or background check to a candidate, they will see a success message in the candidate application pop-up.

<Frame>
  <img alt="Teamtailor sent test view" />
</Frame>

## ATS User Experience Customisation

<Steps>
  <Step title="To Update the result via unified api">
    Utilise the following endpoints to update the results:

    * [Assessment Update Result](https://docs.stackone.com/ats/api-reference/assessments/results/update-assessments-result)
    * [Background Check Update Result](https://docs.stackone.com/ats/api-reference/background-checks/results/update-background-check-result)

    Utilise the following endpoint to get metadata to update the result of the assessment or background check:

    * [Connector Meta Information](https://docs.stackone.com/platform/api-reference/connectors/get-connector-meta-information) with the provider key `teamtailor` for model `assessments/results.update` or `background_checks/results.update`

    #### User sees the updated results with different conditions of the assessment/background check in Teamtailor

    |                                                                                                                                      |
    | ------------------------------------------------------------------------------------------------------------------------------------ |
    | When the result status `completed` without any other details    <br /> <img alt="Update result with result status completed only" /> |
    | When the result status `failed` without any other details       <br /> <img alt="Update result with result status failed only" />    |
    | When the result `completed` with all data except Score          <br /> <img alt="completed without score" />                         |
    | When the result `failed` with all data except Score             <br /> <img alt="failed without score" />                            |
    | When the result `completed` with all details                    <br /> <img alt="completed without score" />                         |
    | When the result `failed` with all details                       <br /> <img alt="failed without score" />                            |
    | When the result not included Result URL                         <br /> <img alt="without result URL" />                              |
    | When the result not included Attachments URL                    <br /> <img alt="without attachments URL" />                         |
    | When the result included multiple Attachments URL               <br /> <img alt="multiple attachments URL" />                        |
  </Step>
</Steps>

## Testing Checklist

✅  **Provider Setup:**

* Logged-in with Admin account.
* Valid StackOne URL.
* Integration partner app is published to the Teamtailor's marketplace under your selected category.
* Teamtailor's marketplace activation form of your integration app having an input field to enter `External Trigger Token`.

✅  **StackOne Configuration:**

* Selected `Public + Partner API` or `Partner API` as Authentication Type.
* Package's List Endpoint URL is correct.
* Enable Teamtailor in StackOne Configuration model with the List Packages endpoint.
* Package's List Endpoint response is expected according to the following endpoint's response:
  * [List Assessments Packages](https://docs.stackone.com/ats/api-reference/assessments/packages/list-assessments-packages)
  * [List Background Check Packages](https://docs.stackone.com/ats/api-reference/background-checks/packages/list-background-check-packages)

✅  **ATS User Activation:**

* Enter `External Trigger Token` to the marketplace app to enable the integration partner app.
* Once the app is enabled from the marketplace, the app should be visible in the Integration list under the Candidate's application; navigate to `More` (the three-dot menu).

✅  **Create a Webhook:**

* Added a webhook for Teamtailor and enabled it with the events such as: `Assessment Order` or `Background Check Order`
* Valid webhook URL to receive assessment/background check notifications.

✅  **ATS User Experience:**

* The integration app is visible in the Integration list under the candidate’s application; navigate to `More` (the three-dot menu).
* A list of packages is visible in the dropdown field on the prompt when you click the integration from the list.
* Select a package and send the webhook. A green check will appear if the notification has been sent, or an error will appear if not.

✅  **Update Result:**

* Success response from the update result endpoint.
* Updated result details to Teamtailor's UI.

## Troubleshooting

<div>
  | Symptom                                                                                                | Likely cause                                                                                                                                                                                                                             | Fix                                                                                                                                                                                                                                                                                                                      |
  | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  | Unable to add new Integration partner app.                                                             | **•** Teamtailor Partnership is not active. <br /><br /> **•** Logged-in account is not an Admin account.                                                                                                                                | **•** Contact Teamtailor support for partnership status. <br /><br /> **•** Log in with an Admin account.                                                                                                                                                                                                                |
  | Integration partner app not visible in Teamtailor Marketplace.                                         | Partnership app might be published but not approved                                                                                                                                                                                      | Contact Teamtailor support for partnership status.                                                                                                                                                                                                                                                                       |
  | Getting `Failed to fetch config from partner: Unable to fetch the partner config` error on the pop-up. | **•** Package's List Endpoint URL or Static Package ID is missing from StackOne Configuration. <br /><br /> **•** Invalid response getting from the Package's List Endpoint URL. <br /><br /> **•** Invalid Package's List Endpoint URL. | **•** Add Static Package ID if you don't have Package's List Endpoint URL. <br /><br /> **•** Response format should be expected as mentioned in the [StackOne Configuration](#stackone-configuration). <br /><br /> **•** Check Package's List Endpoint URL implementation at your end. <br /><br /> **•** Verify CORS. |
  | External Trigger Token field is not visible at StackOne Connector Hub.                                 | **•** Selected Authentication Type is incorrect.                                                                                                                                                                                         | Select Authentication Type `Public + Partner API` or `Partner API` instead.                                                                                                                                                                                                                                              |
  | User unable to activate integration app.                                                               | Invalid External Trigger Token.                                                                                                                                                                                                          | Ensure to copy & add valid External Trigger Token                                                                                                                                                                                                                                                                        |
  | Test notification is not received.                                                                     | **•** Invalid webhook URL. <br /><br /> **•** Incorrect webhook events are enabled.                                                                                                                                                      | **•** Verify webhook URL. <br /><br /> **•** Enable expected events as mentioned in the [StackOne Configuration](#stackone-configuration).                                                                                                                                                                               |
  | Test notification not included the job's hiring team.                                                  | Different Authentication Type instead of `Public + Partner API`.                                                                                                                                                                         | Select Authentication Type `Public + Partner API` instead.                                                                                                                                                                                                                                                               |
  | Unable to update result.                                                                               | Invalid payload format.                                                                                                                                                                                                                  | Check [Connector Meta API](https://docs.stackone.com/platform/api-reference/connectors/get-connector-meta-information) endpoint for payload format.                                                                                                                                                                      |
  | Result URL or Attachment's URL showing error when opened.                                              | Added result URL can be expired or is private.                                                                                                                                                                                           | Ensure to add public or signed URLs; verify CORS and expiry.                                                                                                                                                                                                                                                             |
</div>

For persistent issues, contact StackOne support with detailed error logs and configuration information.


# Workday Assessment
Source: https://docs.stackone.com/integration-guides/ats/workday-assessment

Learn how to configure and integrate Workday Assessments with StackOne.

## Overview

This guide explains how to integrate Workday Assessments with StackOne, enabling automatic management of assessments within your recruitment process.
It details the configuration of assessment categories, tests, and statuses in Workday, as well as the setup of webhooks and integration systems.
By following these steps, you will ensure automated assessment workflows and reliable synchronisation of results between Workday and StackOne.

## Partner Requirements

There are no formal partnership requirements to configure and utilise the assessment feature with Workday; however, you must have administrative privileges for your Workday account.

## Provider Side Setup

### Create Assessment Category in Workday

<Steps>
  <Step title="Create an assessment category">
    Navigate to the <i>Maintain Recruiting Assessment Categories</i> page and add a new assessment category named `Technical Assessment Test`.

    <Frame>
      <img alt="Maintain Assessment Categories" />
    </Frame>

    Click the `OK` button to save, and then the `Done` button to confirm.

    <Frame>
      <img alt="Assessment Category" />
    </Frame>
  </Step>
</Steps>

### Create Assessment Test in Workday

<Steps>
  <Step title="Create an Assessment Test">
    Navigate to the <i>Maintain Recruiting Assessment Tests</i> page and add an assessment test called `Technical Assessment`.

    <Frame>
      <img alt="Maintain Assessment Tests" />
    </Frame>

    Enter the test name, select the assessment category created in the previous step, and choose the `StackOne_IS_System` integration system generated from StackOne.

    <Frame>
      <img alt="Assessment Tests" />
    </Frame>

    Click `OK` to save, and then `Done` to confirm.
  </Step>

  <Step title="Edit or retrieve the Assessment Test ID">
    Click the three-dot menu, select `View IDs` to view the ID, or `Edit Reference ID` to modify it.

    <Frame>
      <img alt="Edit/View Assessment Test ID" />
    </Frame>
  </Step>

  <Step title="Use of the Assessment Test ID">
    You will need the `Assessment_Test_ID` (for example, `RECRUITING_ASSESSMENT_TEST-6-111`) for the notification payload configuration.

    <Frame>
      <img alt="Assessment Test ID" />
    </Frame>
  </Step>
</Steps>

### Create Assessment Status in Workday

<Steps>
  <Step title="Create an Assessment Status">
    Navigate to the <i>Maintain Assessment Statuses</i> page and add a new assessment status. You can name it `Invited` or choose another name.

    <Frame>
      <img alt="Maintain Assessment Status" />
    </Frame>

    Enter the status name, and tick the overall status and test status boxes. Click `OK`, then `Done` to save and confirm.
  </Step>

  <Step title="Edit or retrieve the Assessment Status ID">
    Click the three-dot menu, select `View IDs` to view the ID, or `Edit Reference ID` to modify it.

    <Frame>
      <img alt="Edit/View Assessment Status ID" />
    </Frame>
  </Step>

  <Step title="Use of the Assessment Status ID">
    The Assessment Status ID is used for sending assessment invitation notifications. Ensure this ID is set to `Invited`, regardless of the status name you have provided.

    <Frame>
      <img alt="Assessment Status ID" />
    </Frame>
  </Step>
</Steps>

### Job Requisitions within the Supervisory Organisation in Workday

<Warning>
  These steps assume you already have a Supervisory Organisation in your Workday account. If not, please contact your administrator to create one.
</Warning>

<Steps>
  <Step title="Listed Job Requisitions">
    Navigate to your <i>Supervisory Organisation</i> page and go to the `Staffing` tab.

    <Info>
      Ensure the Supervisory Organisation’s Staffing Model is `Position Management`.
    </Info>

    <Frame>
      <img alt="SO for JR" />
    </Frame>

    Under the `Positions with Open Job Requisition` grid, you will find the list of Job Requisitions that support sending notifications for the Assessment stage via the Integration System.
  </Step>

  <Step title="No Listed Job Requisitions">
    If there are no jobs listed under `Positions with Open Job Requisition`, find `Create Position` under the `Staffing` tab in the three-dot menu.

    <Frame>
      <img alt="Create Job Position" />
    </Frame>

    Fill in the required details to create a position. It will then appear in the `Positions without Job Requisition` grid.

    <Frame>
      <img alt="Created Job Position" />
    </Frame>

    Navigate to `Create Job Requisition`, select your Supervisory Organisation and position, click `OK`, complete the Job Requisition form, and then `Submit` it.

    <Frame>
      <img alt="Add in Position in Job Req" />
    </Frame>

    The position will now appear in the `In Progress Requisition Actions` grid.

    <Frame>
      <img alt="Added in Position in Job Req" />
    </Frame>

    Once the job requisition is approved, it will appear in the `Positions with Open Job Requisition` grid and will be enabled to send notifications.

    <Frame>
      <img alt="Approved Job Req" />
    </Frame>
  </Step>
</Steps>

### Update Assess Candidate Business Process in Workday

<Steps>
  <Step title="Select to update the Integration System">
    Search for the business process named *Assess Candidate* using the global search bar (e.g. `bp: Assess Candidate`).

    <Frame>
      <img alt="BP Config IS" />
    </Frame>

    Navigate to the <i>Assess Candidate Business Process</i> page and click the `Configure Integration System` button.

    <Frame>
      <img alt="BP Config IS" />
    </Frame>

    Select `StackOne_IS_System` as the integration and click `OK`.

    <Frame>
      <img alt="Select IS on Popup" />
    </Frame>

    <Warning>
      If you don't see `StackOne_IS_System` as an available integration system, please verify that your Workday account is properly connected to StackOne and that you have set up the necessary webhook with the appropriate events in StackOne.<br /><br />
      Please refer to the <a href="#stackone-configuration">StackOne Configuration</a> section to connect and set up the webhook for your Workday account.
    </Warning>
  </Step>

  <Step title="Edit payload attribute values">
    A pop-up will appear, allowing you to select the values for the fields to be included in the payload request when the `Invited` event is triggered from Workday.

    <Frame>
      <img alt="Set Values for Fields" />
    </Frame>

    **Please fill in the following information:**

    * **Candidate First Name:** \[First Name]
    * **Candidate Last Name:** \[Last Name]
    * **Candidate Email Address:** \[Email]
    * **Candidate Reference ID:** \[Candidate ID]
    * **Job Application Reference ID:** \[Job Requisition as Text]
    * **Assessment Test Reference ID:** \[Assessment\_Test\_ID for the assessment you want to send to the candidate]

    Click `OK` to save your configuration.
  </Step>
</Steps>

## StackOne Configuration

<Steps>
  <Step title="Enable Workday in StackOne">
    Go to the ATS category on the *Integrations* page and enable Workday.

    <Frame>
      <img alt="Activate Workday" />
    </Frame>
  </Step>

  <Step title="Complete the configuration form">
    Complete the required fields in the **Workday - Configuration** modal:

    * **Authentication Type** - You can select any Authentication Type to integrate with Workday.
    * **Integration Category** - Select `Assessments`.

    <Frame>
      <img alt="Activate Workday" />
    </Frame>

    Click `Confirm` or `Save Changes` to enable the Workday integration, allowing end-users to link their accounts via the StackOne Connector Hub.
  </Step>

  <Step title="Create a Webhook">
    Navigate to the *Webhooks* page and click the `+ Add Webhook` button to add a webhook for Workday.

    <Frame>
      <img alt="Create Webhook" />
    </Frame>
  </Step>

  <Step title="Select webhook event">
    Navigate to the *Events* tab and enable the `Assessment Order` event from the grid.

    <Frame>
      <img alt="Select Webhook Event" />
    </Frame>

    Click the `Save` button to save the webhook.

    <Note>
      To test the assessment webhook with your Workday Sandbox account, see the <a href="#ats-user-enablement">ATS User Enablement</a> section to connect and configure
      the **Integration System** programmatically in your Workday Sandbox account.
    </Note>
  </Step>
</Steps>

## ATS User Enablement

When users connect their Workday account with StackOne, an Integration System will be created in the user's Workday account named `StackOne_IS_System`, along with the necessary assessment configurations. These include:

* Endpoint URL (used to receive notifications)
* Username
* Password (used to authenticate each request from the user's Workday account)
* Assessment Status (used to send the assessment)

<Note>
  The user must configure the Integration step under the `Assess Candidate` Business Process by selecting `StackOne_IS_System` from the Configure Integration System pop-up.
</Note>

Log in to your Workday account and search for *View Integration System* in the global search bar. Search for `StackOne_IS_System` in the prompt that opens, then click `OK`.

<Frame>
  <img alt="View Integration System" />
</Frame>

You will find the Integration System named `StackOne_IS_System`, with the configured Integration Attributes and `Inline Assessment` as an Integration Template.

<Frame>
  <img alt="View Integration System" />
</Frame>

## ATS User Experience

After completing the configuration process, users will have an **Assessment** stage in the Job Requisition workflow.

<Frame>
  <img alt="Assessment Stage" />
</Frame>

When a candidate is moved to the **Assessment** stage, an `Assess` button will appear next to their name. The user can use this to send the assessment test to the candidate.

<Frame>
  <img alt="Assess Button" />
</Frame>

### Send the test to the candidate from Workday

#### Move Candidate to the Assessment Stage in Workday

<Steps>
  <Step title="Go to the Job Requisition">
    Navigate to the <i>Job Requisitions</i> page by selecting the same Job Requisition from the pop-up where the candidate applied for the job.

    <Frame>
      <img alt="View JR" />
    </Frame>

    Navigate to the `Candidate` tab and select the `Review` tab, where the candidate will be displayed in the grid below.

    <Frame>
      <img alt="Candidate Job Apply" />
    </Frame>
  </Step>

  <Step title="Move Candidate from Review to Assessment stage">
    Select the candidate in the grid and click the `Move Forward` button.

    <Frame>
      <img alt="View JR" />
    </Frame>
  </Step>

  <Step title="Select Assessment from the dropdown">
    In the pop-up, select the next stage, which is likely the Assessment Stage. Choose `Assessment` in both dropdown menus.

    <Frame>
      <img alt="Candidate Job Apply" />
    </Frame>

    Click the `OK` button to move.
  </Step>

  <Step title="Candidate Moved to the Assessment Stage">
    If you go to the `Assessment` tab, the candidate will now be in the Assessment stage.

    <Frame>
      <img alt="View JR" />
    </Frame>

    If you are unable to move the candidate to the assessment stage directly, move the stages one at a time.
  </Step>
</Steps>

#### Send the assessment invitation to the candidate using Start Proxy

<Steps>
  <Step title="Sending via Start Proxy">
    If you are not the recruiter, go to the recruiter’s account via `Start Proxy`. Click the `Awaiting Action` link, and a pop-up will appear showing the recruiter’s name.

    <Frame>
      <img alt="View Recruiter" />
    </Frame>
  </Step>

  <Step title="Navigate to the Start Proxy">
    Go to the <i>Start Proxy</i> page and select Recruiter from the dropdown menu.

    <Frame>
      <img alt="Start Proxy" />
    </Frame>

    You will be taken to the recruiter's homepage, where you need to navigate to the `My Tasks` page in the top-right corner.

    <Frame>
      <img alt="My Tasks" />
    </Frame>

    You will find the task at the top, labelled with the Job Requisition and candidate name, in the sidebar.

    <Frame>
      <img alt="Sidebar" />
    </Frame>

    Clicking the sidebar task will display the candidate's assessment details on the right side.
  </Step>

  <Step title="Send the Assessment Invitation">
    Set the Overall Status to `Invited` and select the Assessment as `Technical Assessment` from the dropdown menu. Then, click the `Submit` button.

    <Frame>
      <img alt="Assessment Form" />
    </Frame>
  </Step>
</Steps>

#### Send the assessment invitation to the candidate as a Recruiter

<Steps>
  <Step title="Sending as a Recruiter">
    If you are the recruiter, you should see the `Assess` button next to the candidate's name.

    <Frame>
      <img alt="Sending Invite" />
    </Frame>
  </Step>

  <Step title="Send the Assessment Invitation">
    Set the Overall Status to `Invited` and select the Assessment as `Technical Assessment` from the dropdown menu.

    <Frame>
      <img alt="Send Invite" />
    </Frame>

    Click the `Submit` button to trigger the webhook notification from Workday.
  </Step>
</Steps>

<Note>
  You can refer to the [Workday Assessment](https://hub.stackone.com/integration-configuration-concepts/ats/workday-assessment) guide for more details on how to send the test from Workday.
</Note>

### User will see after test has been sent

The user can access the candidate's application by clicking their name visible in the `Candidates` tab on the Job Requisition Page.

<Frame>
  <img alt="Assessment Details" />
</Frame>

In the *Application > Screening* tab, under the `Assessment` sub-tab, the user can view the details of the assessment that has been sent to the candidate.

<Frame>
  <img alt="Assessment Details" />
</Frame>

## ATS User Experience Customisation

<Steps>
  <Step title="To update the result via the Unified API">
    Use the following endpoints to update the results:

    * [Assessment Update Result](https://docs.stackone.com/ats/api-reference/assessments/results/update-assessments-result)

    Use the following endpoint to get metadata to update the result of the assessment or background check:

    * [Connector Meta Information](https://docs.stackone.com/platform/api-reference/connectors/get-connector-meta-information) with the provider key `workdayats` for model `assessments/results.update`

    <div>
      | Fields (when provided) | User sees in Workday                                                           | Comment                                       |
      | ---------------------- | ------------------------------------------------------------------------------ | --------------------------------------------- |
      | Result                 | Result will be displayed corresponding to the **Overall Status** label         | Result enum values from Meta API result field |
      | Summary                | Summary will be displayed corresponding to the **Comment** label               |                                               |
      | Submission Date        | Submission date will be displayed corresponding to the **Overall Date** label  |                                               |
      | Start Date             | Start date will be displayed in the **Date** column within the Assessment grid |                                               |
    </div>
  </Step>

  <Step title="How assessment results are displayed to the customer in Workday">
    When a customer opens a candidate's application, they can navigate to the `Assessment` tab within the application to view the assessment details and results.

    <Frame>
      <img alt="Updated Result" />
    </Frame>
  </Step>
</Steps>

## Testing Checklist

✅ **Provider Setup:**

* Logged in with an Admin account.
* Added Assessment Categories.
* Added Assessment Tests.
* Added Assessment Statuses. Ensure `Invited` is set as the Reference ID of the status you will choose when sending the Assessment.
* Job Requisitions are within the Supervisory Organisation with the Staffing Model as `Position Management`.
* Configured the `Assess Candidate` Business Process with the Integration System that will be generated programmatically when the user connects Workday with StackOne.
* Added order payload attribute values with the correct `Assessment Test Reference ID`.

✅ **StackOne Configuration:**

* Selected `Assessments` as the Integration Category.

✅ **ATS User Activation:**

* Workday account connected successfully with StackOne.
* Check that the Integration System named `StackOne_IS_System` is created with the necessary assessment configurations.
* Ensure you configure the Integration step under the `Assess Candidate` Business Process by selecting `StackOne_IS_System` from the Configure Integration System pop-up.

✅ **Create a Webhook:**

* Added a webhook for Workday and enabled it with events such as: `Assessment Order`.
* Valid webhook URL to receive assessment notifications.

✅ **ATS User Experience:**

* Assessment stage is available in the Job Requisition workflow.
* `Invited` status, or a status with `Invited` as the Reference ID, is available to select on the Assessment pop-up when clicking the `Assess` button.
* In the *Application > Screening* tab, under the `Assessment` sub-tab, the sent assessment details will be available.

✅ **Update Result:**

* Success response from the update result endpoint.
* Updated result details visible in Workday's UI.

## Troubleshooting

<div>
  | Symptom                                                                                                         | Likely cause                                                                                                                                                                                                                                                                                                                                | Fix                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
  | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  | Unable to access Organisation and Business Process.                                                             | Logged-in account is not an Admin account.                                                                                                                                                                                                                                                                                                  | Log in with an Admin account.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
  | Unable to search the above-mentioned navigations.                                                               | **•** Logged-in account is not an Admin account. <br /><br /> **•** You do not have permission to access.                                                                                                                                                                                                                                   | **•** Log in with an Admin account. <br /><br /> **•** Contact your Workday account admin to provide the necessary permissions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
  | Unable to find/configure the Integration System under the `Assess Candidate` Business Process.                  | Workday account is not connected with StackOne.                                                                                                                                                                                                                                                                                             | Connect your Workday account with StackOne, which will create the Integration System programmatically.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
  | `Assess` button is not visible next to the candidate's name in Job Requisition.                                 | Logged-in user is not the recruiter or hiring manager for that Job Requisition.                                                                                                                                                                                                                                                             | **•** You can use the <a href="#send-the-assessment-invitation-to-the-candidate-using-start-proxy">Start Proxy</a> feature to send the assessment to the candidate. <br /><br /> **•** Ensure you are logged in as the recruiter or hiring manager associated with the Job Requisition.                                                                                                                                                                                                                                                                                                                            |
  | Assessment test notification is not received.                                                                   | **•** Invalid webhook configurations in StackOne. <br /><br /> **•** Supervisory Organisation's Staffing Model is not set to `Position Management`. <br /><br /> **•** Job Requisition is not listed under the Supervisory Organisation. <br /><br /> **•** `Invited` status, or a status with `Invited` as a Reference ID, is not created. | **•** The webhook URL and enabled events should be valid. Please refer <a href="#stackone-configuration">these</a> steps. <br /><br /> **•** Supervisory Organisation's Staffing Model should be set to `Position Management`. <br /><br /> **•** Job Requisition should be listed under the Supervisory Organisation. Please refer <a href="#job-requisitions-within-the-supervisory-organisation-in-workday">these</a> steps. <br /><br /> **•** `Invited` status, or a status with `Invited` as a Reference ID, should be created. Please refer <a href="#create-assessment-status-in-workday">these</a> steps. |
  | The selected test during the assessment submission to the candidate was not sent within the order notification. | You have already configured the Assessment Test Reference ID under the Integration step in <a href="#update-assess-candidate-business-process-in-workday">Assess Candidate Business Process</a>.                                                                                                                                            | You cannot select the dynamic test from the Assessment send pop-up as you have already configured the Assessment Test Reference ID under the Integration step in <a href="#update-assess-candidate-business-process-in-workday">Assess Candidate Business Process</a>.                                                                                                                                                                                                                                                                                                                                             |
  | Result URL showing error when opened.                                                                           | Added result URL may have expired or is private.                                                                                                                                                                                                                                                                                            | Ensure you add public or signed URLs; verify CORS and expiry.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
</div>

For persistent issues, contact StackOne support with detailed error logs and configuration information.


# Workday Background Check
Source: https://docs.stackone.com/integration-guides/ats/workday-background-check

Learn how to configure and integrate Workday Background Checks with StackOne.

## Overview

This guide provides step-by-step instructions for configuring and integrating Workday Background Checks with StackOne.
By following these steps, you will enable background checks for candidates, ensuring that all required statuses, packages,
and business processes are correctly set up in Workday. The integration automates the workflow and ensures consistent status updates.

## Partner Requirements

There are no formal partnership requirements to configure and utilise the background check feature with Workday; however, you must have administrative privileges for your Workday account.

## Provider Side Setup

### Create Background Check Statuses in Workday

<Steps>
  <Step title="Create background check statuses">
    Navigate to the <i>Maintain Background Check Statuses</i> page, add new statuses, and map each one to the appropriate existing value in the <i>Maps to</i> dropdown.
    Click `OK` to save and `Done` to confirm.

    <Frame>
      <img alt="Maintain Background Check Statuses" />
    </Frame>

    <Info>
      The background check statuses will be used to update the result of the background check.
    </Info>

    Use the following mapping when creating statuses:

    | Background Check Status Label | Maps to           |
    | ----------------------------- | ----------------- |
    | Completed                     | Completed         |
    | Passed                        | Passed            |
    | Initiated                     | Pending           |
    | Failed                        | Did Not Pass      |
    | Expired                       | Error             |
    | Cancelled                     | No Longer Applies |

    <Frame>
      <img alt="Maintain Background Check Statuses" />
    </Frame>
  </Step>

  <Step title="Edit reference IDs for the background check statuses">
    From the 3-dot menu, select <i>Edit Reference ID</i> to modify the `Background_Check_Status_ID`.

    <Frame>
      <img alt="Maintain Background Check Statuses" />
    </Frame>

    Set the Reference ID to exactly match each status label.

    <Frame>
      <img alt="Maintain Background Check Statuses" />
    </Frame>
  </Step>
</Steps>

### Create Background Check Packages in Workday

<Steps>
  <Step title="Create background check packages">
    Navigate to the <i>Maintain Background Check Packages</i> page and add background check packages, or utilise the <a href="https://docs.stackone.com/ats/api-reference/background-checks/packages/create-background-check-package">Create Background Check Package</a> endpoint.

    <Info>
      These background check packages will be available during the background check submission for candidates.
    </Info>

    <Frame>
      <img alt="Maintain Assessment Tests" />
    </Frame>

    Click `OK` to save and `Done` to confirm.
  </Step>
</Steps>

### Job Requisitions within the Supervisory Organisation in Workday

<Warning>
  These steps assume you already have a Supervisory Organisation in your Workday account. If not, please contact your administrator to create one.
</Warning>

<Info>
  It is essential to create the Job Requisition under the Supervisory Organisation that will provide the system with the required security and team authority to manage
  the entire hiring workflow, ensuring that essential business processes (such as automatically triggering background checks) are executed properly.
</Info>

<Steps>
  <Step title="Listed Job Requisitions">
    Navigate to your <i>Supervisory Organisation</i> page via global search (e.g. `org: <your-org-name>`),

    <Frame>
      <img alt="View Supervisory Organisation" />
    </Frame>

    Go to the `Staffing` tab.

    <Info>
      Ensure the Supervisory Organisation's Staffing Model is `Position Management`.
    </Info>

    <Frame>
      <img alt="SO for JR" />
    </Frame>

    Under the `Positions with Open Job Requisition` grid, you will find the list of job requisitions that support sending notifications for the background check via the Integration System.
  </Step>

  <Step title="No listed Job Requisitions">
    If there are no jobs listed under `Positions with Open Job Requisition`, choose `Create Position` under the `Staffing` tab from the 3-dot menu.

    <Frame>
      <img alt="Create Job Position" />
    </Frame>

    Complete the required fields to create a position; it will then appear in the `Positions without Job Requisition` grid.

    <Frame>
      <img alt="Created Job Position" />
    </Frame>

    Navigate to `Create Job Requisition`, select your Supervisory Organisation and position, click `OK`, complete the form, then `Submit` it.

    <Frame>
      <img alt="Add in Position in Job Req" />
    </Frame>

    The position will now appear in the `In Progress Requisition Actions` grid.

    <Frame>
      <img alt="Added in Position in Job Req" />
    </Frame>

    Once the job requisition is approved, it appears in the `Positions with Open Job Requisition` grid. The recruiter can then assign candidates to this job requisition, which includes Background Check as a stage.

    <Frame>
      <img alt="Approved Job Req" />
    </Frame>
  </Step>
</Steps>

### Business Process for Background Check in Workday

<Steps>
  <Step title="Create the Business Process for Background Check">
    To create a Background Check Business Process, open the 3‑dot menu beside the Supervisory Organisation name, then click `Create Business Process` under the Business Process menu.

    <Frame>
      <img alt="Initiate Business Process" />
    </Frame>

    Select `Background Check` from the Business Process Type dropdown, then choose one of the following options: <br />

    * `Copy existing Definition` (to copy and create a new one from an existing or previously configured definition),
    * `Link existing Definition` (if one already exists), or
    * `None of the above` (which will prompt you to create a new one), <br />
      then click `OK`.

    <Frame>
      <img alt="Initiate Business Process 2" />
    </Frame>

    <Warning>
      If the expected **Business Process Type**, such as `Background Check`, is not visible in the dropdown, it means that the Business Process has already been created for this Supervisory Organisation with the specified type.
    </Warning>

    Enter the required details, then go to the `Business Process Steps` tab to configure the steps for the Background Check.

    | Order | If                                                     | Type        | Specify                                | Optional | Group                                                                                        |
    | ----- | ------------------------------------------------------ | ----------- | -------------------------------------- | -------- | -------------------------------------------------------------------------------------------- |
    | a     |                                                        | Initiation  |                                        | No       |                                                                                              |
    | b     |                                                        | Integration |                                        | No       |                                                                                              |
    | c     |                                                        | Service     | Document Delivery                      | No       |                                                                                              |
    | d     | Background Check Event has Package? (Workday Owned)    | Action      | Select Background Check Overall Status | No       | HR Administrator • Manager • Manager (Unconstrained) • Recruiter • Recruiter (Unconstrained) |
    | e     | Event is subevent of Recruiting Event? (Workday Owned) | Action      | Make Background Check Decision         | No       | HR Administrator • Manager • Manager (Unconstrained) • Recruiter • Recruiter (Unconstrained) |

    <Note>
      You may not have the same `Group` values mentioned in the table above or in the image below. Please select the appropriate `Group` values according to your Workday account's security group configurations.
    </Note>

    <Frame>
      <img alt="Setup the Business Process Steps" />
    </Frame>

    Click `Save`, then `Done` to confirm creation of the business process.
  </Step>

  <Step title="Configure the Integration System step">
    <Note>
      To create an Integration System, refer to the section <a href="#integration-system-in-workday">Integration System in Workday</a>.
    </Note>

    Navigate to the <i>Background Check Business Process</i> page and click `Configure Integration System`.

    <Frame>
      <img alt="BP Config IS" />
    </Frame>

    Select your Integration System and click `OK`.

    <Frame>
      <img alt="Select IS on Popup" />
    </Frame>
  </Step>

  <Step title="Edit payload attribute values">
    A pop-up appears allowing you to select the field values to be included in the payload when the `Background Check` event is triggered from Workday.

    <Frame>
      <img alt="Set Values for Fields" />
    </Frame>

    **Fill out the following information:**

    * **Background Check ID:** \[Background Check Business Process]
    * **As Of Entry Moment:** \[Current Moment (DateTime)]

    <Note>
      `Submission Date` and `Workflow State` should be left empty.
    </Note>

    Click `OK` to save your configuration.
  </Step>

  <Step title="Configure Maintain Redirect for the Integration step">
    Open the 3-dot menu on the `integration step` (step b) and click `Maintain Redirect`.

    <Frame>
      <img alt="Maintain Redirect" />
    </Frame>

    Enable the necessary actions, select the appropriate security groups, then click `OK` to save.

    <Note>
      You might have different Security Groups configurations on your Workday account.
    </Note>

    <Frame>
      <img alt="Maintain Redirect Page" />
    </Frame>
  </Step>

  <Step title="Configure the Document Delivery step">
    For the next Business Process step (step c), click `Configure Document Delivery`.

    <Frame>
      <img alt="BP Config IS" />
    </Frame>
  </Step>

  <Step title="Add values in required fields">
    A pop-up appears allowing you to configure the fields, including `Endpoint URL` (HTTP Address) and `External Trigger Token` (User ID).

    <Frame>
      <img alt="Set Values for Fields" />
    </Frame>

    **Fill out the following information:**

    * **From Specific Integration Step(s):** \[Your Integration System]

    * **Transport Type:** \[HTTP/SSL]

    * **HTTP Address:** \[Endpoint URL]
      ```plaintext theme={null}
      https://api.stackone.com/external-trigger/workdayats
      ```

    * **Web Service Invocation Type:** \[Basic Auth]

    * **User ID:** The `External Trigger Token` that you will receive from the StackOne Connector Hub during connection setup.

      <Note>
        To obtain the <b>External Trigger Token</b>, see:
        <br />• <a href="#stackone-configuration">StackOne Configuration</a>
        <br />• <a href="#ats-user-enablement">ATS User Enablement</a>
      </Note>

    * **New Password / Verify Password:** Enter any temporary text (Workday requires a value, but it isn’t used).

    Click the `OK` button to save your configuration.
  </Step>
</Steps>

### Integration System in Workday

<Steps>
  <Step title="Create Integration System">
    <Note>
      The integration system is crucial for the Background Check process as it automates the secure transfer of candidate data to the external vendor and returns the final background check status to Workday.
    </Note>

    Search for `Create Integration System` in the global search bar. Enter the `System Name` and select the integration template `Core Connector: Background Check Order Outbound` from the dropdown.

    <Frame>
      <img alt="Create Integration System" />
    </Frame>

    Click `OK` to create the Integration System.
  </Step>

  <Step title="Configure Integration Services">
    Navigate to `Configure Integration Services` from the 3-dot menu to enable the necessary services for the Background Check Order Integration.

    <Frame>
      <img alt="Configure Integration Services" />
    </Frame>

    The following required services will be enabled by default:

    * Core Connector : Background Check Order Outbound / Core Connector: Background Check Outbound Initial Service\*
    * Core Connector : Background Check Order Outbound / Core Connector : Background Check Outbound Service

    <Frame>
      <img alt="Add Integration Services" />
    </Frame>

    Click `OK` to save.
  </Step>

  <Step title="Configure Integration Attributes">
    Navigate to `Configure Integration Attributes` from the 3-dot menu to add the required attribute values.

    <Frame>
      <img alt="Configure Integration Attributes" />
    </Frame>

    Select the values for the attributes as shown in the image.

    <Frame>
      <img alt="Add Integration Attributes" />
    </Frame>

    Click `OK` to save.<br /><br />

    You have successfully created the Integration System for Background Check in Workday. <br />
    You can now use this Integration System in the business process described under the `Configure the Integration System step` in
    <a href="#business-process-for-background-check-in-workday">Business Process for Background Check in Workday</a>.
  </Step>
</Steps>

## StackOne Configuration

<Steps>
  <Step title="Enable Workday in StackOne">
    Go to the ATS category on the <i>Integrations</i> page and enable Workday.

    <Frame>
      <img alt="Activate Workday" />
    </Frame>
  </Step>

  <Step title="Complete the configuration form">
    Complete the required fields in the <b>Workday – Configuration</b> modal:

    * **Authentication Type** - Select one of the authentication types, e.g. `Basic Authentication`.
    * **Integration Category** - Select `Background Checks`.

      <Frame>
        <img alt="Activate Workday" />
      </Frame>

    Click `Confirm` or `Save Changes` to enable the Workday integration. This allows end users to link their accounts via the StackOne Connector Hub.
  </Step>

  <Step title="Create a webhook">
    Navigate to the *Webhooks* page and click the `+ Add Webhook` button to add a webhook for Workday.

    <Frame>
      <img alt="Create Webhook" />
    </Frame>
  </Step>

  <Step title="Select webhook event">
    Navigate to the <i>Events</i> tab and enable the `Background Check Order` event.

    <Frame>
      <img alt="Select Webhook Event" />
    </Frame>

    Click the `Save` button to save the webhook.

    <Note>
      To test the background check webhook with your Workday Sandbox account, see the <a href="#ats-user-enablement">ATS User Enablement</a> section.
    </Note>
  </Step>
</Steps>

## ATS User Enablement

Navigate to the *Accounts* page to link your Workday account with StackOne.

<Frame>
  <img alt="Link Workday account" />
</Frame>

You will receive the `External Trigger Token`, which must be entered as the User ID during the `Configure Document Delivery` step in <a href="#business-process-for-background-check-in-workday">Business Process for Background Check in Workday</a>.

<Frame>
  <img alt="External Trigger Token" />
</Frame>

## ATS User Experience

After completing configuration, users will see **Background Check** as a stage in the Job Requisition workflow within the Supervisory Organisation.

<Frame>
  <img alt="Background Check Stage" />
</Frame>

When a candidate is moved to the **Background Check** stage, a `Background Check` button appears next to their name. Users can use this to send the background check request to the candidate.

<Frame>
  <img alt="Background Button" />
</Frame>

### Send the background check request from Workday

#### Move the candidate to the Background Check stage

<Steps>
  <Step title="Open the Job Requisition">
    Navigate to the <i>Job Requisitions</i> page and select the job requisition the candidate applied to.

    <Frame>
      <img alt="View JR" />
    </Frame>

    Go to the `Candidate` tab, then the `Review` sub-tab, where the candidate appears in the grid.

    <Frame>
      <img alt="Candidate Job Apply" />
    </Frame>
  </Step>

  <Step title="Move candidate from Review to Background Check">
    Select the candidate in the grid and click `Move Forward`.

    <Frame>
      <img alt="View JR" />
    </Frame>
  </Step>

  <Step title="Select Background Check from the dropdown">
    In the pop-up, select the next stage (you may need to advance sequentially). For the Background Check stage, choose `Background Check` in both dropdown menus.

    <Frame>
      <img alt="Candidate Job Apply" />
    </Frame>

    Click the `OK` button to move.
  </Step>

  <Step title="Candidate moved to the Background Check stage">
    In the `Background Check` tab, the candidate now appears in the Background Check stage.

    <Frame>
      <img alt="View JR" />
    </Frame>
  </Step>
</Steps>

#### Send the background check invitation to the candidate

<Steps>
  <Step title="Submit background check as a recruiter">
    If you are the recruiter, the `Background Check` button appears next to the candidate's name.

    <Frame>
      <img alt="Sending Invite" />
    </Frame>
  </Step>

  <Step title="Send the Background Check invitation">
    Select the background check package you created (see <a href="#create-background-check-packages-in-workday">Create background check packages</a>) from the dropdown.

    <Frame>
      <img alt="Send Invite" />
    </Frame>

    Click `Submit` to trigger the webhook notification from Workday.
  </Step>
</Steps>

#### See the background check integration logs

<Steps>
  <Step title="Go to the Process Monitor">
    Access the <i>Process Monitor</i> page using the global search. Set the Process Type to `Integration` and click `OK` to view all logs related to integrations.

    <Frame>
      <img alt="Sending Invite" />
    </Frame>

    If you have just sent the background check request, you can view the latest logs at the top of the grid. Look for entries with a `Completed` status that correspond to your integration system name and Document Delivery requests.

    <Frame>
      <img alt="Send Invite" />
    </Frame>

    If the status is marked as completed without any errors, it means the webhook notification has been successfully sent.
  </Step>
</Steps>

### What the user sees after sending the request

In the <i>Application > Screening</i> tab, under the `Background Check History` sub‑tab, the user can view details of the background check that was sent to the candidate.

<Frame>
  <img alt="Background Check Details" />
</Frame>

## ATS User Experience Customisation

<Steps>
  <Step title="Update the result via the Unified API">
    Use the following endpoint to update results:

    * <a href="https://docs.stackone.com/ats/api-reference/background-checks/results/update-background-check-result">Background Check: Update Result</a>

    Use the following endpoint to get metadata to update the result of the background check:

    * [Connector Meta Information](https://docs.stackone.com/platform/api-reference/connectors/get-connector-meta-information) with the provider key `workdayats` for model `background_checks/results.update`

    <div>
      | Fields (when provided) | User sees in Workday                                                       | Comment                                       |
      | ---------------------- | -------------------------------------------------------------------------- | --------------------------------------------- |
      | Result                 | Result will be displayed within the grid's **Overall Status** column       | Result enum values from Meta API result field |
      | Submission Date        | Submission date will be displayed within the grid's **Status Date** column |                                               |
      | Result URL             | Result URL will be displayed within the grid's **Results URL** column      |                                               |
    </div>
  </Step>

  <Step title="How results appear in Workday">
    When a user opens a candidate's application, they can navigate to the `Background Check History` sub‑tab to view background check details and results.

    <Frame>
      <img alt="Updated Result" />
    </Frame>
  </Step>
</Steps>

## Testing Checklist

✅ **Provider Setup:**

* Logged in with an Admin account.
* Added background check status mappings as mentioned <a href="#create-background-check-statuses-in-workday">above</a>.
* Added background check packages as mentioned <a href="#create-background-check-packages-in-workday">here</a>.
* Job Requisitions exist within the Supervisory Organisation whose Staffing Model is `Position Management`.
* Configured the `Background Check` business process with the Integration System created.
* Added order payload attribute values correctly as mentioned in the <a href="#business-process-for-background-check-in-workday">Business Process for Background Check</a> step.
* Configured the Document Delivery step with the correct `Endpoint URL` and `External Trigger Token` (User ID). See <a href="#business-process-for-background-check-in-workday">Business process steps</a>.

✅ **StackOne Configuration:**

* Selected `Background Checks` as the Integration Category.

✅ **ATS User Activation:**

* Configured the Integration step in the Background Check business process by selecting the correct Integration System.
* Added a valid `Endpoint URL` and `External Trigger Token` (User ID) under the Document Delivery step.

✅ **Create a Webhook:**

* Added a webhook for Workday and enabled the `Background Check Order` event.
* Valid webhook URL to receive background check notifications.

✅ **ATS User Experience:**

* Background Check stage is available in the Job Requisition workflow.
* In the *Application > Screening* tab, under the `Background Check` sub-tab, the sent background check details will be available.

✅ **Update Result:**

* Success response from the update result endpoint.
* Updated result details visible in Workday's UI.

## Troubleshooting

<div>
  | Symptom                                                                                 | Likely cause                                                                                                                                                                                                                                                                                                                                                         | Fix                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
  | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Unable to access Supervisory Organisation and Business Process.                         | Logged-in account is not an admin account.                                                                                                                                                                                                                                                                                                                           | Log in with an admin account.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
  | Unable to get `Background Check` Business Process Type to create a Business Process     | A Business Process of the `Background Check` type has already been created for this Supervisory Organization.                                                                                                                                                                                                                                                        | Use the global search to find the existing Business Process (e.g., `bp: <your-bp-name>`) and edit the existing Business Process as mentioned in <a href="#business-process-for-background-check-in-workday">Business Process for Background Check</a> step.                                                                                                                                                                                                                                                                                                                                                                                                     |
  | Unable to search/navigate the above-mentioned navigations.                              | **•** Logged-in account is not an admin account. <br /><br /> **•** Missing permissions.                                                                                                                                                                                                                                                                             | **•** Log in with an admin account. <br /><br /> **•** Contact your Workday administrator to grant the required permissions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
  | `Background` button is not visible next to the candidate's name in the job requisition. | Logged-in user is not the recruiter or hiring manager for that job requisition.                                                                                                                                                                                                                                                                                      | Log in as the recruiter or hiring manager associated with the job requisition.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
  | Webhook notification not received.                                                      | **•** Invalid webhook configuration in StackOne. <br /><br /> **•** Supervisory Organisation staffing model not set to `Position Management`. <br /><br /> **•** Job requisition not listed under the Supervisory Organisation. <br /><br /> **•** `Invited` status (or matching Reference ID) not created. <br /><br /> **•** Document Delivery step misconfigured. | **•** Validate webhook URL and enabled events (see <a href="#stackone-configuration">StackOne Configuration</a>). <br /><br /> **•** Ensure staffing model is `Position Management`. <br /><br /> **•** Ensure job requisition appears under the Supervisory Organisation (see <a href="#job-requisitions-within-the-supervisory-organisation-in-workday">Job Requisitions section</a>). <br /><br /> **•** Create `Invited` status (see <a href="#create-background-check-statuses-in-workday">Statuses section</a>). <br /><br /> **•** Reconfigure Document Delivery (see <a href="#business-process-for-background-check-in-workday">Business Process</a>). |
  | List of packages not available.                                                         | No background check packages added.                                                                                                                                                                                                                                                                                                                                  | Add background check packages (see <a href="#create-background-check-packages-in-workday">Packages section</a>).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
  | Result URL shows an error.                                                              | Result URL has expired or is not publicly accessible.                                                                                                                                                                                                                                                                                                                | Use a public or signed URL; verify CORS configuration and expiry time.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
</div>

For persistent issues, contact StackOne support with detailed error logs and configuration information.


# HubSpot Webhook Configuration
Source: https://docs.stackone.com/integration-guides/crm/hubspot-webhook-configuration

To successfully configure the webhook and send the event on action.

<Warning>
  This guide assumes that you have administrative privileges for your HubSpot account.
</Warning>

## ✅ Prerequisites

Make sure you have the following before you start:

* A [HubSpot Developer Account](https://developers.hubspot.com)

## Get Credentials

<Steps>
  <Step title="Log in to HubSpot Developer Account">
    Log in to your HubSpot Developer Account at [https://app.hubspot.com/login](https://app.hubspot.com/login)

    <Frame>
      <img alt="Log In" />
    </Frame>
  </Step>

  <Step title="HubSpot OAuth App">
    * Select **Apps** from the navigation panel.
    * Click **Create App** to create a new app or select an existing app from the list.

    <Frame>
      <img alt="App List" />
    </Frame>
  </Step>

  <Step title="Get the Developer API Key">
    * Select **Keys** from the left sidebar.
    * Click **Show** to view your existing key or **Generate New Key** to create one.
    * Copy the key and store it securely.

    <Note>
      Developer API key is required to subscribe `create` and `delete` events for `Contacts` and `Accounts`
    </Note>

    <Frame>
      <img alt="API Key" />
    </Frame>
  </Step>
</Steps>

## Configure Webhooks

<Steps>
  <Step title="Navigate to Webhooks">
    In your app dashboard, navigate to **Apps>Webhooks**.

    <Frame>
      <img alt="Webhook Page" />
    </Frame>
  </Step>

  <Step title="Set the Webhook URL">
    * Add your `External Trigger URL` in the Target URL field.
      <Note>This step is only required when configuring update events for Contacts and Accounts.
      For all other events (such as create and delete), webhook subscriptions are handled automatically via the Webhook Subscription API, and no manual configuration of the Target URL is needed. </Note>

    <Frame>
      <img alt="Target URL" />
    </Frame>

    * Click **Save** to save the changes.

    <Frame>
      <img alt="Save changes" />
    </Frame>
  </Step>

  <Step title="Subscribe to Events">
    * Click **Create Subscription**
    * Select the object and event you want to subscribe to.
      * `contact.propertyChange`
      * `company.propertyChange`
    * Select the field you want to trigger the `propertyChange` event on.
    * Save subscription by clicking **Subscribe** button.

    <Note>
      This step is only required when configuring *update* events for **contacts** and **accounts**.
    </Note>

    <Frame>
      <img alt="Subscribe Event" />
    </Frame>

    * Activate the webhook by clicking the **Activate** button.

    <Frame>
      <img alt="Activate Event" />
    </Frame>
  </Step>
</Steps>

## StackOne Webhooks Configurations

<Steps>
  <Step title="Log in to StackOne Dashboard">
    Log in to your StackOne Dashboard at [https://app.stackone.com/login](https://app.stackone.com/login) and navigate to **Webhooks**

    <Frame>
      <img alt="Webhooks page" />
    </Frame>
  </Step>

  <Step title="Create Webhook">
    * To create new webhook click on **Add Webhook** button.

    <Frame>
      <img alt="Add Webhook" />
    </Frame>

    * Enter Webhook **Name** and **URL** and click **Create**.

    <Frame>
      <img alt="Create" />
    </Frame>

    * Click **Save** to save the changes.
  </Step>

  <Step title="Configure Events">
    * Select Webhook from the list.

    <Frame>
      <img alt="Select Webhook" />
    </Frame>

    * Go the **Events** tab.
    * To add a new event (such as Create, Update, or Delete), click the plus icon under the CRM catgory.

    <Frame>
      <img alt="Add Event" />
    </Frame>

    * Select the event under the **HubSpot** integration and click on the *Confirm* button to save the details.

    <Frame>
      <img alt="Confirm Event" />
    </Frame>

    * Save the webhook by clicking the **Save** button.

    <Frame>
      <img alt="Confirm Event" />
    </Frame>
  </Step>
</Steps>

<br />

Congratulations, you're all set!

## Useful Links

<Card title="API Reference" icon="link" href="https://developers.hubspot.com/docs/guides/api/app-management/webhooks">
  [https://developers.hubspot.com/docs/guides/api/app-management/webhooks](https://developers.hubspot.com/docs/guides/api/app-management/webhooks)
</Card>

<Card title="HubSpot Developer Portal" icon="link" href="https://developers.hubspot.com">
  [https://developers.hubspot.com](https://developers.hubspot.com)
</Card>


# Overview
Source: https://docs.stackone.com/integration-guides/crm/overview



Most API integrations work without additional configuration using the standard StackOne API [connector configuration](/guides/embedding-stackone-hub). See our standard [connector guides](https://hub.stackone.com/integrations) for setting up a customer account.

For some providers additional setup is required to allow them to communicate with the StackOne platform or to enable new features to the existing integration and workflows beyond the scope of our standard integration offerings.&#x20;

The customer may also be presented with further configuration options to setup the integration to suit their particular environment. Depending on the integration they may also be expected see changes on their front end-use of the underlying systems.

These guides are usually optional and are only required for specific purposes.


# Confluence Integration
Source: https://docs.stackone.com/integration-guides/documents/confluence-documents-integration



# StackOne File Picker Integration: Confluence

StackOne integrates with **Atlassian Confluence** to support document selection and navigation through Confluence spaces and pages. Unlike traditional file systems, Confluence is a **knowledge base platform**. Its "pages" can act as both **files** and **folders** depending on how they are used.

This document explains how StackOne models Confluence content, how we use the API, and how the custom file picker behaves.

***

## Confluence Structure vs StackOne Model

| Confluence Concept     | StackOne Equivalent | Notes                                         |
| ---------------------- | ------------------- | --------------------------------------------- |
| **Space**              | `drive`             | Top-level container for content within a site |
| **Page with children** | `folder/file`       | A page can act as both a folder and a file    |

* **Duality of Pages**:
  Confluence pages can behave as both **folders and files**. StackOne surfaces this by:
  * Including all pages in both the **`listFolders`** and **`listFiles`** endpoints
  * Adding metadata flags to indicate whether a page has **content**, **children**, or both

## File Download

Confluence offers two endpoints for downloading files:

* `GET exportword?pageId={.id}`
* `GET /wiki/rest/api/content/{id}?expand=body.export_view`

These allow the download of files in either:

* **Word**
* **HTML**

StackOne uses the second endpoint to download files natively and allow the export of files as .doc.

***

## File Picker Flow

The Confluence File Picker is **custom-built by StackOne** to present a consistent folder-like interface.

### Navigation Flow

1. **Site Selection**
   Users first select a **site** (Confluence instance), if multiple are connected.
2. **Space Listing**
   StackOne loads all **spaces** (mapped to drives) within the site.
3. **Top-Level Pages**
   Once a space is selected, users see a tree of pages. Each page is:
   * Clickable as a **file** (if it has content)
   * Expandable as a **folder** (if it has children)
4. **Nested Pages**
   Pages can be expanded recursively to reveal their nested children.
5. **Selection Options**
   Users can:
   * Select a page as a file (if it contains content)
   * Navigate through it as a folder (if it contains child pages)

***

## StackOne Modeling Approach

| StackOne Model Object | How It Maps to Confluence                                           |
| --------------------- | ------------------------------------------------------------------- |
| `drive`               | A Confluence **space**                                              |
| `folder`              | A **page** with child pages                                         |
| `file`                | A **page** with content or an attached document                     |
| `metadata`            | Indicates if an item has `hasContent`, `hasChildren`, or both       |
| `path`                | Virtualized to reflect the nested hierarchy of pages within a space |

***

## API Usage

StackOne uses the **CQL (Confluence Query Language) API** to efficiently retrieve content and metadata.

| Operation                 | API Used                                            | Notes                                       |
| ------------------------- | --------------------------------------------------- | ------------------------------------------- |
| List sites                | Configured in StackOne per connected account        | No Confluence API call; configuration-level |
| List spaces in site       | `GET /wiki/rest/api/space`                          | Lists all available spaces                  |
| List pages in a space     | `GET /wiki/rest/api/content/search?cql=...`         | Filters top-level or nested pages using CQL |
| Upload attachment to page | `POST /api/v2/pages`                                | Used for file uploads                       |
| Download attachment       | `GET rest/api/content/{id}?expand=body.export_view` | Direct file download endpoint               |

* **Search Strategy**:
  * StackOne uses **CQL queries** to list content scoped to a space and parent page
  * This allows accurate retrieval of both files and folders under any point in the hierarchy
* **Handling Dual-Use Pages**:
  * A page may appear as both a file and a folder
  * StackOne reflects this with flags and exposes both capabilities in the picker

***

## File Semantics

| Type               | Displayed As             | Condition                    |
| ------------------ | ------------------------ | ---------------------------- |
| Page with body     | File (can be selected)   | `body.storage.value` present |
| Page with children | Folder (can be expanded) | `ancestors.length > 0`       |

* Pages without content or children are still shown but cannot be selected
* Pages with **both** content and children can be both selected and expanded

***

## Permissions & Auth

* **API Token** with optional scopes
  * Maximum 1-year expiry
* Full set of integration scopes:
  * `write:confluence-content`
  * `read:confluence-space.summary`
  * `read:confluence-props	`
  * `write:confluence-props`
  * `read:confluence-content.all`
  * `read:confluence-content.summary`
  * `search:confluence`
  * `readonly:content.attachment:confluence`

***

## Summary

| Area                   | Confluence                                                 |
| ---------------------- | ---------------------------------------------------------- |
| Picker UX              | Custom-built hierarchical UI                               |
| Root Model             | Site → Space → Page (acts as file/folder)                  |
| File API               | CQL-based search of pages and attachments                  |
| Folder Behavior        | Pages act as folders if they contain child pages           |
| File Behavior          | Pages act as files if they have content or attachments     |
| Selection Logic        | Pages can be both selectable and expandable simultaneously |
| StackOne Normalization | All content mapped to unified `file` / `folder` objects    |


# GoogleDrive Partner OAuth
Source: https://docs.stackone.com/integration-guides/documents/googledrive-partner-oauth

To integrate the GoogleDrive with StackOne, please follow these essentials steps

## Log in to Google Cloud Console

Log in to your Google Cloud Console at [https://console.cloud.google.com](https://console.cloud.google.com)

<Frame>
  <img alt="Log in" />
</Frame>

## Create or Select a project

Create a new project or select an working project from projects list.

<Frame>
  <img alt="Create or select project" />
</Frame>

## Configure Google OAuth

<Steps>
  <Step title="Navigate to OAuth consent screen">
    In the left navigation menu, click **APIs & Services > OAuth consent screen**

    <Frame>
      <img alt="Navigate to OAuth consent screen" />
    </Frame>
  </Step>

  <Step title="Configure Google Auth platform">
    Click on **GET STARTED** button in OAuth Overview page.

    <Frame>
      <img alt="Copy Your Domain" />
    </Frame>
  </Step>

  <Step title="Enter App details">
    Enter the App name and User support email, then click on next button

    <Frame>
      <img alt="Copy Your Domain" />
    </Frame>
  </Step>

  <Step title="Select Audience type">
    Select Audience type and click next button

    <Frame>
      <img alt="Copy Your Domain" />
    </Frame>
  </Step>

  <Step title="Enter Contact information">
    Enter contact email address and click on next button

    <Frame>
      <img alt="Copy Your Domain" />
    </Frame>
  </Step>

  <Step title="Finish the configuration process">
    Read the Google policies and click on Checkbox, then click on create button to finish.

    <Frame>
      <img alt="Copy Your Domain" />
    </Frame>
  </Step>

  <Step title="Select Required Application Scopes">
    Click the **Add or Remove Scopes** button, and a popup window will appear on the right titled *Update selected scopes*.

    Enable the following scope which is required for full functionality of this integration:

    * `https://www.googleapis.com/auth/drive.file`

    You can copy and paste the scope into the **Filter** bar to quickly locate them.

    Once the scope have been enabled, click the **Update** button to proceed.

    <Frame>
      <img alt="Update Scopes Button" />
    </Frame>
  </Step>
</Steps>

## Generate OAuth2 Client Credentials

<Steps>
  <Step title="Navigate to OAuth Clients">
    In the left navigation menu, click **Google Auth Platform > Clients**

    <Frame>
      <img alt="Navigate to OAuth Clients" />
    </Frame>
  </Step>

  <Step title="Create Client">
    Click on **CREATE CLIENT** button to create OAuth Client app

    <Frame>
      <img alt="Create Client" />
    </Frame>
  </Step>

  <Step title="Enter Client App details">
    Select **Web application** from Application type dropdown, Enter the Client App name and redirect URL as `https://api.stackone.com/connect/oauth2/googledrive/callback`, then click on CREATE button

    <Frame>
      <img alt="Enter Client App details" />
    </Frame>
  </Step>

  <Step title="Copy Client Credentials">
    Select you Client App from the the displayed **OAuth 2.0 Client IDs** list. Copy and store Client ID and Client Secret to be used in later steps.

    <Frame>
      <img alt="Copy Your Domain" />
    </Frame>
  </Step>
</Steps>

## Enable the Google Drive API

Google requires manually enabling APIs for your account. The [Google Drive API](https://developers.google.com/drive) provides the underlying endpoints for this Documents connection.

<Steps>
  <Step title="Navigate to the API Library">
    In the left navigation menu, click **APIs & Services > Library**

    <Frame>
      <img alt="Navigate to the API Library" />
    </Frame>
  </Step>

  <Step title="Locate the Google Drive API">
    Using the search bar, enter a search for *"Google Drive"*. Click the **Google Drive API** result.

    <Frame>
      <img alt="Locate the Admin SDK API" />
    </Frame>
  </Step>

  <Step title="Enable the Google Drive API">
    Click the **Enable** button to enable the Google Drive API for your organization.

    <Frame>
      <img alt="Enable the Admin SDK API" />
    </Frame>
  </Step>

  <Step title="Locate the Google Picker API">
    Similar as above, using the search bar, enter a search for *"Picker API"*. Click the **Google Picker API** result.

    <img alt="Google Drive Picker Api List Pn" />
  </Step>

  <Step title="Enable the Google Picker API">
    Click the **Enable** button to enable the Google Picker API for your organization.

    <img alt="Google Picker Api Enable Pn" />
  </Step>
</Steps>

## To Enable and Connect the Integration

<Steps>
  <Step title="Enable GoogleDrive">
    Navigate to the Documents category on the Integrations page and enable GoogleDrive.

    <Frame>
      <img alt="Enter Credentials" />
    </Frame>
  </Step>

  <Step title="Enter Credentials">
    Please complete the necessary fields in the **GoogleDrive - Configuration** model:

    * **Authentication Type** - Please select the **OAuth2 - Google Drive Partner Credentials** to integrate with the Google Drive Partner.
    * **Client ID**
    * **Client Secret**
    * **Scopes** - If you selected only the required scopes in the previous steps, leave the default value for this field. Otherwise, enter the space-separated list of scopes granted to your application.
    * **Redirect URI** - (optional) - If you are using your own OAuth2 credentials, enter the redirect URI that you configured in the Google Cloud Console. Otherwise, leave this field blank. For more information, see [OAuth Proxy Redirect](/integration-guides/oauth-proxy-redirect).

    Proceed by clicking the Save Changes button.

    <Frame>
      <img alt="Enter Credentials" />
    </Frame>
  </Step>

  <Step title="Connect to GoogleDrive">
    Click the Connect button to start the login process. You will be redirected to Google Drive.

    <Frame>
      <img alt="Connect to GoogleDrive" />
    </Frame>
  </Step>

  <Step title="Grant OAuth Application Consent">
    A window will appear and may prompt you to log in to your Google Drive account.

    After logging in, you will be displayed the OAuth consent screen you configured.

    Click the **Allow** button to grant the application access to your Google Drive account.

    <Frame>
      <img alt="Grant OAuth Application Consent" />
    </Frame>
  </Step>
</Steps>


# Onedrive Partner OAuth
Source: https://docs.stackone.com/integration-guides/documents/onedrive-oauth

Follow these steps to connect Onedrive via the StackOne Hub successfully.

<Warning>
  Ensure that your Microsoft account has the "[**Global Administrator**](https://learn.microsoft.com/en-us/microsoft-365/admin/add-users/about-admin-roles?view=o365-worldwide#permissions-based-on-admin-role-and-group-type-in-m365-admin-page)" and "[**OneDrive Administrator**](https://learn.microsoft.com/en-us/sharepoint/sharepoint-admin-role)"   Roles assigned.

  \
  You can view and manage user role assignments in your [Microsoft Admin center](https://admin.microsoft.com/Adminportal/Home#/users).
</Warning>

<Info>
  For users outside of your organization to connect with your Microsoft application, a Microsoft Partner Center account is required. [Read more](https://learn.microsoft.com/en-gb/entra/identity-platform/publisher-verification-overview)

  Your Microsoft application must have your **MPN ID** assigned under *Branding & Properties* > *Publisher Verification:*

  <Frame>
    <img alt="OneDrive Mpn Pn" />
  </Frame>
</Info>

If you've been directed to StackOne to integrate with OneDrive, the following steps will help you understand the process and any necessary actions to configure a successful integration.

## Create and Configure a New Application

<Steps>
  <Step title="Log in to Microsoft Azure">
    Log in to your [Microsoft Azure](https://portal.azure.com/) portal.

    <Frame>
      <img alt="Azure Login Pn" />
    </Frame>
  </Step>

  <Step title="Navigate to App Registrations">
    Go to your [Microsoft Entra admin center](https://entra.microsoft.com/).

    In the left navigation bar, click "Applications" > "App registrations".

    <Frame>
      <img alt="Ms Entra App Registrations Pn" />
    </Frame>
  </Step>

  <Step title="Register a New Application">
    Under ***App Registrations***, click the "+ New registration" button.

    <Frame>
      <img alt="Ms Entra New App Registration Btn Pn" />
    </Frame>
  </Step>

  <Step title="Configure Application Details">
    Under ***Register an application***, input the following details:

    * Name
    * Supported account types
      * Select "*Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts*"
    * Redirect URI
      * Select "*Web*"
      * Enter the URI: `https://api.stackone.com/connect/oauth2/onedrive/callback`

    Once complete, click "Register" to create the new application.

    <Frame>
      <img alt="Ms Entra New App Docs OneDrive Details Pn" />
    </Frame>
  </Step>

  <Step title="Obtain the App Client ID and Tenant ID">
    After registration, you'll be taken to the application overview page.

    **Copy** <Icon icon="clipboard" /> the following values and store them safely to be used in a later step:

    * Application (client) ID
    * Directory (tenant) ID

    <Frame>
      <img alt="Ms Entra App Client Id OneDrive" />
    </Frame>
  </Step>

  <Step title="Obtain the Application Client Secret">
    Under *Client credentials* on the right, click "Add a certificate or secret".

    <Frame>
      <img alt="Ms Entra App Click Client Secret Pn" />
    </Frame>

    Under *Client secrets*, click the "+ New client secret" button.

    <Frame>
      <img alt="Ms Entra New App Client Secret OneDrive Pn" />
    </Frame>

    Under *Add a client secret*, enter a description and select your desired expiration date for this secret.

    <Info>
      Please keep in mind that a new secret will need to be generated when this one expires.
    </Info>

    Click the "Add" button to proceed.

    <Frame>
      <img alt="Ms Entra New Client Secret Details OneDrive Pn" />
    </Frame>

    The new client secret will be displayed. **Copy** <Icon icon="clipboard" /> the **Value** and store it safely to be used in a later step.

    <Warning>
      Make sure to copy this value now. It will not be displayed again.
    </Warning>

    <Frame>
      <img alt="Ms Entra Copy Client Secret Value Pn" />
    </Frame>
  </Step>

  <Step title="Set the Application API Permissions">
    Click "API permissions" near the left navigation.

    <Frame>
      <img alt="Ms Entra App Api Permissions Pn" />
    </Frame>

    Under *Configured permissions*, click the "Add a permission" button.

    <Frame>
      <img alt="Ms Entra Add App Api Permission OneDrive Pn" />
    </Frame>

    Under *Request API permissions*, click "Microsoft Graph".

    <Frame>
      <img alt="Ms Entra App Api Permissions Microsoft Gro Pn" />
    </Frame>

    The application requires the following permissions.

    **Delegated Permissions**

    * **Files.Read** - Read user files
    * **Files.Read.All** - Read all files that user can access
    * **Files.ReadWrite** - Read and upload user files
    * **offline\_access** - Maintain access to data you have given it access to
    * **Sites.Read.All** - Read items in all site collections
    * **Sites.ReadWrite.All** - Edit or delete items in all site collections
    * **User.Read** - Sign in and read user profile
    * **User.ReadBasic.All** - Read all users' basic profiles

    After selecting all of the listed permissions above, click the "Add permissions" button.

    <Frame>
      <img alt="Ms Entra App Api Permissions OneDrive Pn" />
    </Frame>
  </Step>

  <Step title="Grant Admin Consent for Application Permissions">
    All of the added permissions will be listed under *Configured permissions*. Please ensure that all of the permissions above are listed.

    Click the "Grant admin consent" button to approve all of the listed permissions.

    Click the "Yes" button to confirm Admin approval.

    <Frame>
      <img alt="Ms Entra Confirm Admin Consent Pn" />
    </Frame>
  </Step>

  <Step title="Add Single-Page Application Redirect URI">
    To support the File Picker, an additional Redirect URI is required for the Single-Page Application platform configuration.

    Navigate to **Authentication** under *Manage*, and click the "Add a platform" button.

    <Frame>
      <img alt="Share Point Auth Add Platform Btn Pn" />
    </Frame>

    Under *Configure Platforms* on the right, click **Single-page application**.

    <Frame>
      <img alt="OneDrive Spa Platform Pn" />
    </Frame>

    Enter the following **Redirect URI**:\
    `https://app.stackone.com`

    <Frame>
      <img alt="OneDrive Spa Redirect Pn" />
    </Frame>

    Press the "**Configure**" button to continue, then the "**Save**" button in the *Authorization* screen you are returned to.
  </Step>
</Steps>

### Get your SharePoint Base URL

Your OneDrive base URL follows this format:

```
https://{your-domain}.sharepoint.com
```

You can find this URL by:

1. Opening your Microsoft OneDrive site
2. Copying the base URL from your browser's address bar

<br />

Congratulations, you're all set!

## Available data

This integration has the following [Documents Resources](https://docs.stackone.com/reference/getting-started-with-your-api) available from the provider:

* Drives
* Files
* Folders


# Overview
Source: https://docs.stackone.com/integration-guides/documents/overview

Introduction to integrating and configuring document provider connections, OAuth setup, and using the StackOne Documents API and File Picker for unified file access

Most API integrations work without additional configuration using the standard StackOne API [connector configuration](/guides/embedding-stackone-hub). See our standard [connector guides](https://hub.stackone.com/integrations) for setting up a customer account.

For some providers additional setup is required to allow them to communicate with the StackOne platform or to enable new features to the existing integration and workflows beyond the scope of our standard integration offerings.&#x20;

The customer may also be presented with further configuration options to setup the integration to suit their particular environment. Depending on the integration they may also be expected see changes on their front end-use of the underlying systems.

These guides are usually optional and are only required for specific purposes.

## Supported Document Providers

#### Key Providers Supported

<Warning>
  **OAuth Application Setup Required**: Some providers may require creating OAuth applications and configuring credentials. See the [Documents Integration Guides](/integration-guides/documents/overview) for provider-specific setup instructions, including [Google Drive](/integration-guides/documents/googledrive-partner-oauth), [SharePoint](/integration-guides/documents/sharepoint-oauth), and [OneDrive](/integration-guides/documents/onedrive-oauth) OAuth configurations.
</Warning>

| Provider         | Picker Type | Navigation                   | Multi-Select | File Types      |
| ---------------- | ----------- | ---------------------------- | ------------ | --------------- |
| **SharePoint**   | Native      | Site → Drive → Folder → File | ✅            | All documents   |
| **OneDrive**     | Native      | Drive → Folder → File        | ✅            | All documents   |
| **Google Drive** | Native      | Drive → Folder → File        | ✅            | All documents   |
| **Confluence**   | Custom      | Space → Page                 | ✅            | Pages/Documents |
| **Notion**       | Custom      | Workspace → Page             | ✅            | Pages/Blocks    |

For other providers, you can check support in the [StackOne's integration page](https://www.stackone.com/integrations) or your Dashboard's [field coverage page](https://app.stackone.com/field_coverage) or request a new integration via our in-app, slack or email support.


# Sharepoint & Onedrive
Source: https://docs.stackone.com/integration-guides/documents/sharepoint-and-onedrive



# StackOne File Picker Integrations: SharePoint vs OneDrive

StackOne supports file selection from **Microsoft SharePoint** and **OneDrive** via Microsoft Graph API. While both services use the same API surface, their **data models**, **hierarchies**, and **access scopes** differ, especially around SharePoint's **site-based structure**.

This document outlines how StackOne models and integrates these services in a consistent developer-facing experience.

***

## File Picker Overview

* **Native File Picker**:
  Both **SharePoint** and **OneDrive** use Microsoft’s **native file picker** components for the file and folder interface.

* **Custom Site Picker (SharePoint only)**:
  For SharePoint, StackOne builds a **custom site selection layer** on top of the native picker. This allows users to:

  * Choose a SharePoint **site**
  * Then proceed to the native SharePoint file picker scoped to that site’s drives and folders

* **Unified Selection Model**:
  Regardless of source (SharePoint or OneDrive), selected files and folders are normalized into a common StackOne format in both UI and API.

***

## Technical Architecture Comparison

| Feature / Concept            | **SharePoint**                                                                                     | **OneDrive**                                                       |
| ---------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| **File Storage Model**       | Organization → Sites → Drives → Folders → Files                                                    | Drive → Folders → Files                                            |
| **Site Abstraction**         | Required. Files are grouped under named SharePoint **sites**                                       | Not applicable. One flat drive per user                            |
| **Drives per Site**          | One or more **drives** per site (typically document libraries)                                     | Single drive per user                                              |
| **Multi-Site Support**       | Yes. StackOne iterates all accessible sites and drives                                             | Not applicable                                                     |
| **Graph API Root Endpoint**  | `/sites/{site-id}/drives/{drive-id}`                                                               | `/me/drive` or `/users/{user-id}/drive`                            |
| **File Discovery in Picker** | Site selection (custom) → Native SharePoint picker for drive/folder browsing                       | Direct native picker for user’s OneDrive content                   |
| **Pages Support**            | SharePoint Pages (e.g. `.aspx`) are **excluded** from file API responses                           | N/A                                                                |
| **File List API Behavior**   | StackOne aggregates and returns **all files from all sites/drives** in a unified list via `/files` | StackOne returns files from the user’s OneDrive drive via `/files` |
| **Underlying Picker UI**     | Native SharePoint file picker (after custom site selection)                                        | Native OneDrive file picker                                        |

***

## StackOne Modeling Strategy

Both integrations are abstracted into the same file model and API schema. Internally:

| Object Type              | StackOne Model Notes                                                                        |
| ------------------------ | ------------------------------------------------------------------------------------------- |
| `File`                   | Includes `id`, `name`, `path`, `mime_type`, `size`, `modified_at`, `download_url`, `source` |
| `Folder`                 | Includes `id`, `name`, `path`, `parent_id`, and `owner_id` if browsing recursively          |
| `Drive`                  | Mapped directly from Graph API; grouped under sites for SharePoint                          |
| `Site` (SharePoint only) | Populated via Graph API, shown to users as custom selector before native picker             |

***

## API Comparison

Here’s how the underlying Microsoft Graph API calls differ between the two integrations.

| Operation                 | **SharePoint**                                                      | **OneDrive**                            |
| ------------------------- | ------------------------------------------------------------------- | --------------------------------------- |
| Discover sites            | `GET /sites?search=*` or `GET /sites/{tenant}.sharepoint.com/sites` | N/A                                     |
| List drives in a site     | `GET /sites/{site-id}/drives`                                       | N/A (one drive per user)                |
| List root folder contents | `GET /sites/{site-id}/drives/{drive-id}/root/children`              | `GET /me/drive/root/children`           |
| Get file metadata         | `GET /sites/{site-id}/drives/{drive-id}/items/{item-id}`            | `GET /me/drive/items/{item-id}`         |
| Download file             | `GET /sites/{site-id}/drives/{drive-id}/items/{item-id}/content`    | `GET /me/drive/items/{item-id}/content` |
| StackOne file listing     | Aggregated from all sites/drives into one list                      | Pulled from user's root drive           |

***

## Implementation Details

* **Authentication**:

  * Microsoft Identity Platform (OAuth 2.0)
  * Required scopes:

    * `Files.Read`, `Files.Read.All`
    * `Sites.Read.All` (SharePoint only)

* **Pagination Support**:

  * All Microsoft Graph list endpoints are paginated via `@odata.nextLink`
  * StackOne SDKs handle pagination and aggregation transparently

* **File Filtering**:

  * SharePoint Pages (HTML content) are excluded
  * OneDrive integration shows files as they appear in the user's drive (including shared items)

* **Caching Strategy**:

  * Site metadata in SharePoint may be cached per session for performance
  * Drives and folders are lazily loaded as users navigate via the picker

***

## Summary

| Area                        | SharePoint                                     | OneDrive                                 |
| --------------------------- | ---------------------------------------------- | ---------------------------------------- |
| Picker UX                   | Native SharePoint picker with custom site step | Native OneDrive picker                   |
| Scoping Model               | Site → Drive → Folder → File                   | Drive → Folder → File                    |
| File List API               | Aggregated across all sites                    | Scoped to single personal/business drive |
| API Surface                 | Microsoft Graph                                | Microsoft Graph                          |
| StackOne File Object Output | Unified format                                 | Unified format                           |

***

Let me know if you'd like this exported to Markdown, Notion, or built into an internal developer doc format.


# Sharepoint Partner OAuth
Source: https://docs.stackone.com/integration-guides/documents/sharepoint-oauth

Follow these steps to connect Sharepoint via the StackOne Hub successfully.

<Warning>
  Ensure that your Microsoft account has the "[**Global Administrator**](https://learn.microsoft.com/en-us/microsoft-365/admin/add-users/about-admin-roles?view=o365-worldwide#permissions-based-on-admin-role-and-group-type-in-m365-admin-page)" and "[**SharePoint Administrator**](https://learn.microsoft.com/en-us/sharepoint/sharepoint-admin-role)"   Roles assigned.

  \
  You can view and manage user role assignments in your [Microsoft Admin center](https://admin.microsoft.com/Adminportal/Home#/users).
</Warning>

<Info>
  For users outside of your organization to connect with your Microsoft application, a Microsoft Partner Center account is required. [Read more](https://learn.microsoft.com/en-gb/entra/identity-platform/publisher-verification-overview)

  Your Microsoft application must have your **MPN ID** assigned under *Branding & Properties* > *Publisher Verification:*

  <Frame>
    <img alt="Sharepoint Mpn Pn" />
  </Frame>
</Info>

If you've been directed to StackOne to integrate with Sharepoint, the following steps will help you understand the process and any necessary actions to configure a successful integration.

## Create and Configure a New Application

<Steps>
  <Step title="Log in to Microsoft Azure">
    Log in to your [Microsoft Azure](https://portal.azure.com/) portal.

    <Frame>
      <img alt="Azure Login Pn" />
    </Frame>
  </Step>

  <Step title="Navigate to App Registrations">
    Go to your [Microsoft Entra admin center](https://entra.microsoft.com/).

    In the left navigation bar, click "Applications" > "App registrations".

    <Frame>
      <img alt="Ms Entra App Registrations Pn" />
    </Frame>
  </Step>

  <Step title="Register a New Application">
    Under ***App Registrations***, click the "+ New registration" button.

    <Frame>
      <img alt="Ms Entra New App Registration Btn Pn" />
    </Frame>
  </Step>

  <Step title="Configure Application Details">
    Under ***Register an application***, input the following details:

    * Name
    * Supported account types
      * Select "*Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts*"
    * Redirect URI
      * Select "*Web*"
      * Enter the URI: `https://api.stackone.com/connect/oauth2/sharepoint/callback`

    Once complete, click "Register" to create the new application.

    <Frame>
      <img alt="Ms Entra New App Docs Sharepoint Details Pn" />
    </Frame>
  </Step>

  <Step title="Obtain the App Client ID and Tenant ID">
    After registration, you'll be taken to the application overview page.

    **Copy** <Icon icon="clipboard" /> the following values and store them safely to be used in a later step:

    * Application (client) ID
    * Directory (tenant) ID

    <Frame>
      <img alt="Ms Entra App Client Id Sharepoint" />
    </Frame>
  </Step>

  <Step title="Obtain the Application Client Secret">
    Under *Client credentials* on the right, click "Add a certificate or secret".

    <Frame>
      <img alt="Ms Entra App Click Client Secret Pn" />
    </Frame>

    Under *Client secrets*, click the "+ New client secret" button.

    <Frame>
      <img alt="Ms Entra New App Client Secret Sharepoint Pn" />
    </Frame>

    Under *Add a client secret*, enter a description and select your desired expiration date for this secret.

    <Info>
      Please keep in mind that a new secret will need to be generated when this one expires.
    </Info>

    Click the "Add" button to proceed.

    <Frame>
      <img alt="Ms Entra New Client Secret Details Sharepoint Pn" />
    </Frame>

    The new client secret will be displayed. **Copy** <Icon icon="clipboard" /> the **Value** and store it safely to be used in a later step.

    <Warning>
      Make sure to copy this value now. It will not be displayed again.
    </Warning>

    <Frame>
      <img alt="Ms Entra Copy Client Secret Value Pn" />
    </Frame>
  </Step>

  <Step title="Set the Application API Permissions">
    Click "API permissions" near the left navigation.

    <Frame>
      <img alt="Ms Entra App Api Permissions Pn" />
    </Frame>

    Under *Configured permissions*, click the "Add a permission" button.

    <Frame>
      <img alt="Ms Entra Add App Api Permission Sharepoint Pn" />
    </Frame>

    Under *Request API permissions*, click "Microsoft Graph".

    <Frame>
      <img alt="Ms Entra App Api Permissions Microsoft Gro Pn" />
    </Frame>

    The application requires the following permissions.

    **Delegated Permissions**

    * **Files.Read** - Read user files
    * **Files.Read.All** - Read all files that user can access
    * **Files.ReadWrite** - Read and upload user files
    * **offline\_access** - Maintain access to data you have given it access to
    * **Sites.Read.All** - Read items in all site collections
    * **Sites.ReadWrite.All** - Edit or delete items in all site collections
    * **User.Read** - Sign in and read user profile
    * **User.ReadBasic.All** - Read all users' basic profiles

    After selecting all of the listed permissions above, click the "Add permissions" button.

    <Frame>
      <img alt="Ms Entra App Api Permissions Sharepoint Pn" />
    </Frame>
  </Step>

  <Step title="Grant Admin Consent for Application Permissions">
    All of the added permissions will be listed under *Configured permissions*. Please ensure that all of the permissions above are listed.

    Click the "Grant admin consent" button to approve all of the listed permissions.

    Click the "Yes" button to confirm Admin approval.

    <Frame>
      <img alt="Ms Entra Confirm Admin Consent Pn" />
    </Frame>
  </Step>

  <Step title="Add Single-Page Application Redirect URI">
    To support the File Picker, an additional Redirect URI is required for the Single-Page Application platform configuration.

    Navigate to **Authentication** under *Manage*, and click the "Add a platform" button.

    <Frame>
      <img alt="Share Point Auth Add Platform Btn Pn" />
    </Frame>

    Under *Configure Platforms* on the right, click **Single-page application**.

    <Frame>
      <img alt="Sharepoint Spa Platform Pn" />
    </Frame>

    Enter the following **Redirect URI**:\
    `https://app.stackone.com`

    <Frame>
      <img alt="Sharepoint Spa Redirect Pn" />
    </Frame>

    Press the "**Configure**" button to continue, then the "**Save**" button in the *Authorization* screen you are returned to.
  </Step>
</Steps>

### Get your SharePoint Base URL

Your SharePoint base URL follows this format:

```
https://{your-domain}.sharepoint.com
```

You can find this URL by:

1. Opening your Microsoft SharePoint site
2. Copying the base URL from your browser's address bar

<br />

Congratulations, you're all set!

## Available data

This integration has the following [Documents Resources](https://docs.stackone.com/reference/getting-started-with-your-api) available from the provider:

* Drives
* Files
* Folders


# SharePoint Client OAuth (Single-Tenant)
Source: https://docs.stackone.com/integration-guides/documents/sharepoint-private-oauth

Connect SharePoint via a single-tenant Microsoft app with delegated permissions using the StackOne Hub.

Ensure that your Microsoft account has the "[Global Administrator](https://learn.microsoft.com/en-us/microsoft-365/admin/add-users/about-admin-roles?view=o365-worldwide#permissions-based-on-admin-role-and-group-type-in-m365-admin-page)" and "[SharePoint Administrator](https://learn.microsoft.com/en-us/sharepoint/sharepoint-admin-role)" roles assigned.

You can view and manage user role assignments in your [Microsoft Admin center](https://admin.microsoft.com/Adminportal/Home#/users).

<Info>
  This guide configures a single-tenant SharePoint app for use within your organization only. Users outside your organization cannot connect with this app. No Microsoft Partner Center account or publisher verification is required.
</Info>

If you've been directed to StackOne to integrate with SharePoint using a single-tenant app, the following steps will help you configure a successful integration.

## Create and Configure a New Application

<Steps>
  <Step title="Log in to Microsoft Azure">
    Log in to your [Microsoft Azure](https://portal.azure.com/) portal.

    <Frame>
      <img alt="Azure Login Pn" />
    </Frame>
  </Step>

  <Step title="Navigate to App Registrations">
    Go to your [Microsoft Entra admin center](https://entra.microsoft.com/).

    In the left navigation bar, click "Applications" > "App registrations".

    <Frame>
      <img alt="Ms Entra App Registrations Pn" />
    </Frame>
  </Step>

  <Step title="Register a New Application">
    Under ***App Registrations***, click the "+ New registration" button.

    <Frame>
      <img alt="Ms Entra New App Registration Btn Pn" />
    </Frame>
  </Step>

  <Step title="Configure Application Details">
    Under ***Register an application***, input the following details:

    * Name
    * Supported account types
      * Select "*Accounts in this organizational directory only (Single tenant)*"
    * Redirect URI
      * Select "*Web*"
      * Enter the URI: `https://api.stackone.com/connect/oauth2/sharepoint/callback`

    Once complete, click "Register" to create the new application.

    <Frame>
      <img alt="Ms Entra Register App Sharepoint Single Tenant" />
    </Frame>
  </Step>

  <Step title="Obtain the App Client ID and Tenant ID">
    After registration, you'll be taken to the application overview page.

    **Copy** <Icon icon="clipboard" /> the following values and store them safely to be used in a later step:

    * Application (client) ID
    * Directory (tenant) ID

    <Frame>
      <img alt="Ms Entra App Client Id Sharepoint" />
    </Frame>
  </Step>

  <Step title="Obtain the Application Client Secret">
    Under *Client credentials* on the right, click "Add a certificate or secret".

    <Frame>
      <img alt="Ms Entra App Click Client Secret Pn" />
    </Frame>

    Under *Client secrets*, click the "+ New client secret" button.

    <Frame>
      <img alt="Ms Entra New App Client Secret Sharepoint Pn" />
    </Frame>

    Under *Add a client secret*, enter a description and select your desired expiration date for this secret.

    <Info>
      Please keep in mind that a new secret will need to be generated when this one expires.
    </Info>

    Click the "Add" button to proceed.

    <Frame>
      <img alt="Ms Entra New Client Secret Details Sharepoint Pn" />
    </Frame>

    The new client secret will be displayed. **Copy** <Icon icon="clipboard" /> the **Value** and store it safely to be used in a later step.

    <Warning>
      Make sure to copy this value now. It will not be displayed again.
    </Warning>

    <Frame>
      <img alt="Ms Entra Copy Client Secret Value Pn" />
    </Frame>

    Under *Configured permissions*, click the "Add a permission" button.

    Under *Request API permissions*, click "Microsoft Graph".

    <Frame>
      <img alt="Ms Entra App Api Permissions Microsoft Gro Pn" />
    </Frame>

    The application requires the following **Delegated Permissions**:

    * **Files.Read** - Read user files
    * **Files.Read.All** - Read all files that user can access
    * **Files.ReadWrite** - Read and upload user files
    * **offline\_access** - Maintain access to data you have given it access to
    * **User.Read** - Sign in and read user profile
    * **User.ReadBasic.All** - Read all users' basic profiles

    After selecting all of the listed permissions above, click the "Add permissions" button.
  </Step>

  <Step title="Grant Admin Consent for Permissions">
    All of the added permissions will be listed under *Configured permissions*. Please ensure that all of the permissions above are listed.

    Click the "Grant admin consent" button to approve all of the listed permissions.

    Click the "Yes" button to confirm Admin approval.

    <Frame>
      <img alt="Ms Entra Confirm Admin Consent Pn" />
    </Frame>
  </Step>
</Steps>

## User consent settings and non-admin connections

Tenant-wide [user consent settings](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/configure-user-consent) in Microsoft Entra ID (Identity > Applications > Enterprise apps > Consent and permissions > User consent settings) affect when non-admin users can connect to this single-tenant app without prior admin action.

### When "Let Microsoft manage your consent settings (Recommended)" is selected

This setting applies Microsoft’s managed consent policy. For a **single-tenant, unverified** app (like the one in this guide), non-admin users are often not allowed to grant consent on first use. In practice:

* **Option A:** An org admin connects via OAuth first and completes the consent screen. After that, non-admin users can connect without seeing the consent prompt.
* **Option B:** A non-admin user tries to connect first and is blocked (e.g. "Need admin approval"). An admin then goes to the app’s **Configured permissions** in the [Microsoft Entra admin center](https://entra.microsoft.com/) (Enterprise applications > your app > Permissions) and clicks **Grant admin consent**. After that, the non-admin user can connect successfully on a second attempt.

Granting admin consent only takes effect for the **Enterprise Application** (service principal) that is created when the app is first used in your tenant. If no user had connected yet, that object may not exist, which is why granting consent *before* any user attempt sometimes doesn’t help until after the first (failed) non-admin attempt.

### Allowing non-admins to connect on first attempt

To allow non-admin users to connect on their first attempt without an admin connecting first, change the tenant setting to **"Allow user consent for apps from verified publishers, for selected permissions"**.

That policy explicitly allows user consent for [apps registered in your organization](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/configure-user-consent) (single-tenant apps) as well as verified publishers, but only for permissions your org classifies as **low impact**. To avoid prompts for the permissions this app uses (e.g. Files.Read, User.Read, offline\_access), an admin may need to [classify those permissions as low impact](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/configure-permission-classifications) under Consent and permissions > Permission classifications. After that, non-admin users can typically complete the consent flow on first connection.

<Note>
  Changing to "Allow user consent for apps from verified publishers, for selected permissions" is a tenant-wide setting and may allow user consent for other apps registered in your tenant. Evaluate this against your organization’s security policy.
</Note>

### Get your SharePoint Base URL

Your SharePoint base URL follows this format:

```
https://{your-domain}.sharepoint.com
```

You can find this URL by:

1. Opening your Microsoft SharePoint site
2. Copying the base URL from your browser's address bar

<br />

Congratulations, you're all set!

## Available data

This integration has the following [Documents Resources](https://docs.stackone.com/reference/getting-started-with-your-api) available from the provider:

* Drives
* Files
* Folders


# SAP SuccessFactors Permission Configuration
Source: https://docs.stackone.com/integration-guides/hris/SapSuccessfactors-Permission-Configuration

Configuration of Permissions in SAP SuccessFactors

<Warning>
  The following guidance assumes you have Admin privileges for your SAP SuccessFactors account.
</Warning>

## Permission Settings

### Step 1: Role Configuration

<Steps>
  <Step title="Log in to SuccessFactors as an administrator" />

  <Step title="Navigate to Admin Center." />

  <Step title="In the Tools search bar, search for Manage Permission Roles." />

  <Step title="Choose an existing role or create a new role." />

  <Step title="If you choose a new role, on the Role Details page, enter the role name.">
    On the `Permission Role Details` page, enter the `Role Name` and `Description` in the first section.
  </Step>
</Steps>

### Step 2: Permission Configuration For Role

<Steps>
  <Step title="Select the Permission">
    On the `Permission Role Details` page, click the `Permissions` button in the second section.
  </Step>

  <Step title="Select the Module">
    Select the `module` for which you want to configure permissions. For example, to configure permissions for `Employee Central entities` such as Person, Employment, and Time Off, you can select `Employee_Central_Effective_Dated_Entities`.
  </Step>

  <Step title="Select the Entity">
    On the left side of the page, you will find a list of all entities for which you can configure `read (view)` and `write (edit)` permissions.

    * Selecting the View checkbox allows users to read data from a specific entity using the OData API.
    * Selecting the Edit checkbox grants users permission to write data to that entity using the Write OData API.
  </Step>

  <Step title="Click on Done" />
</Steps>

### Step 3: Assign Role

<Steps>
  <Step title="Assign the Role">
    On the Permission Role Details page, click the `Assignments` tab in `Manage Permission Roles` to assign this role to a group of users.
  </Step>

  <Step title="Select the Group">
    Click the `Add Role Assignment` button, select the `Role`, and then click the `Next` button.
  </Step>

  <Step title="Select the Users">
    In the next tab, select the `Employees` or `Groups` to which you want to assign the role.
  </Step>

  <Step title="Click on Save">
    In the final step, click the `Save` button to save your changes.
  </Step>
</Steps>

### Step 4: Click the `Save Changes` button on the Permission Role Details page to save all changes.

<br />

<br />

## Required configuration for resource mapping via StackOne APIs

### HRIS Resource and  Permissions Configuration

To access the HRIS OData APIs in Employee Central, ensure the following permissions are granted:

* Employee Central HRIS OData APIs – READ
* Employee Central HRIS OData APIs – EDIT
* OData Metadata API – READ

To grant field/object-level access, the following permissions should be assigned:

| Resource           | Fields                                                                                                                                               | Permission               | Category                                              |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | ----------------------------------------------------- |
| Employees          | `First Name`,`Last Name`,`Gender`,`Marital Status`,`Job Title`,`Supervisor`,`Nationality`,`Work Schedule`,`Country`                                  | View/Edit/Insert/Correct | `Employee Central Effective Dated Entities`           |
|                    | `Display Name`,`Date Of Birth`,`Email Address`,`Phone Number`,`First Date Worked`,`Hire Date`,`Original Start Date`,`Termination Date`,`National Id` | View/Edit                | `Employee Data`                                       |
|                    | `Department`,`Cost Center`,`Legal Entity`,`Job Classification`                                                                                       | View/Edit/Insert/Correct | `MDF Foundation Objects`                              |
| Employments        | `Job Title`,`FTE`,`Work Schedule`,`Standard Weekly Hours`,`Company`,`Supervisor`                                                                     | View/Edit/Insert/Correct | `Employee Central Effective Dated Entities`           |
|                    | `Hire Date`,`Termination Date`,`Job Code`                                                                                                            | View/Edit                | `Employee Data`                                       |
| Time Off &  Policy | `Is Fulltime Employee`,`Time Profile`,`Time In Position`,`Timezone`                                                                                  | View/Edit/Insert/Correct | `Employee Central Effective Dated Entities`           |
|                    | Select all permissions in `Time Management User Permissions` and `Manage Time Off`                                                                   | Select All               | `Time Management User Permissions`, `Manage Time Off` |


# ADP Workforce Now Employee Update Passthrough Usage
Source: https://docs.stackone.com/integration-guides/hris/adp-workforce-now-employee-update-passthrough

Learn how to use the passthrough parameter for non-standard employee update operations in ADP Workforce Now

## Overview

ADP Workforce Now requires a non-standard approach when updating employee information through the StackOne Update Employee endpoint. Instead of following the typical unified API flow, ADP WFN uses a specialized passthrough mechanism that allows direct interaction with ADP's event-based API structure.

## How the Passthrough Works

When updating an employee in ADP Workforce Now, the `passthrough` parameter operates differently from other providers:

* **Each key** in the `passthrough` object represents a **path segment** that gets appended to ADP's event API endpoint
* **Each value** is the **complete request body** that gets sent as a POST request to that specific endpoint

<Warning>
  **Critical** You must include the worker's 'associateOID' in the 'eventContext' for all operations. This is required to identify which employee to update. Without it, the request will fail. This is equivalent to the unified 'remote\_id' of the Employee being updated.
</Warning>

### Request Structure

The passthrough data is sent to ADP WFN using the following endpoint pattern:

```
POST /events/hr/v1/{{path}}
```

Where `{{path}}` is replaced by each key in your passthrough object.

## Example Usage

Here's an example of how to structure your Update Employee request with the passthrough parameter to update an employee's organizational units and military status:

```json theme={null}
{
  "passthrough": {
    "worker.work-assignment.organizational-units.change": {
      "events": [
        {
          "data": {
            "eventContext": {
              "worker": {
                "associateOID": "G5357R8DJ46DKM8P"
              }
            },
            "transform": {
              "worker": {
                "workAssignment": {
                  "organizationalUnits": [
                    {
                      "nameCode": {
                        "codeValue": "DEPT-001"
                      },
                      "typeCode": {
                        "codeValue": "Department"
                      }
                    },
                    {
                      "nameCode": {
                        "codeValue": "DIV-TECH"
                      },
                      "typeCode": {
                        "codeValue": "Division"
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      ]
    },
    "worker.military-status.change": {
      "events": [
        {
          "data": {
            "eventContext": {
              "worker": {
                "associateOID": "G5357R8DJ46DKM8P"
              }
            },
            "transform": {
              "worker": {
                "person": {
                  "militaryStatusCode": {
                    "codeValue": "D"
                  }
                }
              }
            }
          }
        }
      ]
    }
  }
}
```

In this example:

* The first operation sends a POST to `/events/hr/v1/worker.work-assignment.organizational-units.change`
* The second operation sends a POST to `/events/hr/v1/worker.military-status.change`
* Each request body contains the complete event structure required by ADP
* The `associateOID` (G5357R8DJ46DKM8P) identifies the worker being updated in both operations

## Finding the Right Operation Path and Body Structure

To determine the correct operation path and request body structure for your use case:

1. **Visit the ADP API Explorer**: [https://developers.adp.com/apis/api-explorer/hcm-offrg-wfn?domain=hr](https://developers.adp.com/apis/api-explorer/hcm-offrg-wfn?domain=hr)

2. **Browse the available operations** to find the specific employee update action you need

3. **Note the operation path name** - this becomes the key in your passthrough object
   * Example: If the API Explorer shows `worker.work-assignment.organizational-units.change`, use that exact string as the key

4. **Review the request body schema** - this becomes the value in your passthrough object

<Note>
  The ADP API Explorer provides comprehensive documentation on all available operations, required fields, and example payloads for the ADP Workforce Now HCM API.
</Note>

<Warning>
  Always validate your passthrough structure against the ADP API documentation. Incorrect paths or malformed request bodies will result in API errors.
</Warning>

## Best Practices

1. **Validate your payload structure** using the ADP API Explorer before implementing in production
2. **Test with a sandbox account** first to ensure your passthrough structure is correct
3. **Handle errors appropriately** - ADP may return specific validation errors for malformed requests

## Additional Resources

* [ADP API Explorer - HCM Workforce Now](https://developers.adp.com/apis/api-explorer/hcm-offrg-wfn?domain=hr)
* [StackOne Update Employee API Reference](/hris/api-reference/employees/update-employee)
* [StackOne Passthrough Query Parameters Guide](/guides/using-the-passthrough-query-parameters)


# Workday WQL
Source: https://docs.stackone.com/integration-guides/hris/workday-wql

Workday query language (WQL) usage guide for StackOne integrations

## Overview

Workday Query Language (WQL) is a powerful capability that lets users run complex queries against Workday data structures.
This guide introduces using WQL within StackOne integrations so you can retrieve and shape Workday data effectively through custom reports.

## Key Features of WQL

* **Data retrieval**: Extract specific data sources and their fields from Workday's extensive datasets.
* **Flexible querying**: Construct queries to filter, sort, and aggregate Workday data.
* **Nested data access**: Access and work with nested data structures in Workday.

### Example Query

Example WQL query to retrieve workers and selected attributes:

```sql theme={null}
SELECT workdayID as Workday_ID, employeeID as Employee_ID, legalName_Title as Title, legalFirstName as First_Name, legalLastName as Last_Name, legalNameInGeneralDisplayFormat as Display_Full_Name, email_PrimaryHome as Personal_Email, email_PrimaryWork as Work_Email, phone_PrimaryHome as Personal_Phone_Number FROM allWorkers
```

<Note>
  Creating a custom report is optional for generating WQL (Workday Query Language). However, there are several ways to obtain WQL: <br />

  * **Custom Report Feature**: By using the custom report feature, users can more accurately tailor the data they wish to extract from the data source and then convert the report to WQL.<br />
  * **Standard Reports**: You can utilize existing standard reports and convert them directly to WQL. To do this, navigate to **Convert Report to WQL** and select the `Standard Report`.<br />
  * **Data Source Navigation**: You can also navigate to the Data Source using global search and access a specific data source (e.g., All Workers) to view the available data source fields. From there, you can form a WQL query according to the WQL syntax.
</Note>

## Create and View a Custom Report

<Steps>
  <Step title="Go to Create Custom Report">
    Search and navigate to the `Create Custom Report` task

    <Frame>
      <img alt="Accessing Report Designer" />
    </Frame>
  </Step>

  <Step title="Configure custom report">
    Follow these steps to configure the custom report:

    * **Report Name**: Must be unique within the tenant
    * **Report Type**: Select **Advanced**
    * **Optimised for Performance**: Tick this box to enhance performance
    * **Data Source**: Choose the appropriate data source based on the data you need (e.g. Workers for HCM reporting).

    <Frame>
      <img alt="Create Custom Report" />
    </Frame>

    Click `OK` to continue.

    Add and configure report fields:

    * Click the `+` icon to add a field.
    * Select a Business Object (e.g. Worker) in the **Business Object** column.
    * Choose the specific field (e.g. Employee ID) in the **Field** column.
    * Set aliases in **Column Heading Override** to ensure stable field names in API responses.

    <Note>
      The **Column Heading Override XML Alias** column will appear only after you enable **Enable As Web Service** under the Advanced tab and save the report. You can view this column when you return to edit the report.
    </Note>

    <Info>
      Add the following **field aliases** in your report. The aliases serve as stable identifiers for the API responses but the underlying fields must be properly configured.

      * Workday\_ID
      * Employee\_ID
      * Title
      * First\_Name
      * Last\_Name
      * Display\_Full\_Name
      * Personal\_Email
      * Work\_Email
      * Personal\_Phone\_Number
      * Work\_Phone\_Number
      * Gender
      * Ethnicity
      * Date\_Of\_Birth
      * Marital\_Status
      * Job\_Title
      * Company
      * Hire\_Date
      * Original\_Hire\_Date
      * Employment\_Status
      * Location
      * Employment\_Type
      * Manager
      * Cost\_Centers
      * National\_Identifier\_Numbers
      * Termination\_Date
      * Home\_Address
      * Home\_Address\_Country
      * Home\_Address\_Postal\_Code
      * Home\_Address\_State
      * Home\_Address\_City
      * Work\_Address
      * Work\_Address\_Country
      * Citizenships
      * Job\_Code
      * Effective\_Date
      * Grade
      * Benefits
      * Skills
    </Info>

    <Frame>
      <img alt="Fields and Aliases Settings" />
    </Frame>
  </Step>

  <Step title="Configure report prompts">
    * Tick **Populate Undefined Prompt Defaults** to make prompt default fields visible in the report table. Once the `Prompt Defaults` grid is visible, the ticked **Populate Undefined Prompt Defaults** field will be unticked again.
    * Tick **Display Prompt Values in Subtitle** to enable prompt display.

    <Frame>
      <img alt="Prompts Settings" />
    </Frame>

    Click `OK` to save the report.
  </Step>

  <Step title="Go to View Custom Report">
    Search for `View Custom Report`.

    <Frame>
      <img alt="Search for View Custom Report" />
    </Frame>

    select the report you just created, and then click `OK` to open it.

    <Frame>
      <img alt="Select Custom report to View" />
    </Frame>
  </Step>

  <Step title="Test Custom Report">
    Navigate to `Test` under the `Custom Report` menu via the 3-dot menu.

    <Frame>
      <img alt="Navigate to Test" />
    </Frame>

    Click `OK` to test it.

    <Frame>
      <img alt="Click OK on Pop-up" />
    </Frame>

    You will get some sample data based on the fields you configured in the custom report.

    <Frame>
      <img alt="Sample Data from Custom Report" />
    </Frame>
  </Step>
</Steps>

## Convert the Report to WQL in Workday

<Steps>
  <Step title="Go to Convert Reports to WQL">
    Use the global search bar to search for "Convert Reports to WQL".

    <Frame>
      <img alt="Global search for Convert Reports to WQL" />
    </Frame>

    Select the custom report you created earlier in the [Create and View a Custom Report](#create-and-view-a-custom-report) step.

    <Frame>
      <img alt="Select created custom report" />
    </Frame>

    Click `OK`.
  </Step>

  <Step title="Click `OK` to continue">
    <Frame>
      <img alt="Click to continue without filter" />
    </Frame>
  </Step>

  <Step title="Get the generated WQL query">
    You are taken to a page showing the generated WQL query for your custom report.

    <Frame>
      <img alt="Generated WQL Query" />
    </Frame>

    Copy this WQL query and paste it into the `Employee WQL Query` field when connecting through the StackOne Connector Hub.

    <Note>
      WQL does not support calculated fields when converting custom reports to WQL.
    </Note>
  </Step>
</Steps>

## StackOne Configuration

To enable Workday WQL in StackOne, go to the HRIS category on the *Integrations* page and enable Workday WQL.

<Frame>
  <img alt="Activate Workday" />
</Frame>

Select `OAuth2` as the authentication type.

<Frame>
  <img alt="Activate Workday" />
</Frame>

Click `Confirm` or `Save Changes` to enable the Workday integration, allowing users to link their accounts via the StackOne Connector Hub.

## ATS User Enablement

Users connect their Workday accounts through the StackOne Connector Hub by providing the WQL query generated in their Workday account.

<Frame>
  <img alt="Activate Workday" />
</Frame>

<Info>
  Users will receive data based on the WQL query provided during the connection setup when they request a [list of employees](https://docs.stackone.com/hris/api-reference/employees/list-employees) using the Unified APIs.
</Info>

## Limitations of WQL

* **Calculated fields**: WQL does not support calculated fields when converting custom reports to WQL.


# GO1 Integration
Source: https://docs.stackone.com/integration-guides/lms/content-library-and-lxps/go1

LMS/LXP and Content Aggregators

## **Summary**

The GO1 integration allows you to pull curated content from your customer's GO1 platform and display it in your LMS/LXP.

It integrates content, users, user progress and pulls in extensive metadata.

Customers can curate their own content library via (GO1 Admin)\[[https://developers.go1.com/products/go1-admin/](https://developers.go1.com/products/go1-admin/)]

### **Limitations**

* **Rate Limits:** No rate limits currently.

### **Testing and Validation**

* Standard testing procedures apply.


# Xyleme Integration
Source: https://docs.stackone.com/integration-guides/lms/content-library-and-lxps/xyleme

LMS/LXP and Content Aggregators

## **Summary**

The Xyleme integration allows you to pull curated content from your customer's Xyleme platform and display it in your LMS/LXP.

It integrates content, users, user progress and pulls in extensive metadata.

To ensure the content and completions pulled in are concise and specific to the integration, you should discuss with Xyleme prior to connecting. This discussion should cover the classification tag that will be used to identify content accessible by the integration.

You should then enter this classification when enabling the integration. This tag will be the same for all customers using the integration.

### **Limitations**

* **Rate Limits:** No rate limits currently.

### **Testing and Validation**

* Standard testing procedures apply.


# Cornerstone Integration
Source: https://docs.stackone.com/integration-guides/lms/external-content-providers/cornerstone

Content & Completion Management

## **Summary**

The Cornerstone integration allows you to push content to Cornerstone and track user progress. There are 2 offerings from Cornerstone, both require partnership agreements:

Cornerstone offers a tenant-specific integration where you can push content to a specific customer's instance (**Cornerstone**). This currently only supports the creation and not the update of content.

Cornerstone also offers a distribution network where content is made available to all customers (**Cornerstone Library**). Additionally, this can be used as:

* One-to-many connector: Content is pushed to a single account, and then distribution is handled by Cornerstone.
* One-to-one connector: Content is pushed to a single account for each tenant, an agreement must be in place between the tenant and external content provider.

One-to-many connector flow:

<Frame>
  <img alt="" />
</Frame>

## **Key Details**

Cornerstone: [https://www.cornerstoneondemand.com/legal/content-providers](https://www.cornerstoneondemand.com/legal/content-providers)

Cornerstone Online Content Connector: [https://csod.dev/reference/connectors/#tag/Online-Content-Connector](https://csod.dev/reference/connectors/#tag/Online-Content-Connector)

## **Retrieving the External Trigger Token**

For the Cornerstone 1:1 connector integration, you'll need to retrieve the external trigger token (ciid) required by Cornerstone. Follow these steps:

1. Once a customer has connected their account to StackOne
2. Navigate to the accounts screen in your StackOne dashboard
3. Click "Edit Account" for the relevant Cornerstone connection
4. Copy the external trigger token from the interface

This external trigger token is essential for the proper functioning of the Cornerstone 1:1 connector and should be provided to your integration setup.

## **Known Provider Bugs**

There is currently a bug in the Cornerstone transcript endpoint (**Cornerstone** Integration) which will cause the due date to be displayed as +7 hours ahead of the expected time.


# GO1 Integration
Source: https://docs.stackone.com/integration-guides/lms/external-content-providers/go1

Content & Completion Management

## **Summary**

The GO1 integration allows you to push content to GO1 and track user progress.

GO1 offers a tenant-specific integration where you can push content to a specific customer's instance (**GO1**). This does not require a partnership agreement and will allow the specific tenant to access content without it being made available across the Go1 distribution network.

They also offer a distribution network where content is made available to all customers (**GO1 Library**). This requires a partnership agreement.

GO1 auto-completes content when a user launches it from the GO1 UI.

<Frame>
  <img alt="" />
</Frame>

## **Key Details**

### **Content Management**

* **Content Catalog:** GO1 manages the content library.

* **Publishing:** Initial content push results in an unpublished state, requiring GO1 administrator publishing.

* **Removal:** Communicate content removal to GO1; use soft delete (upsert with unpublished status) to hide content.

### **Content Upsert Behavior**

* **Deduplication:** Uses `external_reference` as the unique identifier.

  * Existing content with matching `external_reference` will be updated.

  * New content is created if no match is found.

### **Completion Push**

* Uses `content_external_reference` as the content identifier.

### **Provider-Specific Quirks**

* **Content Categorization:**

  * **Taxonomy:** GO1's category taxonomy: [https://help.go1.com/en/articles/6767512-topics-taxonomy](https://help.go1.com/en/articles/6767512-topics-taxonomy)

  * **Category Requirements:** Category and skill tagging is optional.

### **Limitations**

* **Rate Limits:** No rate limits currently.

### **Testing and Validation**

* Standard testing procedures apply.


# External Link Approach for Learning Content Providers
Source: https://docs.stackone.com/integration-guides/lms/external-content-providers/introduction

Introduction to the external link approach for content delivery and its benefits over legacy SCORM/AICC formats

## Overview

Learning content providers using StackOne's LMS integrations use an **external link approach** for content delivery. This method directs users to content hosted on third-party platforms where they can consume learning materials directly on the provider's platform.

<Note>
  The external link approach is the recommended modern standard for content delivery, offering superior flexibility and user experience compared to legacy formats.
</Note>

## How External Link Approach Works

With the external link approach:

1. **Content Discovery**: Users discover available content through your platform via StackOne's unified API
2. **External Redirection**: When users select content, they are directed to the content provider's platform
3. **Direct Consumption**: Users consume content directly on the provider's optimized platform
4. **Progress Tracking**: Learning progress and completion data flows back through StackOne's API

## Why External Links Are Preferred Over SCORM/AICC

### Widespread API Support

Modern web APIs that support external linking are universally supported across all platforms and browsers. Unlike SCORM or AICC, which require specific runtime implementations, external links work with standard web technologies that every LMS supports.

### SCORM and AICC Are Legacy Formats

SCORM (Shareable Content Object Reference Model) and AICC (Aviation Industry Computer-Based Training Committee) are outdated standards with significant limitations:

**Data Storage Restrictions**

* SCORM has a 4,096 character limit for suspend data, severely restricting the ability to save detailed progress information
* Limited data types supported for tracking learner interactions

**Outdated JavaScript APIs**

* SCORM relies on legacy JavaScript APIs that are incompatible with modern web development practices
* Requires specific browser configurations that conflict with modern security policies

**Limited Offline Capabilities**

* SCORM packages require complex workarounds for offline functionality
* Modern web standards offer better progressive web app capabilities

**Browser Compatibility Issues**

* Legacy SCORM players often fail on modern browsers due to security restrictions
* Cross-origin policy conflicts with contemporary web security standards

### Maximum Control Over Learning Journey

The external link approach gives content providers complete control over the user experience:

**User Experience Design Freedom**

* Complete control over interface design, navigation, and user interaction patterns
* Ability to implement advanced features like adaptive learning, personalization, and social learning

**Content Delivery Optimization**

* Use of modern CDNs for optimal content delivery performance
* Implementation of progressive loading and streaming technologies
* Real-time content updates without LMS dependencies

**Advanced Analytics Integration**

* Integration with sophisticated analytics platforms for detailed learner behavior tracking
* Custom reporting and business intelligence capabilities
* Cross-platform analytics aggregation

### Enhanced User Learning Tracking

External links enable superior tracking capabilities:

**Granular Progress Monitoring**

* Track detailed user interactions, time spent on specific sections, and engagement patterns
* Monitor learning path progression and decision points
* Capture rich contextual data about learning behavior

**Real-Time Performance Data**

* Instant feedback on learner performance and comprehension
* Adaptive content delivery based on real-time assessment results
* Dynamic difficulty adjustment based on learner performance

**Cross-Platform Analytics**

* Unified tracking across multiple devices and platforms
* Comprehensive learning journey mapping across different touchpoints
* Integration with enterprise learning analytics systems

**Custom Reporting and Insights**

* Tailored reporting that matches specific business or educational requirements
* Advanced data visualization and learning analytics dashboards
* Predictive analytics for learning outcomes and intervention recommendations

## Modern Technical Advantages

### Scalability and Performance

* **Global Content Delivery**: Leverage modern CDN technologies for optimal global content delivery
* **Elastic Scaling**: Handle varying loads without LMS infrastructure constraints
* **Performance Optimization**: Use modern web technologies like service workers and progressive web apps

### Security and Compliance

* **Modern Security Protocols**: Implement contemporary authentication and authorization standards
* **Data Privacy Controls**: Fine-grained control over data collection and privacy compliance
* **Secure Content Delivery**: Use HTTPS and modern encryption standards for all content delivery

### Integration Flexibility

* **API-First Architecture**: Modern RESTful APIs that integrate with any technology stack
* **Webhook Support**: Real-time notifications for learning events and progress updates
* **Standards Compliance**: Support for modern e-learning standards like xAPI and cmi5

## Getting Started

To implement the external link approach with StackOne:

1. **Content Hosting**: Ensure your content is hosted on a platform accessible via web links
2. **Progress Tracking**: Implement progress tracking that can send data back via StackOne's API
3. **User Authentication**: Set up secure user authentication and session management
4. **Analytics Integration**: Configure tracking and analytics for comprehensive learner insights

<Note>
  StackOne's unified API abstracts the complexity of different LMS providers while maintaining the benefits of the external link approach across all integrated platforms.
</Note>

## Next Steps

* Review the specific [partnership integration requirements](./partnership-integrations) for platforms that require formal partnerships
* Explore platform-specific guides for [Cornerstone](./cornerstone), [Oracle](./oracle), [Workday](./workday), and [Go1](./go1)
* Learn about [other integration options](./other-integrations) available through StackOne

For technical implementation guidance and best practices, contact the StackOne team to discuss your specific content delivery requirements.


# Oracle Fusion Learning Integration
Source: https://docs.stackone.com/integration-guides/lms/external-content-providers/oracle

Content & Completion Management for Oracle Cloud Learning

## **Key Details**

### **Oracle Platform Prerequisite**

Oracle requires a partnership for external content providers. Once the integration is enabled there is a step for the tenant admin to enable the external content provider in the Oracle platform. [Example Configuration](https://docs.oracle.com/en/cloud/saas/talent-management/24d/faiml/configure-external-content-providers-for-oracle-learning.html)

Once an external content provider is added to the Oracle partnership, Oracle will advertise the content provider in the Oracle Learning Catalog. They will also create specific documentation for the integration.

Oracle have a release cadence of 3-6 months, so the integration will take time to be available in the Oracle Learning Catalog.

* See [Oracle Data Exchange Reference](https://docs.oracle.com/en/cloud/saas/talent-management/24d/faiml/external-content-provider-and-oracle-learning-data-exchange-reference.html) for details on the underlying Learning Connect API.

## **Integration Overview**

<Frame>
  <img alt="" />
</Frame>

### **Content Upsert**

* **Deduplication:** Oracle uses unique identifiers for content. Ensure the `external_reference` is unique during content creation.
* **Implementation Notes:**
  * **Course Context:** All content is within a course structure. Default course settings and enrollment requirements may apply.

### **Completion Push**

* Uses `learning_object_external_reference` for content identification via xAPI.

## Integration Configurations

### External Content Provider Enablement

Oracle requires the external content provider to be enabled at the tenant level. This is a one-time setup step and must be completed before any API-based integration can function.

* See [Configure Skillsoft](https://docs.oracle.com/en/cloud/saas/talent-management/24d/faiml/set-up-skillsoft-percipio-integration-with-oracle-learning.html) for an example of this setup step.

### **Limitations**

* **Rate Limits:** Oracle may enforce API rate limits. Consult Oracle documentation for current limits.

### **Testing and Validation**

* Standard testing procedures apply. Validate content upsert and completion flows end-to-end in a sandbox environment before production rollout.

***

> [Official Oracle documentation](https://docs.oracle.com/en/cloud/saas/talent-management/24d/faiml/external-content-provider-and-oracle-learning-data-exchange-reference.html).


# Other Integrations
Source: https://docs.stackone.com/integration-guides/lms/external-content-providers/other-integrations



## **Docebo**

Content in Docebo shows as type tincan - [Docebo Tin Can](https://www.docebo.com/learning-network/blog/tin-can-elearning/) in this case, the content flow will work in exactly the same way as other integrations.

The user will be redirected to the external content provider platform and the progress will be tracked via the User Completions endpoint.

<Warning>
  Docebo does not allow updating content URLs or image URLs via the upsert content endpoint.
</Warning>

## **360 Learning**

**Summary**

360 Learning will automatically create a completion on content launch. This isn't configurable.

The completion is initially created with 1% completion. When you create a completion via StackOne we will update this progress to 100%.

**Top Level Flow**

<video />

**Known Provider Bugs**

Completions `Result` is shown in the model and are accepted by the API but isn't shown in the UI.


# Partnership Integrations
Source: https://docs.stackone.com/integration-guides/lms/external-content-providers/partnership-integrations

LMS integrations that require platform partnerships for external content providers

## Overview

Some LMS integrations require you to establish a partnership with the platform before you can push content to their systems. These partnerships typically involve becoming an approved content provider or technology partner.

<Note>
  StackOne can help guide you through the partnership process for these integrations. Contact our support team for assistance.
</Note>

## Required Partnership Integrations

The following LMS providers require a partnership agreement before integration:

### Cornerstone OnDemand

Cornerstone requires content providers to become approved partners before accessing their integration capabilities.

**Partnership Information:**

* [Cornerstone Content Provider Terms](https://www.cornerstoneondemand.com/legal/content-providers/)

**Partnership Application:**

* [Content Provider Partnership Form](https://forms.monday.com/forms/aed838db5f3a637bf31838bff15f8bb8?r=use1)

**Requirements:**

* Approval as a content provider
* Agreement to content provider terms

**Authentication:**
For Cornerstone Library integrations, speak to Cornerstone to get the username and password to enter in the integration configuration screen.

### Oracle

Oracle requires partners to join their Partner Network program to access LMS integration capabilities.

**Partnership Information:**

* [Oracle PartnerNetwork Program](https://www.oracle.com/partnernetwork/program/build/)

**Partnership Application:**

* [Oracle Partner Application](https://go.oracle.com/LP=126909)

**Requirements:**

* Oracle PartnerNetwork membership
* Business partnership agreement

### Go1

Go1 requires content providers to establish a partnership agreement before integrating with their platform.

<Note>Go1 supports tenant-specific integrations where you can push content to a specific customer's instance. This does not require a partnership agreement and will allow the specific tenant to access content without it being made available across the Go1 distribution network.</Note>

**Partnership Information:**

* [Go1 Content Provider Terms](https://www.go1.com/terms/content-providers-entity)

**Partnership Application:**

* [Go1 Content Provider Application](https://airtable.com/appwZMCkiLE7lZiUz/pag7S9hCWRZHLS8RS/form)

**Requirements:**

* Content provider agreement
* Quality and compliance standards

**Authentication:**
For Go1 Library integrations, speak to Go1 to get the clientId and clientSecret to enter in the integration configuration screen.

## Partnership Process

### General Steps

1. **Review Requirements**: Each platform has specific requirements for content providers and technology partners
2. **Submit Application**: Complete the partnership application form for your chosen platform
3. **Technical Review**: Since StackOne has already built integrations with these platforms there is no need for any integration build time or technical review
4. **Agreement Execution**: Sign the partnership agreement and any required legal documents
5. **Integration Setup**: Begin the technical integration process with StackOne

### Timeline Considerations

* Partnership approvals can take **2-8 weeks** depending on the platform
* Some platforms may require additional documentation or demos

## How StackOne Can Help

StackOne has experience working with these partnership programs and can:

* **Guidance**: Provide advice on application requirements and best practices
* **Documentation**: Help prepare technical documentation required for applications
* **Partnership Introduction**: Introduce you to the correct people to help with your application
* **Support**: Ongoing support throughout the partnership and integration process

<Note>
  Contact StackOne support early in your planning process to ensure smooth partnership applications and integrations.
</Note>

## Next Steps

1. Choose which LMS platform(s) you need to integrate with
2. Review the partnership requirements for each platform
3. Contact StackOne to discuss your integration plans
4. Submit partnership applications
5. Begin technical integration setup with StackOne once partnerships are approved

For additional help with partnership applications or technical integration questions, reach out to the StackOne team.


# SAP SuccessFactors Integration
Source: https://docs.stackone.com/integration-guides/lms/external-content-providers/sap

Content & Completion Management

## **Summary**

The SAP SuccessFactors integration allows you to push content to SAP SuccessFactors and track user progress.

Content pushed to SAP SuccessFactors is fully integrated with other content available to the SAP SuccessFactors tenant and discoverable by multiple filtering options.

In order to integrate content via the OCN (Open Content Network) flow, an user admin must periodically import content from the Open Content Network.

**Content and Completions within SAP SuccessFactors**

<video />

## **Key Details**

### **Content Upsert Behavior (Open Content Network - OCN Flow)**

* **OCN Approach:** Mimics external content provider flow, allowing customer-controlled import. Content updates and deactivation are possible.

<Frame>
  <img alt="" />
</Frame>

* **Deduplication:** Uses `external_reference` as the unique identifier.

  * Existing content with matching `external_reference` will be overwritten.

<Frame>
  <img alt="" />
</Frame>

* **Implementation Notes:**

  * **Launch Method:** Automatically set to "browser."

  * **Languages:** Ensure content titles and descriptions are provided for all relevant locales.

    * Accepted Enum Values:

      * Languages: Locale names (e.g., "English," "Spanish").

      * Result: "pass" or "fail."

  * **Course Wrapper:** A course wrapper with matching title, description, and ID is automatically created.

  * **Inactive Status:** Content initially created as inactive will not appear in the import menu. If set to inactive after import, it will appear under the "not active" filter.

### **Completion Push**

* Uses `content_external_reference` as the content identifier.

* **Unique Constraints:** Assignments are not supported for OCN content via API.

### **Provider-Specific Quirks**

* **Content Categorization:** OCN content is automatically categorized as MOOC.

### **Limitations**

* **Rate Limits:**

  * OCN: 1 request per 5 minutes, 1000 content items per request.

  * Use `/batch` operation for large catalogs.

  * Read operations: 1 request per 0.5 seconds.

## **SSO Configuration for Completion Creation**

When integrating with SAP SuccessFactors for completion tracking, proper SSO configuration is essential to ensure the integration works as expected. This section outlines the required user identification setup for creating completions.

### **User Identification Configuration**

To properly identify users and create completions, you have three configuration options in order of preference:

##### **1. NameID Configuration (Recommended)**

The customer should ensure that the **NameID** is set to the **UserID/StudentID** field in their SAP SuccessFactors SSO configuration. This is the most straightforward approach and provides direct user mapping.

##### **2. Custom Field Configuration (Alternative)**

If option 1 is not possible, the customer should set a custom field `lms_user_id` to the **UserID/StudentID** field in their SSO configuration. This provides an alternative mapping mechanism while maintaining clear user identification.

##### **3. External Reference Configuration (Fallback)**

If the above configurations are not allowed for any reason, the customer must set an `lms_external_reference_field` to the **personExternalID** field.

When using this approach, you will need to:

1. Fetch the StackOne user ID via the `/users?filter[external_reference]=<lms_external_reference_field>` filter, replacing `<lms_external_reference_field>` with the actual value configured for your integration.
2. Use the StackOne ID returned from this request in the user completions request

### **Connector Meta Information**

The `/meta/connectors/sapsuccessfactors_learning?include=connector_meta_field` endpoint provides the `connector_meta_field` information for all the above configuration options. This endpoint contains the metadata needed to understand the available fields and their mapping requirements.

### **Testing and Validation**

* Standard testing procedures apply.
* Verify that the chosen user identification method correctly maps users between systems.
* Test completion creation with the configured SSO setup to ensure proper user attribution.


# Workday Integration
Source: https://docs.stackone.com/integration-guides/lms/external-content-providers/workday

Content & Completion Management

## **0. At a Glance**

* **Connector:** Workday LMS External Content Provider
* **Supported Write Resources:** Content (upsert), Completions (push), Categories (list/get)
* **Integration Direction:** Bidirectional (content push, completion tracking)
* **Partnership Requirements:** Standard Workday tenant access required
* **Key Behaviours:**
  * Auto-completes content when users launch from Workday UI
  * Uses both `external_reference` and `title` for content deduplication
  * Requires base64 encoded cover images
* **Key Quirks:**
  * Auto-creates enrollments and completions, causing potential discrepancies
  * Content categorization may show as internal even for external providers
  * Rate limited to 5-10 requests per second

***

## **1. Integration Overview**

### **1.1 What This Connector Does**

This connector pushes learning content and completion data from your platform into Workday's learning management system.

**What users see:**

* Content appears in Workday's **Learning → Discover** section
* Users can filter content by topics, languages, and content providers
* When users launch content, they're directed to your platform while Workday tracks their progress

**How it works:**

* Workday automatically creates course wrappers around individual content items
* Content integrates seamlessly with Workday's existing catalog
* Workday manages the enrollment and completion lifecycle

### **1.2 System UI Overview (Video)**

**Content and Completions within Workday**

<video />

### **1.3 High-Level Data Flow**

For a comprehensive overview of the data flow and integration architecture, see the [Learning Content Provider LMS Use Case](https://docs.stackone.com/lms/use-cases/learning-content-provider-lms-use-case).

***

## **2. Requirements & Prerequisites**

### **2.1 Partnership / Commercial Requirements**

* **Vendor partnership:** Not required - standard integration
* **Customer-specific setup:** Yes - Workday tenant configuration required
* **Marketplace approval:** Not required
* **Any mandatory agreements or feature enablement:** Standard Workday LMS module access

### **2.2 System-Side Prerequisites**

* **Required modules:** Workday Learning Management System
* **Required admin permissions:** Learning Administrator role for content management
* **Required system features:** External content feature enabled in Workday tenant

### **2.3 StackOne-Side Prerequisites**

* **Required connector meta fields:** Content categories configuration
* **Required configuration flags:** Enrollment requirements, mobile content duplication
* **Sandbox/test requirements:** Workday sandbox tenant for testing

***

## **3. Behaviour of Write Operations**

### **3.1 Content / Object Upsert**

**Supported operations:** Create and update content items

**How Workday identifies content:**

Workday uses both `external_reference` and `title` to identify content:

* If a `title` matches existing content, Workday updates the `external_reference`
* This ensures content remains unique even if references change

**Content lifecycle:**

* **Creation:** Workday automatically creates a course wrapper with these defaults:
  * Lesson Order: 1
  * Lesson Mandatory: True
  * Registrable Status: Open
  * Requires Enrollment: True (configurable)

* **Updates:** Workday updates existing content based on the matching rules above

* **Disabling content:** Set the `active` field to `false` to hide courses from learners

**Requirements and limitations:**

* Cover images must be base64 encoded (StackOne handles this automatically)
* Content must include a valid Workday category
* Categories must be customer-specific or retrieved from the unified categories endpoint

<Frame>
  <img alt="" />
</Frame>

### **3.2 Completion / Status Push**

**How completions work:**

StackOne uses the `learning_object_external_reference` to identify which content the completion relates to.

**Update behavior:**

* StackOne updates existing completion records instead of creating duplicates
* This prevents discrepancies between your platform and Workday

**Important timing considerations:**

<Warning>
  Workday automatically creates completion records when users launch content. StackOne's completion push updates these existing records to reflect the actual completion status from your platform.
</Warning>

**Cleanup options:**

If you need to remove incorrect completions, use the DELETE user completion endpoint.

<Frame>
  <img alt="" />
</Frame>

### **3.3 Additional Writeable Resources**

**Categories:**

* List/get categories from Workday tenant
* Required for content categorization during upsert

***

## **4. Field-to-UI Mapping**

### **4.1 Overview**

This section shows how each unified API field maps into the Workday learner and admin UI. This is essential for previewing how course metadata appears inside **Learning → Discover**, **Course Details**, and **Admin View**.

### **4.2 Mapping Table**

| Unified API Field    | Workday Field / Behaviour                    | UI Location                   | Screenshot Placeholder                         | Notes                                           |
| -------------------- | -------------------------------------------- | ----------------------------- | ---------------------------------------------- | ----------------------------------------------- |
| title                | Course & Lesson Title                        | Discover card + Course header | <img alt="Title and description in Workday" /> | Updates everywhere when changed                 |
| external\_reference  | Learning Course ID                           | Admin View                    |                                                | Must be unique; changing creates new course     |
| description          | Description                                  | Course page                   | <img alt="Course description in Workday" />    | HTML stripped; truncated on tiles               |
| duration             | Time Value Reference + Total Course Duration | Course page + Admin           | <img alt="Duration configuration" />           | ISO-8601 converted to minutes                   |
| categories           | Topics Reference                             | Additional Course Details     | <img alt="Categories and topics" />            | Must match existing topics                      |
| skills               | Skill Reference                              | Course page                   | <img alt="Skills configuration" />             | Unknown skills cause failure                    |
| languages            | Language Reference                           | Additional Details            | <img alt="Language settings" />                | Only first language displayed                   |
| content\_url         | External Content URL                         | Admin → Lessons               | <img alt="Content URL configuration" />        | Hidden from learners; launched via Start/Enroll |
| cover\_url           | Course Image Data                            | Discover tile + Course page   | <img alt="Cover image upload" />               | Must be publicly accessible                     |
| active               | Inactive                                     | Admin                         |                                                | false → hides course                            |
| requires\_enrollment | Requires Enrollment                          | Admin                         | <img alt="Access type configuration" />        | false → self-directed                           |
| mobile\_url          | Mobile Lesson                                | Lessons tab                   |                                                | Creates additional mobile lesson                |

### **4.3 UI Walkthrough**

#### **4.3.1 Discover Catalogue**

* Course appears with:
  * Cover image
  * Title
  * Duration
  * Short description excerpt
* Users can filter by Topic, Language, Content Provider

> **Screenshot:** <img alt="Content discovery page" />
> **Screenshot:** <img alt="Content discovery page" />
> **Screenshot:** <img alt="Content discovery page" />

#### **4.3.2 Course Page (Learner View)**

* Full description
* Skills
* Cover image
* Start/Enroll button
* Completion badge if completed

> **Screenshot:** <img alt="Course details page" />

#### **4.3.3 Lessons in This Course**

* Lesson 1 auto-generated
* Type: External Lesson
* Required flag visible

> **Screenshot:** <img alt="Lessons configuration" />

#### **4.3.4 Admin View**

* External Reference
* Requires Enrollment
* Enforce Lesson Order
* Topics, Skills, Languages

***

## **5. Derived Values & Defaults**

### **5.1 Derived / Computed Values**

* Cover images: URLs converted to base64 encoding automatically
* Duration: ISO-8601 format converted to minutes for Workday display
* Course wrapper: Auto-generated around individual content items

### **5.2 System Defaults Applied by StackOne**

* Content requires enrollment: True (configurable at account level)
* Lesson Mandatory: True
* Lesson Order: 1
* Registrable Status: Open
* Course creation: Auto-wraps individual content in course structure

### **5.3 Hardcoded / Strict Enums**

* **Languages:** Locale codes (e.g., `en_gb`)
* **Result:** `pass` or `fail`
* **Categories:** Must match existing Workday categories or use unified categories endpoint

***

## **6. Configuration**

### **6.1 StackOne Config Options**

* **Enrollment Required (Content):** Yes/No - Controls whether content requires enrollment
* **Create Duplicate Content for Mobile:** Yes/No - Creates additional mobile lesson when mobile\_url provided
* **Content Categories:** Customer-specific category mapping

### **6.2 System-Level Configuration**

* External content feature must be enabled in Workday tenant
* Learning Administrator role assigned to managing users
* Category structure configured for content organization

### **6.3 Identity / SSO Mapping**

* Users identified through Workday's internal user management
* Completions linked via `learning_object_external_reference`
* Auto-enrollment creates user-content relationships

### **6.4 Account Configuration**

* **Requires Enrollment (Account):** Yes/No - Toggle whether a user needs approval to launch a course.
* **Media File ID (WID):** If using the Media File CompletionBlocker approach, enter the Workday WID of the file used for the blocker.

***

## **7. Quirks & Limitations**

### **Known Limitations**

**Rate limits:**

* 5-10 requests per second maximum

**Cover images:**

* Must be base64 encoded (StackOne handles this automatically)
* If URL conversion fails, the content upsert will fail

**Mobile content:**

* Workday doesn't natively support mobile-specific URLs
* Requires creating a duplicate lesson (see Section 6.1 for configuration)

### **System-Specific Behaviors**

**Content categorization:**

* Content may appear categorized as "internal" even when it links to an external provider
* This is a Workday UI behavior and doesn't affect functionality

**Automatic completions:**

* Workday automatically marks content as complete when users launch it from the UI
* For single-lesson courses, Workday completes the entire course immediately on launch

**Content identification:**

* Workday uses both `external_reference` AND `title` for deduplication
* This differs from other LMS systems that typically use only the external reference

### **Potential Issues and Solutions**

<Warning>
  **Completion discrepancies:** Workday auto-creates enrollments and completions, which can cause differences between your platform's progress data and Workday's status.
</Warning>

**How to handle this:**

* StackOne updates existing completion records instead of creating new ones
* Use the DELETE user completion endpoint to clean up incorrect records
* Consider the SCORM course blocker workaround for auto-completion issues (see Section 8 → Integration Configurations)

***

## **8. Testing & Validation**

### **8.1 Recommended Test Cases**

1. **Content Creation:** Push new content with all fields → Verify appears in Discover with correct metadata
2. **Content Update:** Update existing content title → Verify deduplication works correctly
3. **Completion Push:** Send completion for enrolled user → Verify updates existing record without duplicate
4. **Mobile Content:** Push content with mobile\_url and mobile duplication enabled → Verify two lessons created
5. **Category Validation:** Push content with invalid category → Verify appropriate error handling
6. **Cover Image Handling:** Push content with URL-based cover image → Verify base64 conversion success

### **8.2 Sample Payloads**

```json theme={null}
// Content Upsert (PUT /unified/lms/content)
{
  "title": "Advanced Sales Techniques",
  "external_reference": "ADV-SALES-001",
  "description": "A comprehensive course covering modern B2B sales strategies.",
  "languages": [
    { "value": "en_GB" },
    { "value": "fr_FR" }
  ],
  "content_url": "https://provider.example.com/courses/adv-sales-001",
  "cover_url": "https://cdn.example.com/images/adv-sales-001.jpg",
  "active": true,
  "duration": "PT1H30M45S",
  "skills": [
    { "id": "skill-001", "name": "Sales Techniques", "hierarchy": { "value": "primary" }, "language": { "value": "en_GB" } },
    { "name": "Customer Engagement", "hierarchy": { "value": "secondary" } }
  ],
  "order": 1,
  "categories": [
    { "name": "Sales" },
    { "id": "cat-technology", "name": "Technology" }
  ],
}

// Completion Push (POST /unified/lms/users/{id}/completions)
{
  "learning_object_external_reference": "ADV-SALES-001",
  "result": { "value": "Pass" },
  "completed_at": "2025-01-15T14:45:30.000Z",
  "time_spent": "PT45M",
  "score": {
    "value": 100,
    "raw_value": "A+"
  }
}
```

### **8.3 Troubleshooting Checklist**

| **Issue**                         | **Root Cause**                                     | **Verification Steps**                                              |
| --------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------- |
| Content not appearing in Discover | Invalid category or inactive status                | Check categories endpoint, verify active=true                       |
| Cover image not displaying        | URL conversion to base64 failed                    | Verify image URL is public and accessible                           |
| Duplicate completions             | Auto-completion + manual completion                | Check completion records, use DELETE endpoint if needed             |
| Content update creates new course | Title changed without matching external\_reference | Verify deduplication logic using both title and external\_reference |
| Mobile lesson not created         | Mobile duplication disabled or mobile\_url missing | Check connector configuration and mobile\_url field                 |

### **8.4 Troubleshooting Unified Logs**

When creating content in Workday, StackOne makes several API requests. Some of these requests are expected to fail during normal operation—this is not an indication of a problem.

#### **Expected Request Patterns for Each Content Item**

For each content item, StackOne makes the following requests:

**1. Two GET requests to check if content exists**

These requests search by `title` and `external_reference` to determine if content already exists in Workday.

<Note>
  **Expected 500 errors:** If the content doesn't exist, these requests return a 500 status code with the error message:

  `Validation error occurred. Invalid ID value. 'XYZ' is not a valid ID value for type = 'Learning_Course_ID'` or `type = 'Learning_Course'`

  This is normal behavior and does not indicate an underlying issue.
</Note>

<Warning>
  **Different error messages may indicate real issues:**

  If you see a different `faultString`, investigate further. For example:

  * `invalid username or password` indicates credential issues—contact the customer to verify their Workday credentials
</Warning>

**2. Cover image download**

StackOne downloads the cover image from the provided URL to convert it to a base64 string, which Workday requires.

<Note>
  You can identify this request by the URL, which will point to your image hosting service.
</Note>

<Warning>
  If this request fails, it indicates:

  * An issue with your image hosting service
  * The image URL is not publicly accessible
  * Network connectivity problems
</Warning>

**3. Content push operation**

Finally, StackOne pushes the content to Workday using one of two methods:

* **Update:** If content already exists (based on the earlier GET requests)
* **Create:** If the content is new

### **Integration Configurations**

#### **Media File Completion Blocker**

Workday fires automatic completions when a user launches a course from the UI. If the Workday course is a single content item (i.e. one lesson within the course) Workday will also complete the course at this point.

This means that there will often be a discrepancy between the real user progress on the course in the external content provider and the completion status in Workday.

Workday doesn't allow configuration on this but we can provide a Workday approved workaround.

This will require your customer to upload a media file to the Workday system which will contain a PDF instructing the user to return to and complete any previous lessons on the external content provider page before completing the media lesson. As a result it blocks the completion of the course where it would normally auto-complete.

<Frame>
  <img alt="SCORM course blocker flow diagram" />
</Frame>

#### **Mobile Content Lesson**

Workday doesn't support the use of additional mobile friendly content urls with a lesson. In order to help support this we can create an additional duplicate lesson in the content with a mobile specific url.

There are 2 steps to enabling this:

1. Configure the **Create Duplicate Content for Mobile** to Yes in the Integration Configuration
2. Include a value in the [Mobile Launch Content URL](https://docs.stackone.com/lms/api-reference/content/upsert-content#body-mobile-launch-content-url) field.

<Frame>
  <img alt="images/Screenshot2025-03-20at10.57.44.png" />
</Frame>

***


# OAuth Proxy Redirect
Source: https://docs.stackone.com/integration-guides/oauth-proxy-redirect



If you are embedding StackOne components such as the File Picker in your application, you will need to host a redirect page within your application to support verification by Google. Google mandates that this redirect page be hosted within the same domain as your application. This is a requirement of the OAuth2 protocol.

However, to properly authenticate the File Picker component, the returned token must also be sent back to StackOne.

To support this, StackOne provides a custom `redirectUri` parameter in the OAuth2 flow. This allows you to specify a redirect page hosted on your domain, which will then redirect the user back to the StackOne OAuth2 authorization endpoint. This satisfies Google's requirement for a redirect page hosted on your domain while also allowing you to send the token back to StackOne.

The flow can be summarized as follows:

<Frame>
  <img alt="Overall oauth proxy redirect flow" />
</Frame>

## Implementing the Redirect Page

The redirect page should be implemented as a simple endpoint that receives a `GET` request from Google with query parameters and redirects the user back to the StackOne OAuth2 authorization endpoint with the same query parameters.

The StackOne OAuth2 authorization endpoint is: `https://api.stackone.com/connect/oauth2/{connector}/callback` (replace `{connector}` with the connector key, e.g., `googledrive`, `sharepoint`, `onedrive`)

If you were previously testing with the StackOne authorization as your redirect URL, you will need to update your application to use your new redirect page before submitting your application for verification.

## StackOne Redirect URL

To configure the StackOne custom redirect URL, you will need to set the `redirectUri` parameter in the OAuth2 flow to your custom URL:

<Frame>
  <img alt="Entering the redirectUri" />
</Frame>

In this case, when Google authenticates the user, it will redirect to `https://mydomain.com/oauth2/callback` with the following query, and then this endpoint will redirect the user back to the StackOne OAuth2 authorization endpoint with the same query parameters.


# Claude Code
Source: https://docs.stackone.com/mcp/app-guides/claude-code

Connect StackOne MCP to Claude Code using built-in MCP commands.

## Overview

[Claude Code](https://code.claude.com/) is Anthropic's CLI for developers. It provides built-in commands for managing MCP servers.

<Info>
  For complete Claude Code MCP documentation, see the [official MCP guide](https://code.claude.com/docs/en/mcp).
</Info>

## Setup

<Tip>
  The fastest way to get your configuration is directly from the StackOne dashboard — it generates a ready-to-paste `claude mcp add` command. See [Connect from Dashboard](/mcp/connect-from-dashboard).
</Tip>

<Steps>
  <Step title="Get your MCP URL from the dashboard">
    1. Go to **Connectors** in the left nav and open the connector you want to use
    2. Click **Use Connector** in the top right
    3. On the **Use** tab, click **MCP Server** under "Use with Agent Client"
    4. Select a linked account from the dropdown
    5. Choose **Claude Code** as the client
    6. Copy the generated command

    The command uses a single token URL — no API key encoding required.

    <Tip>
      The token expires after one year. Regenerate it at any time using the refresh button in the MCP tile.
    </Tip>
  </Step>

  <Step title="Add StackOne MCP Server">
    Run the command from the dashboard in your terminal. It looks like this:

    ```bash theme={null}
    claude mcp add \
      --transport http \
      gsheets \
      "https://api.stackone.com/mcp?token={session_token}"
    ```

    <Tip>
      Use short names for easier CLI usage: `gsheets`, `slack`, `hubspot-sales`. You can prefix with `stackone-` or `s1-` if you have other MCP servers, but it's not required.
    </Tip>

    <Accordion title="Alternative: Manual API key setup">
      If you prefer to use your API key and account ID directly, set your encoded API key as an environment variable first:

      <Tabs>
        <Tab title="macOS / Linux">
          ```bash theme={null}
          export STACKONE_AUTH_TOKEN=$(echo -n "{stackone_api_key}:" | base64)
          ```
        </Tab>

        <Tab title="Windows (PowerShell)">
          ```powershell theme={null}
          $env:STACKONE_AUTH_TOKEN = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("{stackone_api_key}:"))
          ```
        </Tab>
      </Tabs>

      Then add the server:

      ```bash theme={null}
      claude mcp add \
        --transport http \
        --header "Authorization: Basic $STACKONE_AUTH_TOKEN" \
        gsheets \
        "https://api.stackone.com/mcp?x-account-id={account_id}"
      ```
    </Accordion>
  </Step>

  <Step title="Verify Connection">
    Check the server status:

    ```bash theme={null}
    claude mcp list
    ```

    <Frame>
      <img alt="claude mcp list output showing multiple connected MCP servers" />
    </Frame>

    Within a Claude Code session, use the `/mcp` command to view server details and available tools:

    <Frame>
      <img alt="Claude Code /mcp command showing server details including status, URL, capabilities and tool count" />
    </Frame>

    Select "View tools" to browse available operations:

    <Frame>
      <img alt="Claude Code /mcp command showing list of available tools for googlesheets server" />
    </Frame>
  </Step>
</Steps>

## Adding Multiple Accounts

Get a separate token for each account from the dashboard, then add them as distinct servers:

```bash theme={null}
# Google Sheets account
claude mcp add \
  --transport http \
  gsheets \
  "https://api.stackone.com/mcp?token={google_sheets_session_token}"

# Slack account
claude mcp add \
  --transport http \
  slack \
  "https://api.stackone.com/mcp?token={slack_session_token}"
```

## Scope Options

Control where the configuration is stored:

| Scope   | Flag              | Storage Location                    | Use Case                                |
| ------- | ----------------- | ----------------------------------- | --------------------------------------- |
| Local   | (default)         | `.claude.json` in current directory | Project-specific                        |
| Project | `--scope project` | `.mcp.json` at project root         | Team collaboration (version controlled) |
| User    | `--scope user`    | `~/.claude.json`                    | Personal tools across all projects      |

**Example with user scope** (available across all projects):

```bash theme={null}
claude mcp add \
  --transport http \
  --scope user \
  gsheets \
  "https://api.stackone.com/mcp?token={session_token}"
```

## Management Commands

```bash theme={null}
claude mcp list                           # View all configured servers
claude mcp get gsheets     # Show details for specific server
claude mcp remove gsheets  # Remove a server
```

## Programmatic Integration

For programmatic integration with Anthropic's Claude API, see the [Anthropic SDK Framework Guide](/mcp/framework-guides/anthropic-sdk).

## Next Steps

<CardGroup>
  <Card title="Claude Desktop" icon="desktop" href="/mcp/app-guides/claude-desktop">
    Set up MCP in the Claude Desktop app
  </Card>

  <Card title="Authentication Guide" icon="lock" href="/mcp/auth-security">
    Configure authentication and security
  </Card>
</CardGroup>


# Claude Desktop
Source: https://docs.stackone.com/mcp/app-guides/claude-desktop

Connect StackOne MCP to Claude Desktop using the mcp-remote package.

## Overview

[Claude Desktop](https://claude.ai/download) is Anthropic's GUI application for macOS and Windows with full MCP support for tools, resources, and prompts.

<Info>
  For complete Claude Desktop MCP documentation, see the [official MCP quickstart](https://modelcontextprotocol.io/quickstart/user).
</Info>

## Setup

Claude Desktop requires the [`mcp-remote`](https://github.com/geelen/mcp-remote) package to connect to remote HTTP servers.

<Tip>
  The fastest way to get your configuration is directly from the StackOne dashboard — it generates a ready-to-paste JSON block for Claude Desktop. See [Connect from Dashboard](/mcp/connect-from-dashboard).
</Tip>

<Steps>
  <Step title="Get your MCP URL from the dashboard">
    1. Go to **Connectors** in the left nav and open the connector you want to use
    2. Click **Use Connector** in the top right
    3. On the **Use** tab, click **MCP Server** under "Use with Agent Client"
    4. Select a linked account from the dropdown
    5. Choose **Claude Desktop** as the client
    6. Copy the generated JSON block

    The config uses a single token URL — no separate API key encoding required.

    <Tip>
      The token expires after one year. Regenerate it at any time using the refresh button in the MCP tile.
    </Tip>
  </Step>

  <Step title="Locate Configuration File">
    1. Open Claude Desktop
    2. Navigate to **Settings** → **Developer**
    3. Click **"Edit Config"** to open the configuration file in your default editor

    <Tip>
      The config file is located at:

      * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
      * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
    </Tip>

    <Frame>
      <img alt="Claude Desktop Settings page showing Developer tab with Edit Config button highlighted" />
    </Frame>
  </Step>

  <Step title="Add StackOne MCP Configuration">
    Paste the config from the dashboard into your `claude_desktop_config.json`. It looks like this:

    ```json theme={null}
    {
      "mcpServers": {
        "gsheets": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote@latest",
            "https://api.stackone.com/mcp?token={session_token}"
          ]
        }
      }
    }
    ```

    <Tip>
      Use short names for easier identification: `gsheets`, `slack`, `hubspot-sales`. You can prefix with `stackone-` or `s1-` if you have other MCP servers, but it's not required.
    </Tip>

    <Accordion title="Multiple accounts example">
      For multiple linked accounts, add an entry for each. Get each token from the dashboard by selecting the relevant account.

      <Frame>
        <img alt="Claude Desktop Connectors page showing multiple MCP servers configured for different integrations" />
      </Frame>

      ```json theme={null}
      {
        "mcpServers": {
          "gsheets": {
            "command": "npx",
            "args": [
              "-y",
              "mcp-remote@latest",
              "https://api.stackone.com/mcp?token={google_sheets_session_token}"
            ]
          },
          "slack": {
            "command": "npx",
            "args": [
              "-y",
              "mcp-remote@latest",
              "https://api.stackone.com/mcp?token={slack_session_token}"
            ]
          }
        }
      }
      ```
    </Accordion>

    <Accordion title="Alternative: Manual API key setup">
      If you prefer to use your API key and account ID directly, encode your API key first:

      <Snippet />

      <Frame>
        <img alt="Terminal showing base64 encoding command and output" />
      </Frame>

      Then add to your config:

      ```json theme={null}
      {
        "mcpServers": {
          "gsheets": {
            "command": "npx",
            "args": [
              "-y",
              "mcp-remote@latest",
              "https://api.stackone.com/mcp?x-account-id={account_id}",
              "--header",
              "Authorization: Basic {base64_encoded_api_key}"
            ]
          }
        }
      }
      ```
    </Accordion>
  </Step>

  <Step title="Restart Claude Desktop">
    Close and reopen Claude Desktop to load the new configuration.
  </Step>
</Steps>

## Verify Connection

After restarting, navigate to **Settings** → **Developer** to verify your servers are configured:

<Frame>
  <img alt="Claude Desktop Settings showing configured Local MCP servers" />
</Frame>

A green "running" badge indicates the server is connected. If you see "failed", click **Open Logs Folder** to troubleshoot.

Your servers will also appear in **Settings** → **Connectors** with a "Local Dev" tag, where you can configure tool permissions:

<Frame>
  <img alt="Claude Desktop Connectors page showing tool permissions with options to enable or require approval for each tool" />
</Frame>

Once connected, you can:

1. **List Tools**: Ask "What StackOne tools are available?"
2. **Execute Operations**: Request actions like "Search recent calls in Gong"
3. **Access Resources**: Ask about API schemas or documentation

<Note>
  For troubleshooting, see Claude Desktop's logging capabilities in the [official MCP documentation](https://modelcontextprotocol.io/quickstart/user).
</Note>

## Programmatic Integration

For programmatic integration with Anthropic's Claude API, see the [Anthropic SDK Framework Guide](/mcp/framework-guides/anthropic-sdk).

## Next Steps

<CardGroup>
  <Card title="Claude Code" icon="terminal" href="/mcp/app-guides/claude-code">
    Set up MCP in Claude Code CLI
  </Card>

  <Card title="Authentication Guide" icon="lock" href="/mcp/auth-security">
    Configure authentication and security
  </Card>
</CardGroup>


# Flowise
Source: https://docs.stackone.com/mcp/app-guides/flowise

Connect StackOne MCP server to FlowiseAI for visual AI agent workflows with access to all StackOne integrations.

## Overview

[FlowiseAI](https://flowiseai.com/) is a visual workflow builder for AI agents with native MCP support.

## Prerequisites

* Flowise installed ([installation guide](https://docs.flowiseai.com/))
* A StackOne linked account ([set one up here](/guides/auth-link))

## Setup

<Steps>
  <Step title="Get your MCP URL from the dashboard">
    1. Go to **Connectors** in the left nav and open the connector you want to use
    2. Click **Use Connector** in the top right
    3. On the **Use** tab, click **MCP Server** under "Use with Agent Client"
    4. Select a linked account from the dropdown
    5. Choose **HTTPS MCP** as the client
    6. Copy the generated URL — it looks like:
       ```
       https://api.stackone.com/mcp?token=<session_token>
       ```

    The token encodes your account identity. No separate API key or account ID header is needed.

    <Tip>
      The token expires after one year. Regenerate it at any time using the refresh button in the MCP tile.
    </Tip>
  </Step>

  <Step title="Add MCP Server to Flowise">
    Navigate to your Flowise instance and open the chatflow where you want to add StackOne tools.

    1. In the left sidebar, find **"Custom MCP"** in the **"Tools"** section
    2. Drag the **Custom MCP** component onto your canvas and connect it to your agent
    3. In the MCP Server Config, add:

    ```json theme={null}
    {
      "url": "https://api.stackone.com/mcp?token=<session_token>"
    }
    ```

    Replace `<session_token>` with the token from the previous step.
  </Step>

  <Step title="Configure available tools">
    Once connected, Flowise discovers all available StackOne tools for the account. Use the tool filter to search by provider or action type and enable only what your workflow needs.
  </Step>
</Steps>

***

## Advanced: Manual API Key Setup

If you prefer to authenticate with your API key and account ID directly:

```json theme={null}
{
  "url": "https://api.stackone.com/mcp",
  "headers": {
    "Authorization": "Basic <YOUR_BASE64_TOKEN>",
    "x-account-id": "<YOUR_ACCOUNT_ID>"
  }
}
```

To generate the base64 token:

```bash theme={null}
echo -n "<stackone_api_key>:" | base64
```

See [Authentication & Security](/mcp/auth-security) for details.

***

## Limitations

* **Transport:** StackOne only supports HTTP transport (no STDIO or SSE)
* **Tool Discovery:** Tools are determined by the enabled actions for the integration configuration associated with the linked account

***

## Next Steps

<CardGroup>
  <Card title="Dashboard Setup" icon="desktop" href="/mcp/connect-from-dashboard">
    Generate MCP configs from any connector
  </Card>

  <Card title="Authentication Guide" icon="lock" href="/mcp/auth-security">
    Configure authentication and security
  </Card>

  <Card title="FlowiseAI Docs" icon="external-link" href="https://docs.flowiseai.com/tutorials/tools-and-mcp">
    Official Flowise MCP documentation
  </Card>

  <Card title="Explore All Tools" icon="grid" href="https://app.stackone.com/playground">
    See all available operations in the StackOne Playground
  </Card>
</CardGroup>


# Goose CLI & Desktop
Source: https://docs.stackone.com/mcp/app-guides/goose

Connect StackOne MCP server to Goose AI assistant for automated workflows and on-machine AI assistance.

## Overview

[Goose](https://block.github.io/goose/) is an on-machine AI agent (CLI and Desktop) from Block with MCP support.

## Prerequisites

* Goose installed ([installation guide](https://block.github.io/goose/docs/getting-started/installation/))
* A StackOne linked account ([set one up here](/guides/auth-link))

## Get your MCP URL

Before configuring Goose, get your MCP URL from the StackOne dashboard:

1. Go to **Connectors** in the left nav and open the connector you want to use
2. Click **Use Connector** in the top right
3. On the **Use** tab, click **MCP Server** under "Use with Agent Client"
4. Select a linked account from the dropdown
5. Choose **HTTPS MCP** as the client
6. Copy the generated URL — it looks like:
   ```
   https://api.stackone.com/mcp?token=<session_token>
   ```

The token encodes your account identity. No separate API key or account ID header is needed.

<Tip>
  The token expires after one year. Regenerate it at any time using the refresh button in the MCP tile.
</Tip>

***

## Setup Methods

Goose supports two methods: **Interactive Configuration** (easiest) and **Manual YAML** (advanced).

***

## Method 1: Interactive Configuration (Recommended)

Run the configuration wizard:

```bash theme={null}
goose configure
```

<Steps>
  <Step title="Select 'Add Extension'">
    When prompted, choose **"Add Extension"** from the menu.
  </Step>

  <Step title="Choose Extension Type">
    Select **"Remote Extension"** — StackOne uses HTTP transport.
  </Step>

  <Step title="Name Your Extension">
    Enter a name: `stackone` (or any name you prefer).
  </Step>

  <Step title="Enter Server URL">
    Paste the URL from the dashboard:

    ```
    https://api.stackone.com/mcp?token=<session_token>
    ```
  </Step>

  <Step title="Enable Extension">
    When asked if you want to enable the extension, select **"Yes"**.
  </Step>
</Steps>

***

## Method 2: Manual YAML Configuration

Find your Goose config file:

* **Linux/Mac**: `~/.config/goose/config.yaml`
* **Windows**: `%APPDATA%\goose\config.yaml`

Add the following under `extensions`:

```yaml theme={null}
extensions:
  stackone:
    name: stackone
    type: http
    url: https://api.stackone.com/mcp?token=<session_token>
    enabled: true
    timeout: 300
```

Replace `<session_token>` with the token from the dashboard.

<Accordion title="Multiple accounts">
  Add separate entries for each account:

  ```yaml theme={null}
  extensions:
    salesforce:
      name: salesforce
      type: http
      url: https://api.stackone.com/mcp?token=<salesforce_session_token>
      enabled: true
      timeout: 300

    slack:
      name: slack
      type: http
      url: https://api.stackone.com/mcp?token=<slack_session_token>
      enabled: true
      timeout: 300
  ```
</Accordion>

***

## Advanced: Manual API Key Setup

If you prefer to authenticate with your API key and account ID directly:

```yaml theme={null}
extensions:
  stackone:
    name: stackone
    type: http
    url: https://api.stackone.com/mcp
    enabled: true
    timeout: 300
    headers:
      Authorization: "Basic <YOUR_BASE64_TOKEN>"
      x-account-id: "<YOUR_ACCOUNT_ID>"
```

To generate the base64 token:

```bash theme={null}
echo -n "<stackone_api_key>:" | base64
```

Using environment variables:

```yaml theme={null}
extensions:
  stackone:
    name: stackone
    type: http
    url: https://api.stackone.com/mcp
    enabled: true
    timeout: 300
    headers:
      Authorization: "Basic ${STACKONE_AUTH_TOKEN}"
      x-account-id: "${STACKONE_ACCOUNT_ID}"
```

See [Authentication & Security](/mcp/auth-security) for details.

***

## Verify Installation

After configuration, start a Goose session and check available tools:

```bash theme={null}
goose session
```

Then ask:

```
what tools do you have?
```

You should see StackOne operations based on your connected accounts.

***

## Desktop Application

If using Goose Desktop:

1. Open Goose Desktop
2. Go to **Settings** → **Extensions**
3. Your StackOne extension should appear in the list
4. Toggle to enable/disable as needed

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Extension not loading">
    **Symptoms:** StackOne tools don't appear when asked "what tools do you have?"

    1. Verify config file location: `goose info -v`
    2. Check YAML syntax (indentation matters)
    3. Ensure the extension is marked `enabled: true`
    4. Restart Goose after config changes
    5. Check logs: `goose logs`
  </Accordion>

  <Accordion title="Authentication errors">
    **Symptoms:** "401 Unauthorized" or "403 Forbidden"

    If using a dashboard token, regenerate it from the MCP tile in the dashboard.

    If using manual API key auth:

    1. Verify base64 encoding includes the trailing colon: `echo -n "your_api_key:" | base64`
    2. Confirm the account ID matches your linked account
    3. Check the API key is valid in [StackOne Dashboard](https://app.stackone.com)
  </Accordion>

  <Accordion title="Connection timeout">
    Increase the timeout in your config:

    ```yaml theme={null}
    timeout: 600  # 10 minutes
    ```
  </Accordion>

  <Accordion title="No tools available">
    1. Verify you have active integrations in the StackOne Dashboard
    2. Check that actions are enabled in your integration config
    3. Review [StackOne Playground](https://app.stackone.com/playground) to see expected tools
  </Accordion>

  <Accordion title="YAML configuration errors">
    1. Validate YAML syntax at [https://www.yamllint.com/](https://www.yamllint.com/)
    2. Check indentation (use spaces, not tabs)
    3. Ensure quotes around header values
    4. Run: `goose info -v` to see config parsing errors
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup>
  <Card title="Dashboard Setup" icon="desktop" href="/mcp/connect-from-dashboard">
    Generate MCP configs from any connector
  </Card>

  <Card title="Authentication Guide" icon="lock" href="/mcp/auth-security">
    Configure authentication and security
  </Card>

  <Card title="Goose Documentation" icon="book" href="https://block.github.io/goose/docs/">
    Learn more about Goose capabilities
  </Card>

  <Card title="Explore All Tools" icon="grid" href="https://app.stackone.com/playground">
    See all available operations in StackOne Playground
  </Card>
</CardGroup>


# n8n Automation
Source: https://docs.stackone.com/mcp/app-guides/n8n

Use StackOne MCP in n8n workflows with the MCP Client Tool node for automated operations.

## Overview

[n8n](https://n8n.io/) provides MCP support through its MCP Client Tool node for workflow automation.

## Setup

<Steps>
  <Step title="Get your MCP URL from the dashboard">
    1. Go to **Connectors** in the left nav and open the connector you want to use
    2. Click **Use Connector** in the top right
    3. On the **Use** tab, click **MCP Server** under "Use with Agent Client"
    4. Select a linked account from the dropdown
    5. Choose **HTTPS MCP** as the client
    6. Copy the generated URL — it looks like:
       ```
       https://api.stackone.com/mcp?token=<session_token>
       ```

    The token encodes your account identity. No separate API key or account ID header is needed.

    <Tip>
      The token expires after one year. Regenerate it at any time using the refresh button in the MCP tile.
    </Tip>
  </Step>

  <Step title="Add MCP Client Tool in n8n">
    <Frame>
      <img alt="" />
    </Frame>

    1. Create a new workflow
    2. Click **+** to add a node and search for "MCP Agent"
    3. Under tools, click **+** and search for **MCP Client Tool**
    4. Configure the node:
       * **URL**: Paste the URL from the previous step
       * **Authentication**: None
       * Select the tools you want from the **Tools to include** dropdown
  </Step>

  <Step title="Test the connection">
    Click **Execute Step** to verify the connection and see available tools.
  </Step>
</Steps>

***

## Advanced: Manual API Key Setup

If you prefer to authenticate with your API key and account ID directly instead of a dashboard-generated token:

1. Set the URL to `https://api.stackone.com/mcp?x-account-id=<ACCOUNT_ID>`
2. Set **Authentication** to **Header Auth** (create new credentials if needed):
   * Header name: `Authorization`
   * Value: `Basic <BASE64_STACKONE_API_KEY>` — base64-encode your API key followed by a colon (`your_api_key:`)

See [Authentication & Security](/mcp/auth-security) for details on obtaining your API key and account ID.

***

## Building Workflows

Once configured, use the MCP Client Tool node to execute StackOne actions on the linked account you specified.

## Next Steps

<CardGroup>
  <Card title="Dashboard Setup" icon="desktop" href="/mcp/connect-from-dashboard">
    Generate MCP configs from any connector
  </Card>

  <Card title="Authentication Guide" icon="lock" href="/mcp/auth-security">
    Configure authentication and security
  </Card>
</CardGroup>

***

For detailed n8n setup instructions, see the [official n8n documentation](https://docs.n8n.io/).


# Postman
Source: https://docs.stackone.com/mcp/app-guides/postman

Connect StackOne MCP to Postman to test and interact with MCP tools using HTTP requests.

## Overview

[Postman](https://www.postman.com/) is a popular API development and testing tool that allows you to send HTTP requests and receive responses. You can use Postman to interact with StackOne's MCP server by making JSON-RPC 2.0 requests.

<Info>
  Postman is ideal for testing MCP endpoints, debugging requests, and exploring available tools before integrating into your application.
</Info>

## Get the StackOne public Postman collection

The StackOne public Postman collection comes with a pre-configured MCP request:

<Card title="Open in Postman" icon="postman" href="https://god.gw.postman.com/run-collection/68ca4160009b6f9cc908f435?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D68ca4160009b6f9cc908f435%26entityType%3DextensibleCollection%26workspaceId%3Df291b2e0-d0cb-4dc2-93c4-c2d4f581da3f">
  Fork this collection to get started
</Card>

The collection already includes:

* MCP requests in the **StackOne MCP** folder
* Basic Auth configured with `{{apiKey}}` as the username
* `x-account-id` header set to `{{accountID}}`
* URL pre-configured to `https://api.stackone.com/mcp`

## Setup

<Steps>
  <Step title="Create a Postman Environment">
    1. Open Postman
    2. Click the **Environments** icon in the left sidebar
    3. Click **+** to create a new environment
    4. Name it "StackOne MCP" (or your preferred name)
  </Step>

  <Step title="Add Environment Variables">
    Add the following variables to your environment (these match the variable names used in the collection):

    | Variable    | Initial Value     | Current Value     |
    | ----------- | ----------------- | ----------------- |
    | `apiKey`    | `your-api-key`    | `your-api-key`    |
    | `accountID` | `your-account-id` | `your-account-id` |

    <Tip>
      You can generate a new API key in the [StackOne Dashboard](https://app.stackone.com/api_keys). You can find your account ID in the [StackOne Dashboard](https://app.stackone.com) under your linked accounts.
    </Tip>
  </Step>

  <Step title="Select Your Environment">
    In the top-right corner of Postman, select your "StackOne MCP" environment from the dropdown to activate it.
  </Step>
</Steps>

<Frame>
  <img alt="Example Postman environment" />
</Frame>

## Using the MCP Request

After forking the collection and setting up your environment variables, you'll find a pre-configured MCP request in the **StackOne MCP** folder. The MCP protocol uses JSON-RPC 2.0 format.

### Send Your First Request

1. Navigate to the **StackOne MCP** folder in your forked collection
2. Select the **Connect to StackOne MCP** request
3. Make sure your environment is selected in the top-right corner
4. Under the **Message** tab, click "Load Capabilities"
5. This will show all the available tools for the account you've connected to
6. Select the tool you want to use, fill in any required fields, and click "Run"

You should receive a JSON response from the API with the results of request.

<Info>
  The next time you load the collection, it should automatically load the capabilities for the account you've connected to.
</Info>

<Frame>
  <img alt="Postman MCP request showing a selected tool, request parameters, and JSON response" />
</Frame>

## Next Steps

<CardGroup>
  <Card title="MCP Quickstart" icon="rocket" href="/mcp/quickstart">
    Learn more about StackOne MCP
  </Card>

  <Card title="Authentication Guide" icon="lock" href="/mcp/auth-security">
    Configure authentication and security
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/mcp/troubleshooting">
    Resolve common issues
  </Card>

  <Card title="Framework Guides" icon="code" href="/mcp/framework-guides/anthropic-sdk">
    Integrate MCP into your application
  </Card>
</CardGroup>


# Authentication & Security
Source: https://docs.stackone.com/mcp/auth-security

Learn about MCP authentication methods, required headers, and security best practices for StackOne MCP integration.

## Authentication Methods

StackOne MCP server uses the same authentication as the regular StackOne API, ensuring consistent security across all integration methods.

<AccordionGroup>
  <Accordion title="Get your API key" icon="key">
    1. Go to <a href="https://app.stackone.com/api_keys">**Configuration → API Keys**</a> in the dashboard
    2. Click **Create API Key** and copy it securely

    <Warning>
      API keys are shown only once. Store securely.
    </Warning>

    See [API Keys Guide](/guides/api-keys) for detailed instructions.
  </Accordion>

  <Accordion title="Get your Account ID" icon="id-card">
    1. Go to <a href="https://app.stackone.com/accounts">**Accounts**</a> in the dashboard
    2. Select your linked account
    3. Copy the account ID (e.g., `47187425466113776871`)

    You can also retrieve account IDs via the [List Accounts API](/platform/api-reference/accounts/list-accounts).
  </Accordion>
</AccordionGroup>

### Basic Authentication (Recommended)

StackOne MCP uses the same Basic Auth as all StackOne APIs:

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    # -u flag auto-encodes to base64
    curl -u "$STACKONE_API_KEY:" https://api.stackone.com/mcp ...
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const encoded = Buffer.from(`${apiKey}:`).toString('base64');
    fetch(url, { headers: { 'Authorization': `Basic ${encoded}` } });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import base64
    encoded = base64.b64encode(f"{api_key}:".encode()).decode()
    headers = {'Authorization': f'Basic {encoded}'}
    ```
  </Tab>
</Tabs>

## Required Headers

### Core Headers

All MCP requests require these headers:

```bash theme={null}
Authorization: Basic <BASE64_ENCODED_STACKONE_API_KEY>
x-account-id: <ACCOUNT_ID>
Content-Type: application/json
Accept: application/json,text/event-stream
```

<Warning>
  **Critical: Accept Header is Mandatory**

  The `Accept: application/json,text/event-stream` header is **required by the MCP specification** (version 2025-03-26), not just StackOne.

  * **Both formats must be listed** - you cannot use only `application/json` or wildcards like `*/*`
  * This header is required on **every request** (initialize, tools/list, tools/call, etc.)
  * Without this header, you'll receive a `406 Not Acceptable` error

  This requirement allows the MCP server to choose between returning single JSON responses or Server-Sent Events streams based on the operation.

  **Source**: [MCP Specification - Streamable HTTP Transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports)
</Warning>

**Optional Protocol Header:**

```bash theme={null}
MCP-Protocol-Version: 2025-06-18
```

StackOne supports protocol versions `2025-03-26` and `2025-06-18`. Most clients handle this automatically.

## Account ID

The account ID can be passed in two ways:

### 1. Header Method (Recommended)

```bash theme={null}
x-account-id: 47187425466113776871
```

### 2. Query Parameter (Fallback)

For clients that don't support custom headers:

```bash theme={null}
https://api.stackone.com/mcp?x-account-id=47187425466113776871
```

**Account ID Format:**

* Numeric string (e.g., `47187425466113776871`)
* Short alphanumeric ID (e.g., `abc123xyz`)

<Note>
  The header method takes precedence if both are provided. Use query parameters only when custom headers are not supported by your MCP client.
</Note>

## Transport Protocol

StackOne uses **Streamable HTTP transport** exclusively:

* **Protocol**: HTTPS only
* **Method**: POST requests for all operations
* **No SSE**: Server-Sent Events are not supported
* **Session Management**: Stateless (no session support currently)

## Security Best Practices

### Always Use HTTPS

✅ **Correct**: `https://api.stackone.com/mcp`
❌ **Incorrect**: `http://api.stackone.com/mcp`

### Store API Keys Securely

Use environment variables and never commit API keys to version control.

## Troubleshooting Authentication

For authentication errors and common issues, see our comprehensive [Troubleshooting Guide](/mcp/troubleshooting) which covers:

* 401 Unauthorized errors
* 403 Forbidden errors
* Missing header issues (especially Accept header)
* Base64 encoding problems
* Account ID validation
* 406 Not Acceptable errors

## Testing Authentication

Verify your authentication setup with a simple `initialize` CURL request or [using Postman](/mcp/quickstart#postman-testing-visual-interface):

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.stackone.com/mcp \
    -H 'Authorization: Basic <YOUR_BASE64_TOKEN>' \
    -H 'x-account-id: <YOUR_ACCOUNT_ID>' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json,text/event-stream' \
    -H 'MCP-Protocol-Version: 2025-06-18' \
    -d '{
      "jsonrpc": "2.0",
      "id": "auth-test",
      "method": "initialize",
      "params": {
        "clientInfo": {"name": "auth-test", "version": "1.0.0"},
        "protocolVersion": "2025-06-18",
        "capabilities": {}
      }
    }'
  ```
</CodeGroup>

A successful response confirms your authentication is configured correctly.

## Next Steps

Once authentication is configured:

<CardGroup>
  <Card title="Try the Quickstart" icon="rocket" href="/mcp/quickstart">
    Test your setup with basic MCP operations
  </Card>

  <Card title="Choose Your Client" icon="desktop" href="/mcp/app-guides/claude-desktop">
    Configure your preferred MCP client
  </Card>
</CardGroup>


# Connect MCP from the Dashboard
Source: https://docs.stackone.com/mcp/connect-from-dashboard

Generate MCP connection configs for any connector directly from the StackOne dashboard.

Every connector in your project has a built-in flow for generating MCP connection configs. Once an account is linked, you can get a ready-to-paste config for Claude Desktop, Claude Code, Cursor, VS Code, or any other MCP-compatible client in three clicks.

## Prerequisites

* A linked account for the connector you want to use. See [Embedding the StackOne Hub](/guides/embedding-stackone-hub) or [Auth Links](/guides/auth-link) to add one.

***

## How to get your MCP config

<Steps>
  <Step title="Open a connector">
    Go to **Connectors** in the left nav, then click any connector to open its detail page.

    <Frame>
      <img alt="Connectors list showing available connectors with Actions, Configs, and Accounts counts" />
    </Frame>
  </Step>

  <Step title="Click 'Use Connector'">
    Click the **Use Connector** button in the top-right of the connector detail page. This opens the "Get Started with Connector" panel.

    <Frame>
      <img alt="Connector detail page showing the Use Connector button in the top-right header" />
    </Frame>

    <Note>
      If the connector isn't configured yet, you'll see a setup wizard instead. Complete both steps — create a connector profile, then link an account — and the **Use** tab with the MCP tile will appear.
    </Note>
  </Step>

  <Step title="Select your account">
    On the **Use** tab, click **MCP Server** under "Use with Agent Client" to expand the tile.

    Select a linked account from the dropdown. StackOne generates a token for that account automatically.

    <Frame>
      <img alt="MCP Server tile showing account selector dropdown" />
    </Frame>
  </Step>

  <Step title="Choose your client">
    Pick the client you want to connect. Supported options:

    | Client         | Config format                  |
    | -------------- | ------------------------------ |
    | HTTPS MCP      | Direct URL                     |
    | Claude Desktop | JSON (`mcpServers` block)      |
    | Claude Code    | CLI command (`claude mcp add`) |
    | Cursor         | URL + one-click deep link      |
    | VS Code        | URL + one-click deep link      |
    | Codex CLI      | CLI command                    |
    | Gemini CLI     | JSON (`mcpServers` block)      |
    | Windsurf       | JSON (`mcpServers` block)      |
    | Zed            | JSON (`context_servers` block) |
    | Kiro           | JSON (`mcpServers` block)      |
    | Raycast        | URL                            |
    | LM Studio      | URL                            |

    <Frame>
      <img alt="Client selection grid showing icons for all supported MCP clients" />
    </Frame>
  </Step>

  <Step title="Copy the config">
    The panel shows the config in the right format for your client, with a copy button.

    For clients that use a config file (Claude Desktop, Gemini CLI, etc.), the panel also shows the exact file path to paste it into.

    For Cursor and VS Code, you can skip the copy step entirely and click **Add to Cursor** or **Add to VS Code** to install it directly via deep link.

    <Frame>
      <img alt="Config panel showing JSON configuration with copy button and file path" />
    </Frame>

    Paste the config into the specified file or terminal, then restart your client.
  </Step>
</Steps>

***

## What the MCP URL looks like

The generated URL follows this format:

```
https://api.stackone.com/mcp?token=<session_token>
```

The token encodes the account identity and expires after one year. You can regenerate it at any time using the refresh button in the MCP tile.

<Tip>
  The token-based URL is useful for quick setup and testing. For production deployments, use your API key and account ID directly. See [Authentication & Security](/mcp/auth-security) for details.
</Tip>

***

## Next steps

<CardGroup>
  <Card title="MCP Quickstart" icon="rocket" href="/mcp/quickstart">
    Full endpoint reference and authentication options
  </Card>

  <Card title="Authentication & Security" icon="lock" href="/mcp/auth-security">
    Token types, expiry, and production auth patterns
  </Card>
</CardGroup>


# Frequently Asked Questions
Source: https://docs.stackone.com/mcp/faq

Common questions and answers about StackOne MCP integration, features, limitations, and best practices.

## General Questions

<AccordionGroup>
  <Accordion title="What is the Model Context Protocol (MCP)?">
    The Model Context Protocol (MCP) is an open standard for connecting AI applications to external data sources and tools. It provides a standardized way for Large Language Models (LLMs) to access and interact with various services, databases, and APIs.

    StackOne implements MCP to give AI agents direct access to all platform actions across HRIS, ATS, CRM, and other business systems. This includes both unified operations and custom integrations created by customers, without requiring additional setup for each provider.
  </Accordion>

  <Accordion title="How does StackOne MCP differ from the regular StackOne API?">
    **StackOne API:**

    * Direct HTTP REST API calls
    * Requires manual integration and error handling
    * Developer builds custom tools/functions
    * Static documentation and schemas

    **StackOne MCP:**

    * Standardized protocol for AI agents
    * Automatic tool discovery and execution
    * Built-in error handling and retries
    * Dynamic schemas and real-time capabilities
    * Optimized for AI agent consumption

    MCP provides a more intelligent, agent-friendly interface to the same underlying StackOne platform actions.
  </Accordion>

  <Accordion title="Which MCP transport protocols does StackOne support?">
    StackOne supports **Streamable HTTP transport only**:

    * ✅ **Streamable HTTP**: POST/GET requests with JSON-RPC
    * ❌ **Server-Sent Events (SSE)**: Not supported (legacy)
    * ❌ **STDIO**: Not applicable for cloud-hosted service

    This choice provides better reliability, easier debugging, and broader client compatibility compared to SSE-based transports.
  </Accordion>
</AccordionGroup>

## Setup and Configuration

<AccordionGroup>
  <Accordion title="Which clients support StackOne MCP?">
    See our [client guides](/mcp/app-guides/claude-desktop) for specific setup instructions. Practically, any MCP client that supports the Streamable HTTP transport will work with StackOne MCPs.
  </Accordion>

  <Accordion title="How do I get my StackOne API credentials for MCP?">
    <Steps>
      <Step title="Access the API Key Management Section">
        Log in to StackOne and go to the "API Keys" section in the left navigation menu. This is where you can generate and manage your API keys.
      </Step>

      <Step title="Generate a New API Key">
        Click the "Create API Key" button. In the popup dialog, enter a name for your key (e.g., "stackone-mcp-key"). This name is a label and cannot be changed later. Click "Generate" to create your unique API key.
      </Step>

      <Step title="Select API Key Scopes (optional)">
        By default, API keys are created with full permissions. If you need to restrict the key's access, you can select specific scopes by expanding the "Scopes" section and selecting the scopes that match your application's needs.
      </Step>

      <Step title="Securely Store the API Key">
        The API key will be displayed on-screen. Copy it immediately and store it securely, as this is the only time it will be shown. If you lose the key, you'll need to generate a new one.
      </Step>
    </Steps>

    <Info>
      For complete, visual instructions on generating and managing API keys (including detailed steps & screenshots), see our [API Keys guide](/guides/api-keys).
    </Info>

    **Security Note:** It is good practice to use different StackOne projects per environments (development, staging, production) and generate separate API keys for each.
  </Accordion>

  <Accordion title="Can I use MCP with multiple StackOne accounts?">
    Yes! You can configure multiple StackOne accounts in most MCP clients. Each account gets its own MCP server instance with different tools based on that account's integrations.
  </Accordion>

  <Accordion title="What authentication methods are supported?">
    **Primary Method - Basic Authentication (Required):**

    ```http theme={null}
    Authorization: Basic <BASE64_ENCODED_STACKONE_API_KEY>
    x-account-id: <ACCOUNT_ID>
    ```

    **How to encode API key:**

    ```bash theme={null}
    echo -n "<stackone_api_key>" | base64
    ```

    *Note: Include the colon after the API key*

    **Required Headers:**

    * `Authorization`: Basic auth with base64-encoded API key
    * `x-account-id`: Your StackOne account ID (header method recommended)

    **Alternative - Query Parameter:**

    ```
    https://api.stackone.com/mcp?x-account-id=<ACCOUNT_ID>
    ```

    Use this for clients that don't support the `x-account-id` custom header. Header method takes precedence if both are provided.

    See [Authentication Guide](/mcp/auth-security) for detailed setup.
  </Accordion>
</AccordionGroup>

## Features and Capabilities

<AccordionGroup>
  <Accordion title="What StackOne operations are available through MCP?">
    **All StackOne platform actions** are available as MCP tools, dynamically generated based on your account's active integrations. This includes provider-specific operations, custom actions, and unified operations.

    <Note>
      The examples below are **samples only**. To see the complete list of operations available for your account:

      * **Explore in Playground**: [app.stackone.com/playground](https://app.stackone.com/playground)
      * **Browse Connectors**: [app.stackone.com/connectors](https://app.stackone.com/connectors)

      Everything visible in the playground and connectors pages is accessible via MCP.
    </Note>

    **Provider-Specific Actions (Sample Examples):**

    * `gong_crm_search_calls` - Search CRM calls in Gong
    * `ashby_list_applications` - List applications from Ashby ATS
    * `workday_list_employees` - List employees from Workday HRIS
    * `salesforce_list_accounts` - List accounts from Salesforce CRM
    * `asana_list_tickets` - List tickets from Asana
    * Custom provider operations based on your connected integrations
    * And thousands more pre-built actions.

    **Unified Operations (Sample Examples):**

    * `unified_hris_list_employees` - List employees (works across all HRIS providers)
    * `unified_ats_list_jobs` - List jobs (works across all ATS providers)
    * `unified_crm_list_contacts` - List contacts (works across all CRM providers)
    * and thousands more pre-built unified actions.

    **Custom Integrations & Actions:**

    * Any integrations created by you using our Connector Engine & Integration As Code setup.
    * Custom actions built via StackOne's action builder
    * Provider-specific operations not covered by unified APIs

    **Categories Supported:**
    HRIS, ATS, CRM, Marketing Automation, IT Management, IAM, LMS, Documents, Assessments, Background Checks, Screening, Messaging, Ticketing, Accounting, and more. See [all integrations](https://www.stackone.com/integrations).

    **Dynamic Tool Discovery:**

    * Only actions for YOUR connected providers appear
    * Actions respect your integration configuration and permissions
    * Use `tools/list` to see what's available for your specific account
  </Accordion>

  <Accordion title="Do MCP tools support all API parameters and features?">
    Yes! MCP tools provide full access to StackOne API capabilities:

    **Supported Features:**

    * ✅ All query parameters (limit, cursor, filters, etc.)
    * ✅ Request body parameters for POST/PUT operations
    * ✅ Include/expand parameters
    * ✅ Custom field access
    * ✅ Error handling
    * ✅ Pagination with cursors for unified actions
    * ✅ Real-time data by default
  </Accordion>

  <Accordion title="Can I use MCP for real-time data sync?">
    MCP is designed for **on-demand operations**, not continuous real-time sync:

    **Good Use Cases for MCP:**

    * Interactive queries ("Show me recent employees")
    * Triggered operations ("Create employee when form submitted")
    * Periodic  operations (via scheduled workflows)
    * AI-driven data analysis and reporting

    **Not Optimal For:**

    * Continuous real-time streaming
    * High-frequency automated syncing
    * Background data replication

    **For Real-Time Sync, Use Instead:**

    * **[StackOne Unified API](/hris/introduction)** - Direct API calls optimized for bulk data retrieval with pagination, filtering, and `updated_after` parameters
    * **[StackOne Webhooks](/guides/webhooks)** - Real-time change notifications when data updates in connected providers
    * **[Action RPC Endpoint](/platform/api-reference/actions/make-an-rpc-call-to-an-action)** - Direct execution of custom actions and provider-specific operations for high-frequency workflows

    **Hybrid Approach:**

    * Use Unified API + Webhooks for continuous sync
    * Use MCP for AI-driven queries and analysis on synced data
    * Combine both for the best of real-time data and intelligent agents
  </Accordion>

  <Accordion title="How does error handling work in MCP?">
    For details and examples of MCP error handling, including protocol errors, causes, and solutions, see our [Troubleshooting Guide](/mcp/troubleshooting).

    **Client Handling:**
    Most MCP clients handle errors gracefully and can retry operations or provide alternative suggestions to users.
  </Accordion>
</AccordionGroup>

## Performance and Limits

<AccordionGroup>
  <Accordion title="What are the rate limits for MCP operations?">
    MCP operations use the same rate limits as regular StackOne API calls:

    **Standard Limits:**

    * **60 requests per minute** per API key
    * **1,000 requests per hour** per API key
    * **10,000 requests per day** per account

    **Headers Returned:**

    ```http theme={null}
    X-RateLimit-Limit: 60
    X-RateLimit-Remaining: 45
    X-RateLimit-Reset: 1640995200
    ```

    **Best Practices:**

    * Use pagination to reduce large queries
    * Cache results when appropriate
    * Implement exponential backoff for retries
    * Monitor rate limit headers

    **Enterprise Plans:**
    Higher rate limits available - contact StackOne support for details.
  </Accordion>

  <Accordion title="How do I optimize MCP performance?">
    **Client-Side Optimizations:**

    1. **Cache Tool Definitions:**
       ```javascript theme={null}
       // Cache tools list to avoid repeated calls
       let cachedTools = await mcpClient.listTools();
       ```

    2. **Use Appropriate Pagination:**
       ```json theme={null}
       {
         "limit": 25,  // Optimal batch size
         "cursor": "next_page_token"
       }
       ```

    3. **Connection Reuse:**
       ```javascript theme={null}
       // Reuse MCP client connections
       const client = new StackOneMCPClient(apiKey, accountId);
       await client.initialize(); // Once per session
       ```

    **Server-Side Optimizations:**

    * StackOne automatically optimizes MCP responses
    * Results are compressed when possible
    * Provider connection pooling for faster operations
    * Intelligent caching where appropriate
  </Accordion>

  <Accordion title="Are there size limits for MCP requests/responses?">
    **Request Limits:**

    * Maximum request size: **10MB**
    * Maximum parameters per tool call: **1,000**
    * Maximum nested object depth: **10 levels**

    **Response Limits:**

    * Maximum response size: **50MB** (compressed)
    * Large datasets automatically paginated
    * Binary data (files) handled via streaming

    **Pagination Recommendations:**

    * Use `limit` parameter to control response size
    * Default limits: 25-100 items per page
    * Maximum limit: 1,000 items per page (varies by endpoint)

    **For Large Operations:**
    Consider breaking down into multiple smaller MCP tool calls rather than one large operation.
  </Accordion>
</AccordionGroup>

## Development and Integration

<AccordionGroup>
  <Accordion title="Can I build custom MCP tools that use StackOne data?">
    **Yes!** You can create custom MCP servers that combine StackOne data with other sources:

    ```python theme={null}
    from mcp.server import Server
    from stackone import StackOneClient

    app = Server("custom-stackone-mcp")
    stackone = StackOneClient(api_key="...", account_id="...")

    @app.tool("analyze_employee_trends")
    async def analyze_trends(time_period: str) -> str:
        # Get StackOne data
        employees = await stackone.hris.list_employees(
            updated_after=get_date_filter(time_period)
        )

        # Add custom analysis
        trends = perform_custom_analysis(employees.data)

        return format_trend_report(trends)
    ```

    **Use Cases:**

    * Combine StackOne data with internal databases
    * Add custom business logic and calculations
    * Create domain-specific abstractions
    * Implement custom caching or data transformation
  </Accordion>

  <Accordion title="How do I implement StackOne MCP in a framework without native support?">
    **For Frameworks Without Native MCP Support:**

    1. **Create HTTP Client Wrapper:**
       ```typescript theme={null}
       class StackOneMCPClient {
         async callTool(name: string, args: any) {
           const response = await fetch('https://api.stackone.com/mcp', {
             method: 'POST',
             headers: this.getHeaders(),
             body: JSON.stringify({
               jsonrpc: '2.0',
               id: Date.now().toString(),
               method: 'tools/call',
               params: { name, arguments: args }
             })
           });
           return response.json();
         }
       }
       ```

    2. **Convert to Framework Tools:**
       ```javascript theme={null}
       // For OpenAI Functions
       const tools = mcpTools.map(tool => ({
         type: 'function',
         function: {
           name: tool.name,
           description: tool.description,
           parameters: tool.inputSchema
         }
       }));
       ```

    3. **Handle Execution:**
       ```javascript theme={null}
       async function handleToolCall(toolCall) {
         const result = await mcpClient.callTool(
           toolCall.function.name,
           JSON.parse(toolCall.function.arguments)
         );
         return formatResult(result);
       }
       ```

    See our [framework guides](/mcp/framework-guides/vercel-ai-sdk) for specific examples.
  </Accordion>

  <Accordion title="Is there a TypeScript SDK for StackOne MCP?">
    **Currently No Official SDK**, but you can use our examples:

    **Basic TypeScript Client:**

    ```typescript theme={null}
    import type { MCPRequest, MCPResponse, MCPTool } from './mcp-types';

    export class StackOneMCPClient {
      constructor(
        private apiKey: string,
        private accountId: string
      ) {}

      async callTool<T = any>(
        name: string,
        arguments_: Record<string, any>
      ): Promise<T> {
        const response = await fetch('https://api.stackone.com/mcp', {
          method: 'POST',
          headers: this.getHeaders(),
          body: JSON.stringify({
            jsonrpc: '2.0',
            id: crypto.randomUUID(),
            method: 'tools/call',
            params: { name, arguments: arguments_ }
          })
        });

        const result: MCPResponse<T> = await response.json();

        if (result.error) {
          throw new Error(result.error.message);
        }

        return this.parseContent(result.result?.content);
      }
    }
    ```

    **Community SDKs:**

    * Check npm for community-maintained packages
    * Consider contributing to open-source MCP clients
    * Use our examples as starting points

    **Future Plans:**
    Official TypeScript/JavaScript SDK for MCP is under consideration.
  </Accordion>
</AccordionGroup>

## Compatibility

<AccordionGroup>
  <Accordion title="I'm using StackOne REST API - should I migrate to MCP?">
    **Consider MCP if you:**

    * ✅ Building AI agents or LLM applications
    * ✅ Want dynamic tool discovery
    * ✅ Need standardized AI integrations
    * ✅ Use supported MCP clients (Claude, VS Code, etc.)
    * ✅ Want reduced integration complexity

    **Stick with REST API if you:**

    * ❌ Building traditional web/mobile applications
    * ❌ Using frameworks without MCP support
    * ❌ Have complex custom data processing needs

    **Hybrid Approach:**
    Many customers use both:

    * MCP for building AI agents
    * API for other more deterministic functionality (eg. needing to render a UI on top of the data)
  </Accordion>

  <Accordion title="Will my existing StackOne integrations work with MCP?">
    **Yes!** MCP uses the same underlying StackOne platform:

    **Automatic Compatibility:**

    * All existing provider connections work with MCP
    * Same data models and schemas for unified operations
    * Identical field mappings and transformations for unified operations
    * Same rate limits and permissions

    **No Changes Required:**

    * Provider configurations remain the same
    * API keys work for both REST and MCP
    * Account settings apply to both interfaces
  </Accordion>

  <Accordion title="How do I reduce context window usage with many MCP tools?">
    By default, StackOne registers each enabled action as its own MCP tool. For integrations with many actions, this can consume significant context window tokens.

    Use **search & execute mode** to keep the tool footprint constant at two tools regardless of how many actions your integration supports:

    ```
    https://api.stackone.com/mcp?tool-mode=search_execute
    ```

    This registers two tools:

    * `{provider}_search_actions` — accepts a natural language query and returns matching actions with their `action_id`
    * `{provider}_execute_action` — runs any action by its `action_id`

    The agent searches first, then executes — trading tool-list brevity for an extra round trip.

    See [Tool Modes](/mcp/tool-modes) for setup examples and when to use each mode.
  </Accordion>

  <Accordion title="How do I control which actions are available to MCP clients?">
    StackOne MCP servers automatically respect your integration configuration and action selection:

    **Integration Configuration:**

    * Actions must be enabled in the integration configuration associated with the linked account(s)
    * Only enabled actions appear in `tools/list` responses
    * This applies to both unified and provider-specific actions

    **Account-Level Control:**

    * Actions deselected at the integration or linked account level are filtered out
    * Changes take effect immediately for all MCP clients

    **Example:** If you disable "Create Employee" in your Workday integration configuration, the `workday_create_employee` tool won't appear in MCP linked to an account using that configuration, even if the integration technically supports it.
  </Accordion>
</AccordionGroup>

## Still Have Questions?

<CardGroup>
  <Card title="Troubleshooting Guide" icon="wrench" href="/mcp/troubleshooting">
    Debug common issues and errors
  </Card>

  <Card title="StackOne Support" icon="headset" href="https://app.stackone.com">
    Contact support through dashboard
  </Card>

  <Card title="MCP Documentation" icon="book" href="https://modelcontextprotocol.io">
    Official MCP protocol docs
  </Card>

  <Card title="Community Forums" icon="users" href="/mcp/">
    Join the StackOne community
  </Card>
</CardGroup>


# Anthropic SDK (Python)
Source: https://docs.stackone.com/mcp/framework-guides/anthropic-sdk

Connect StackOne MCP to Anthropic's Claude SDK using the official MCP Python client.

## Overview

Anthropic provides native MCP client support through the official `mcp` Python SDK, enabling direct integration with StackOne's MCP server.

[MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)

## Installation

```bash theme={null}
uv add anthropic mcp httpx
```

## Quick Start

Connect to StackOne MCP and use tools with Claude:

```python theme={null}
import os
import asyncio
import base64
from anthropic import Anthropic
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

# Configure StackOne account
STACKONE_ACCOUNT_ID = "<account_id>"  # Your StackOne account ID

# Encode API key for Basic auth
auth_token = base64.b64encode(
    f"{os.getenv('STACKONE_API_KEY')}:".encode()
).decode()

async def main():
    # Connect to StackOne MCP
    async with streamablehttp_client(
        url="https://api.stackone.com/mcp",
        headers={
            "Authorization": f"Basic {auth_token}",
            "x-account-id": STACKONE_ACCOUNT_ID
        }
    ) as (read, write, get_session_id):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # Get StackOne tools
            tools_response = await session.list_tools()
            tools = [{
                "name": t.name,
                "description": t.description,
                "input_schema": t.inputSchema
            } for t in tools_response.tools]

            # Use with Claude
            client = Anthropic()
            messages = [{"role": "user", "content": "Search recent calls in Gong"}]

            response = client.messages.create(
                model="claude-haiku-4-5-20251001",
                max_tokens=4096,
                tools=tools,
                messages=messages
            )

            # Handle tool calls
            if response.stop_reason == "tool_use":
                for block in response.content:
                    if block.type == "tool_use":
                        result = await session.call_tool(
                            block.name,
                            arguments=block.input
                        )
                        print(result.content[0].text)

asyncio.run(main())
```

## Environment Variables

```bash theme={null}
STACKONE_API_KEY=<stackone_api_key>
ANTHROPIC_API_KEY=your_anthropic_key
```

## Agent with Tool Calling Loop

For multi-turn conversations with automatic tool execution:

```python theme={null}
async def chat_with_tools(session, user_message: str):
    """Chat with Claude using StackOne tools"""
    client = Anthropic()

    # Get tools from StackOne
    tools_response = await session.list_tools()
    tools = [{
        "name": t.name,
        "description": t.description,
        "input_schema": t.inputSchema
    } for t in tools_response.tools]

    messages = [{"role": "user", "content": user_message}]

    # Tool calling loop
    while True:
        response = client.messages.create(
            model="claude-haiku-4-5-20251001",
            max_tokens=4096,
            tools=tools,
            messages=messages
        )

        if response.stop_reason != "tool_use":
            return response.content[0].text

        # Execute tools
        tool_results = []
        for block in response.content:
            if block.type == "tool_use":
                result = await session.call_tool(block.name, arguments=block.input)
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": result.content[0].text
                })

        messages.append({"role": "assistant", "content": response.content})
        messages.append({"role": "user", "content": tool_results})
```

## Resources

* [MCP Python SDK Documentation](https://github.com/modelcontextprotocol/python-sdk)
* [Anthropic Tool Use Guide](https://docs.anthropic.com/en/docs/tool-use)
* [Anthropic Python SDK](https://docs.anthropic.com/en/api/client-sdks)
* [StackOne Authentication](/mcp/auth-security)

## Next Steps

<CardGroup>
  <Card title="Pydantic AI" icon="robot" href="/mcp/framework-guides/pydantic-ai">
    Try Pydantic AI with built-in MCP support
  </Card>

  <Card title="LangChain" icon="link" href="/mcp/framework-guides/langchain">
    Build agents with LangChain MCP adapters
  </Card>
</CardGroup>


# Azure AI Foundry Agent Service
Source: https://docs.stackone.com/mcp/framework-guides/azure-agents

Connect StackOne MCP to Azure AI Foundry Agent Service with native MCP integration.

## Overview

Azure AI Foundry Agent Service provides native MCP support, allowing agents to connect to StackOne's MCP server for enterprise-grade AI workflows.

[Official Docs](https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/tools/model-context-protocol)

## Prerequisites

* Azure AI Foundry workspace
* Azure OpenAI deployment
* StackOne API credentials

## Quick Start

Connect to StackOne MCP via Azure AI Foundry:

```python theme={null}
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
import os
import base64

# Configure StackOne account
STACKONE_ACCOUNT_ID = "<account_id>"  # Your StackOne account ID

# Encode StackOne API key
auth_token = base64.b64encode(
    f"{os.getenv('STACKONE_API_KEY')}:".encode()
).decode()

# Create Azure AI project client
project_client = AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(),
    conn_str="<your-connection-string>"
)

# Register StackOne MCP server
mcp_connection = project_client.connections.create_or_update(
    connection_name="stackone-mcp",
    properties={
        "connectionType": "MCP",
        "serverUrl": "https://api.stackone.com/mcp",
        "headers": {
            "Authorization": f"Basic {auth_token}",
            "x-account-id": STACKONE_ACCOUNT_ID,
            "Content-Type": "application/json",
            "Accept": "application/json,text/event-stream",
            "MCP-Protocol-Version": "2025-06-18"
        }
    }
)

# Create agent with StackOne MCP tools
agent = project_client.agents.create_agent(
    model="gpt-5",
    name="Platform Data Assistant",
    instructions="You help analyze data from connected platforms",
    tools=[{
        "type": "mcp",
        "mcp_server": "stackone-mcp"
    }]
)

# Create thread and run
thread = project_client.agents.create_thread()
message = project_client.agents.create_message(
    thread_id=thread.id,
    role="user",
    content="List Salesforce accounts"
)

run = project_client.agents.create_and_process_run(
    thread_id=thread.id,
    assistant_id=agent.id
)

print(run.status)
```

## Portal Configuration

You can also configure MCP connections through the Azure AI Foundry portal:

1. Navigate to your AI Foundry workspace
2. Go to **Connections** → **Add Connection**
3. Select **Model Context Protocol (MCP)**
4. Enter StackOne MCP details:
   * **Server URL**: `https://api.stackone.com/mcp`
   * **Headers**: Add authentication headers
   * **Server Label**: `stackone-mcp`

[Learn more in Azure docs](https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/tools/model-context-protocol)

## Environment Variables

```bash theme={null}
STACKONE_API_KEY=<stackone_api_key>
AZURE_OPENAI_ENDPOINT=your_azure_endpoint
AZURE_OPENAI_KEY=your_azure_key
```

## Resources

* [Azure AI Foundry MCP Documentation](https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/tools/model-context-protocol)
* [MCP Code Samples](https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/tools/model-context-protocol-samples)
* [Azure AI Foundry Agent Service](https://learn.microsoft.com/en-us/azure/ai-foundry/agents/)
* [StackOne Authentication](/mcp/auth-security)

## Next Steps

<CardGroup>
  <Card title="OpenAI Agents SDK" icon="robot" href="/mcp/framework-guides/openai-agents-sdk">
    Use OpenAI Agents SDK with Azure OpenAI
  </Card>

  <Card title="Anthropic SDK" icon="message" href="/mcp/framework-guides/anthropic-sdk">
    Build agents with Anthropic SDK
  </Card>
</CardGroup>


# CrewAI
Source: https://docs.stackone.com/mcp/framework-guides/crewai

Connect StackOne MCP to CrewAI with built-in MCP server support.

## Overview

CrewAI includes native MCP integration via the `mcps` parameter on agents, enabling direct connection to StackOne's MCP server using either simple URL strings or structured configuration objects.

[Official Docs](https://docs.crewai.com/en/mcp/overview)

## Installation

```bash theme={null}
pip install crewai
```

Or with uv:

```bash theme={null}
uv add crewai
```

## Quick Start

Connect to StackOne MCP using structured configuration:

```python theme={null}
import os
import base64
from crewai import Agent, Crew, Task
from crewai.mcp import MCPServerHTTP

# Configure StackOne account
STACKONE_ACCOUNT_ID = "<account_id>"  # Your StackOne account ID

# Encode API key for Basic auth
auth_token = base64.b64encode(
    f"{os.getenv('STACKONE_API_KEY')}:".encode()
).decode()

# Create agent with StackOne MCP server
data_agent = Agent(
    role="Platform Data Analyst",
    goal="Analyze data from connected platforms and provide insights",
    backstory="Expert in cross-platform data integration and analysis",
    mcps=[
        MCPServerHTTP(
            url="https://api.stackone.com/mcp",
            headers={
                "Authorization": f"Basic {auth_token}",
                "x-account-id": STACKONE_ACCOUNT_ID
            }
        )
    ]
)

# Create task
analysis_task = Task(
    description="Search recent calls in Gong and summarize key insights",
    agent=data_agent,
    expected_output="A summary of recent call activities and insights"
)

# Create and run crew
crew = Crew(
    agents=[data_agent],
    tasks=[analysis_task]
)

result = crew.kickoff()
print(result)
```

## Environment Variables

```bash theme={null}
STACKONE_API_KEY=<stackone_api_key>
```

## Configuration Options

When using `MCPServerHTTP`, you can configure:

* `url`: The MCP server endpoint
* `headers`: Custom headers for authentication
* `tool_filter`: Optional filter to restrict which tools are available
* `cache_tools_list`: Whether to cache the tool list (default: True)

## Next Steps

<CardGroup>
  <Card title="CrewAI MCP Docs" icon="book" href="https://docs.crewai.com/en/mcp/overview">
    Official CrewAI MCP documentation
  </Card>

  <Card title="StackOne API" icon="grid" href="/platform/introduction">
    Learn about StackOne's Platform API
  </Card>
</CardGroup>


# Google ADK
Source: https://docs.stackone.com/mcp/framework-guides/google-adk

Connect StackOne MCP to Google ADK for building sophisticated AI agents with Gemini models and native MCP support.

## Overview

Google's Agent Development Kit (ADK) is an open-source, code-first Python toolkit for building, evaluating, and deploying AI agents. ADK includes native MCP support via the `McpToolset` class, enabling direct integration with StackOne's MCP server.

[Official Documentation](https://google.github.io/adk-docs/)

## Installation

```bash theme={null}
pip install google-adk
```

Or with uv:

```bash theme={null}
uv add google-adk
```

## Quick Start

Connect to StackOne MCP and create an ADK agent using the Runner pattern:

```python theme={null}
import os
import base64
import asyncio
from google.adk import Runner
from google.adk.agents import LlmAgent
from google.adk.tools.mcp_tool import McpToolset, StreamableHTTPConnectionParams
from google.adk.sessions import InMemorySessionService
from google.genai import types

# Configuration - API keys from environment (secrets)
STACKONE_API_KEY = os.getenv("STACKONE_API_KEY")
os.environ["GOOGLE_API_KEY"] = os.getenv("GOOGLE_API_KEY")

# Encode API key for Basic auth
auth_token = base64.b64encode(f"{STACKONE_API_KEY}:".encode()).decode()

def create_stackone_agent(account_id: str) -> LlmAgent:
    """
    Create an agent for a specific StackOne account.

    In production, account_id should come from:
    - User/tenant context
    - Database lookup based on authenticated user
    - Request parameters
    """
    return LlmAgent(
        model="gemini-2.5-pro",
        name="stackone_assistant",
        instruction="You are a helpful assistant with access to data from connected platforms via StackOne.",
        tools=[
            McpToolset(
                connection_params=StreamableHTTPConnectionParams(
                    url="https://api.stackone.com/mcp",
                    headers={
                        "Authorization": f"Basic {auth_token}",
                        "x-account-id": account_id
                    }
                ),
                tool_name_prefix="stackone_"
            )
        ],
    )

async def main():
    # Get account_id from user context (not environment variable)
    account_id = get_user_account_id()  # Your function to determine this

    # Create agent for this specific account
    agent = create_stackone_agent(account_id)

    # Create runner with in-memory session service
    runner = Runner(
        agent=agent,
        app_name="stackone_demo",
        session_service=InMemorySessionService()
    )

    # Create a session
    await runner.session_service.create_session(
        app_name="stackone_demo",
        user_id="user_1",
        session_id="session_1"
    )

    # Create and send a message
    message = types.Content(parts=[types.Part(text="List workers from Workday, limit 5")], role="user")

    # Run the agent and collect response
    async for event in runner.run_async(
        user_id="user_1",
        session_id="session_1",
        new_message=message
    ):
        if hasattr(event, 'content') and event.content:
            if hasattr(event.content, 'parts'):
                for part in event.content.parts:
                    if hasattr(part, 'text') and part.text:
                        print(part.text)

asyncio.run(main())
```

## Environment Variables

```bash theme={null}
export STACKONE_API_KEY="your_stackone_api_key"
export GOOGLE_API_KEY="your_google_api_key"
```

<Note>
  **Account ID**: The StackOne account ID should be determined from user context (e.g., which tenant/customer is using the agent), not from environment variables. Pass it as a parameter when creating the agent.
</Note>

## Multi-Turn Conversations

Continue conversations by reusing the same session:

```python theme={null}
# First query
message1 = types.Content(parts=[types.Part(text="List 3 workers")], role="user")
async for event in runner.run_async(user_id="user_1", session_id="session_1", new_message=message1):
    # Process first response...
    pass

# Follow-up query (uses same session for context)
message2 = types.Content(parts=[types.Part(text="Show me details for the first worker")], role="user")
async for event in runner.run_async(user_id="user_1", session_id="session_1", new_message=message2):
    # Process follow-up response...
    pass
```

## Tool Filtering

Restrict which StackOne tools are exposed to the agent for security:

```python theme={null}
McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://api.stackone.com/mcp",
        headers={
            "Authorization": f"Basic {auth_token}",
            "x-account-id": account_id
        }
    ),
    tool_filter=[
        "workday_list_workers",
        "workday_get_worker",
        "salesforce_crm_list_accounts"
    ]  # Only expose specific tools
)
```

<Note>
  **Required Headers**: Only `Authorization` and `x-account-id` are required. Additional headers like `Content-Type`, `Accept`, and `MCP-Protocol-Version` are handled automatically by the ADK client.
</Note>

<Note>
  **Class Name Update**: In ADK v1.17.0+, use `McpToolset` (not `MCPToolset`). The old capitalization is deprecated but still works with a warning.
</Note>

## Resources

* [ADK Documentation](https://google.github.io/adk-docs/)
* [MCP Tools Guide](https://google.github.io/adk-docs/tools/mcp-tools/)
* [ADK Authentication](https://google.github.io/adk-docs/tools/authentication/)
* [Gemini API](https://ai.google.dev/gemini-api/docs)
* [StackOne Authentication](/mcp/auth-security)

## Next Steps

<CardGroup>
  <Card title="Pydantic AI" icon="robot" href="/mcp/framework-guides/pydantic-ai">
    Try Pydantic AI for Python agents
  </Card>

  <Card title="Vercel AI SDK" icon="code" href="/mcp/framework-guides/vercel-ai-sdk">
    Build TypeScript agents with Vercel AI
  </Card>
</CardGroup>


# LangChain
Source: https://docs.stackone.com/mcp/framework-guides/langchain

Connect StackOne MCP to LangChain using the MCP adapters package.

## Overview

LangChain provides MCP integration through `langchain-mcp-adapters`, converting MCP tools into LangChain-compatible tools.

[Official Docs](https://langchain-ai.github.io/langgraph/agents/mcp/)

## Installation

```bash theme={null}
uv add langchain langchain-mcp-adapters langchain-openai
```

## Quick Start

Connect to StackOne MCP and use tools in LangChain:

```python theme={null}
import os
import asyncio
import base64
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain_openai import ChatOpenAI
from langchain.prompts import ChatPromptTemplate

# Configure StackOne account
STACKONE_ACCOUNT_ID = "<account_id>"  # Your StackOne account ID

# Encode API key for Basic auth
auth_token = base64.b64encode(
    f"{os.getenv('STACKONE_API_KEY')}:".encode()
).decode()

async def main():
    # Connect to StackOne MCP server
    mcp_client = MultiServerMCPClient({
        "stackone": {
            "url": "https://api.stackone.com/mcp",
            "transport": "streamable_http",
            "headers": {
                "Authorization": f"Basic {auth_token}",
                "x-account-id": STACKONE_ACCOUNT_ID,
                "Content-Type": "application/json",
                "Accept": "application/json,text/event-stream",  # Required by MCP spec
                "MCP-Protocol-Version": "2025-06-18"
            }
        }
    })

    # Get StackOne tools
    tools = await mcp_client.get_tools()

    # Create agent with StackOne tools
llm = ChatOpenAI(model="gpt-5")
    prompt = ChatPromptTemplate.from_messages([
        ("system", "You are a helpful assistant with access to data from connected platforms."),
        ("human", "{input}"),
        ("placeholder", "{agent_scratchpad}")
    ])

    agent = create_tool_calling_agent(llm, tools, prompt)
    agent_executor = AgentExecutor(agent=agent, tools=tools)

    # Run agent
    result = agent_executor.invoke({"input": "List Salesforce accounts"})
    print(result["output"])

asyncio.run(main())
```

## Environment Variables

```bash theme={null}
STACKONE_API_KEY=<stackone_api_key>
OPENAI_API_KEY=your_openai_key
```

## Resources

* [LangChain MCP Adapters](https://changelog.langchain.com/announcements/mcp-adapters-for-langchain-and-langgraph)
* [LangChain Documentation](https://python.langchain.com/docs/get_started/introduction)
* [StackOne Authentication](/mcp/auth-security)

## Next Steps

<CardGroup>
  <Card title="LangGraph" icon="diagram-project" href="/mcp/framework-guides/langgraph">
    Build complex workflows with LangGraph
  </Card>

  <Card title="Pydantic AI" icon="robot" href="/mcp/framework-guides/pydantic-ai">
    Try Pydantic AI with built-in MCP support
  </Card>
</CardGroup>


# LangGraph
Source: https://docs.stackone.com/mcp/framework-guides/langgraph

Connect StackOne MCP to LangGraph for building stateful multi-agent workflows.

## Overview

LangGraph provides both client and server MCP support through `langchain-mcp-adapters`, enabling integration with StackOne's MCP server.

[Official Docs](https://langchain-ai.github.io/langgraph/agents/mcp/)

## Installation

```bash theme={null}
uv add langgraph langchain-mcp-adapters langchain-openai
```

## Quick Start

Connect to StackOne MCP and use tools in LangGraph:

```python theme={null}
import os
import asyncio
import base64
from langgraph.prebuilt import create_react_agent
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain_openai import ChatOpenAI

# Configure StackOne account
STACKONE_ACCOUNT_ID = "<account_id>"  # Your StackOne account ID

# Encode API key for Basic auth
auth_token = base64.b64encode(
    f"{os.getenv('STACKONE_API_KEY')}:".encode()
).decode()

async def main():
    # Connect to StackOne MCP server
    mcp_client = MultiServerMCPClient({
        "stackone": {
            "url": "https://api.stackone.com/mcp",
            "transport": "streamable_http",
            "headers": {
                "Authorization": f"Basic {auth_token}",
                "x-account-id": STACKONE_ACCOUNT_ID,
                "Content-Type": "application/json",
                "Accept": "application/json,text/event-stream",  # Required by MCP spec
                "MCP-Protocol-Version": "2025-06-18"
            }
        }
    })

    # Get StackOne tools
    tools = await mcp_client.get_tools()

    # Create LangGraph agent with StackOne tools
    agent = create_react_agent(
    ChatOpenAI(model="gpt-5"),
        tools=tools,
        state_modifier="You are a helpful assistant with access to data from connected platforms."
    )

    # Run agent
    for chunk in agent.stream({"messages": [("human", "Search recent calls in Gong")]}):
        print(chunk)

asyncio.run(main())
```

## Environment Variables

```bash theme={null}
STACKONE_API_KEY=<stackone_api_key>
OPENAI_API_KEY=your_openai_key
```

## Resources

* [LangGraph MCP Documentation](https://langchain-ai.github.io/langgraph/agents/mcp/)
* [LangGraph Concepts](https://langchain-ai.github.io/langgraph/concepts/mcp/)
* [LangChain MCP Adapters](https://changelog.langchain.com/announcements/mcp-adapters-for-langchain-and-langgraph)
* [StackOne Authentication](/mcp/auth-security)

## Next Steps

<CardGroup>
  <Card title="LangChain" icon="link" href="/mcp/framework-guides/langchain">
    Use MCP with LangChain agents
  </Card>

  <Card title="CrewAI" icon="users" href="/mcp/framework-guides/crewai">
    Build multi-agent systems with CrewAI
  </Card>
</CardGroup>


# OpenAI Agents SDK
Source: https://docs.stackone.com/mcp/framework-guides/openai-agents-sdk

Connect StackOne MCP to OpenAI Agents SDK with built-in MCP server support.

## Overview

OpenAI Agents SDK includes native MCP support with `MCPServerStreamableHttp`, enabling direct integration with StackOne's MCP server.

[Official Docs](https://openai.github.io/openai-agents-python/mcp/)

## Installation

```bash theme={null}
pip install openai-agents
```

Or with uv:

```bash theme={null}
uv add openai-agents
```

## Quick Start

Connect to StackOne MCP and use tools with OpenAI agents:

```python theme={null}
import os
import asyncio
import base64
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp, MCPServerStreamableHttpParams

# Configure StackOne account
STACKONE_ACCOUNT_ID = "<account_id>"  # Your StackOne account ID

# Encode API key for Basic auth
auth_token = base64.b64encode(
    f"{os.getenv('STACKONE_API_KEY')}:".encode()
).decode()

async def main():
    # Create MCP server connection
    stackone_mcp = MCPServerStreamableHttp(
        params=MCPServerStreamableHttpParams(
            url="https://api.stackone.com/mcp",
            headers={
                "Authorization": f"Basic {auth_token}",
                "x-account-id": STACKONE_ACCOUNT_ID
            }
        )
    )

    # Use async context manager to connect/disconnect automatically
    async with stackone_mcp:
        # Create agent with StackOne tools
        agent = Agent(
            name="stackone-assistant",
            model="gpt-5",
            mcp_servers=[stackone_mcp]
        )

        # Run agent
        result = await Runner.run(agent, "List Salesforce accounts")
        print(result.final_output)

asyncio.run(main())
```

## Environment Variables

```bash theme={null}
STACKONE_API_KEY=<stackone_api_key>
OPENAI_API_KEY=your_openai_key
```

## Multi-Turn Conversation

Pass previous messages as context for follow-up questions:

```python theme={null}
import os
import asyncio
import base64
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp, MCPServerStreamableHttpParams

STACKONE_ACCOUNT_ID = "<account_id>"
auth_token = base64.b64encode(
    f"{os.getenv('STACKONE_API_KEY')}:".encode()
).decode()

async def main():
    stackone_mcp = MCPServerStreamableHttp(
        params=MCPServerStreamableHttpParams(
            url="https://api.stackone.com/mcp",
            headers={
                "Authorization": f"Basic {auth_token}",
                "x-account-id": STACKONE_ACCOUNT_ID
            }
        )
    )

    async with stackone_mcp:
        agent = Agent(
            name="stackone-assistant",
            model="gpt-5",
            mcp_servers=[stackone_mcp]
        )

        # First turn
        result = await Runner.run(agent, "List Salesforce accounts")
        print(result.final_output)

        # Continue conversation — pass previous output as context
        result = await Runner.run(
            agent,
            "Show me the most recent account activities",
            context=result.context
        )
        print(result.final_output)

asyncio.run(main())
```

## Resources

* [OpenAI Agents SDK MCP Guide](https://openai.github.io/openai-agents-python/mcp/)
* [OpenAI Agents SDK Documentation](https://openai.github.io/openai-agents-python/)
* [StackOne Authentication](/mcp/auth-security)

## Next Steps

<CardGroup>
  <Card title="Pydantic AI" icon="robot" href="/mcp/framework-guides/pydantic-ai">
    Try Pydantic AI with built-in MCP support
  </Card>

  <Card title="LangChain" icon="link" href="/mcp/framework-guides/langchain">
    Build agents with LangChain MCP adapters
  </Card>
</CardGroup>


# Pydantic AI
Source: https://docs.stackone.com/mcp/framework-guides/pydantic-ai

Connect StackOne MCP to Pydantic AI with built-in MCP server support.

## Overview

Pydantic AI includes native MCP integration via the `mcp_servers` parameter, enabling direct connection to StackOne's MCP server.

[Official Docs](https://ai.pydantic.dev/mcp/client/)

## Installation

```bash theme={null}
uv add pydantic-ai
```

## Quick Start

Connect to StackOne MCP and create an agent:

```python theme={null}
import os
import base64
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStreamableHTTP

# Configure StackOne account
STACKONE_ACCOUNT_ID = "<account_id>"  # Your StackOne account ID

# Encode API key for Basic auth
auth_token = base64.b64encode(
    f"{os.getenv('STACKONE_API_KEY')}:".encode()
).decode()

# Create agent with StackOne MCP server
agent = Agent(
    model="openai:gpt-5",
    mcp_servers=[
        MCPServerStreamableHTTP(
            url="https://api.stackone.com/mcp",
            headers={
                "Authorization": f"Basic {auth_token}",
                "x-account-id": STACKONE_ACCOUNT_ID
            }
        )
    ]
)

# Run agent with StackOne tools
result = agent.run_sync("Search recent calls in Gong")
print(result.data)
```

## Environment Variables

```bash theme={null}
STACKONE_API_KEY=<stackone_api_key>
OPENAI_API_KEY=your_openai_key
```

## With Tool Prefix

Avoid naming conflicts when using multiple MCP servers:

```python theme={null}
agent = Agent(
    model="openai:gpt-5",
    mcp_servers=[
        MCPServerStreamableHTTP(
            url="https://api.stackone.com/mcp",
            headers={
                "Authorization": f"Basic {auth_token}",
                "x-account-id": STACKONE_ACCOUNT_ID
            },
            tool_prefix="stackone_"  # Tools become stackone_gong_crm_search_calls, etc.
        )
    ]
)
```

## Resources

* [Pydantic AI MCP Client Documentation](https://ai.pydantic.dev/mcp/client/)
* [Pydantic AI Documentation](https://ai.pydantic.dev/)
* [StackOne Authentication](/mcp/auth-security)

## Next Steps

<CardGroup>
  <Card title="LangChain" icon="link" href="/mcp/framework-guides/langchain">
    Build agents with LangChain MCP adapters
  </Card>

  <Card title="CrewAI" icon="users" href="/mcp/framework-guides/crewai">
    Create multi-agent systems with CrewAI
  </Card>
</CardGroup>


# Vercel AI SDK
Source: https://docs.stackone.com/mcp/framework-guides/vercel-ai-sdk

Connect StackOne MCP to Vercel AI SDK for TypeScript/JavaScript applications with native MCP client support.

## Overview

Vercel AI SDK v4.2+ includes native MCP support via `experimental_createMCPClient`, enabling direct integration with StackOne's MCP server.

[Official Docs](https://ai-sdk.dev/docs/reference/ai-sdk-core/create-mcp-client)

## Installation

```bash theme={null}
npm install ai @ai-sdk/openai
```

## Quick Start

Connect to StackOne MCP and use tools in your Next.js/Node.js app:

```typescript theme={null}
import { anthropic } from "@ai-sdk/anthropic";
import { generateText, stepCountIs } from "ai";
import { experimental_createMCPClient } from "@ai-sdk/mcp";

// Connect to StackOne MCP server
const mcp = await experimental_createMCPClient({
	transport: {
		type: "http",
		url: "https://api.stackone.com/mcp",
		headers: {
			Authorization: `Basic ${Buffer.from(`${process.env.STACKONE_API_KEY}:`).toString("base64")}`,
			"x-account-id": "<stackone_account_id>",
		},
	},
});

// Get StackOne tools
const tools = await mcp.tools();

// Use with any AI SDK provider
const result = await generateText({
	model: anthropic("claude-haiku-4-5-20251001"),
	tools,
	prompt: "List all employees", // update the prompt based on what you want your agent to do
	stopWhen: stepCountIs(2),
});

console.log(result.text);
```

## Environment Variables

```bash theme={null}
STACKONE_API_KEY=<stackone_api_key>
```

## Resources

* [Vercel AI SDK MCP Documentation](https://ai-sdk.dev/docs/reference/ai-sdk-core/create-mcp-client)
* [Vercel AI SDK Core Docs](https://ai-sdk.dev/docs/ai-sdk-core)
* [MCP Cookbook](https://ai-sdk.dev/cookbook/node/mcp-tools)
* [StackOne Authentication](/mcp/auth-security)

## Next Steps

<CardGroup>
  <Card title="OpenAI Agents SDK" icon="robot" href="/mcp/framework-guides/openai-agents-sdk">
    Use MCP with OpenAI Agents SDK
  </Card>

  <Card title="Pydantic AI" icon="python" href="/mcp/framework-guides/pydantic-ai">
    Build Python agents with Pydantic AI
  </Card>
</CardGroup>


# StackOne MCPs
Source: https://docs.stackone.com/mcp/quickstart

Connect all StackOne platform actions directly to LLM clients and agents via the Model Context Protocol

The **[Model Context Protocol (MCP)](https://modelcontextprotocol.io)** is an open protocol that standardizes how AI applications provide context to LLMs.

StackOne provides **production-ready MCP servers** for each linked account, giving your AI agents direct access to 10,000+ actions across hundreds of integrations. See the complete list at [stackone.com/integrations](https://www.stackone.com/integrations).

<Tip>
  **Not sure if MCP is right for you?** Check out our [Agent Protocols Guide](/guides/calling-stackone-actions) to understand when to use MCP vs AI Toolset (SDK) vs A2A.
</Tip>

***

## MCP Server Endpoint

```
https://api.stackone.com/mcp
```

**Required headers:**

* `Authorization: Basic <base64-encoded-api-key>`
* `x-account-id: <account-id>` (or `?x-account-id=` query param)

Authentication to third-party providers is completely abstracted - you only need your StackOne API key and account ID. Accounts must be linked beforehand through the [StackOne Hub](/guides/embedding-stackone-hub) or via [auth links](/guides/auth-link).

***

## Fastest Way to Test

<CardGroup>
  <Card title="AI Playground" icon="play" href="https://app.stackone.com/playground">
    No setup. Test with natural language instantly
  </Card>

  <Card title="Postman" icon="https://mintcdn.com/stackone-60/ukzqjoO9pVfH9ilh/images/mcp/logos/postman.svg?fit=max&auto=format&n=ukzqjoO9pVfH9ilh&q=85&s=b5d9867a85829951d3e50f703021c8a8" href="/mcp/app-guides/postman">
    Fork the StackOne collection and test MCP requests
  </Card>

  <Card title="MCP Inspector" icon="magnifying-glass">
    Run `npx @modelcontextprotocol/inspector https://api.stackone.com/mcp`
  </Card>
</CardGroup>

***

## How It Works

```mermaid theme={null}
flowchart LR
    Client[LLM Client or Agent] <-->|MCP Streamable HTTP| StackOneMCP[StackOne MCP Server]
    StackOneMCP <-->|tools/list| Toolset[StackOne Tool Catalog]
    StackOneMCP <-->|tools/call| Providers[(Connected SaaS APIs)]
    IntegrationConfig[Integration & Account Settings] -->|Defines available tools| Toolset

    style StackOneMCP fill:#10b981,stroke:#059669,color:#fff
    style Toolset fill:#10b981,stroke:#059669,color:#fff
    style IntegrationConfig fill:#10b981,stroke:#059669,color:#fff
```

The StackOne MCP Server dynamically generates its tool catalog based on your account's configured integrations and enabled actions.

<AccordionGroup>
  <Accordion title="Multiple Integration Options" icon="plug">
    Use the MCP server, the [Actions RPC endpoint](/platform/api-reference/actions/make-an-rpc-call-to-an-action), the [Unified API endpoints](/hris/introduction), or [A2A Agents](/a2a/introduction), all using the same linked account. You can also access the [StackOne AI Toolset](/agents/typescript/introduction) for specialized LLM tools.
  </Accordion>

  <Accordion title="Accuracy & Context Engineering" icon="brain">
    Enhance your agent's toolset with [Tool Search](/agents/typescript/tool-search) for natural language discovery of relevant tools. Every tool has structured input/output schemas and documentation.
  </Accordion>

  <Accordion title="Customizable & Extensible" icon="gear">
    Toggle tools on or off, customize your toolset, or create your own connectors using StackOne's Connector Engine and StackOne Agent.
  </Accordion>

  <Accordion title="Purposeful Action Design" icon="bullseye">
    StackOne tools aren't direct wrappers to single API endpoints. Many are mapped to high-value, context-optimized actions tailored to common business use cases.
  </Accordion>
</AccordionGroup>

***

## Framework Guides

Most frameworks support MCP natively:

<CardGroup>
  <Card title="Claude SDK" icon="message" href="/mcp/framework-guides/anthropic-sdk" />

  <Card title="Vercel AI SDK" icon="triangle" href="/mcp/framework-guides/vercel-ai-sdk" />

  <Card title="OpenAI Agents" icon="brain" href="/mcp/framework-guides/openai-agents-sdk" />

  <Card title="Pydantic AI" icon="python" href="/mcp/framework-guides/pydantic-ai" />

  <Card title="CrewAI" icon="users" href="/mcp/framework-guides/crewai" />

  <Card title="Google ADK" icon="google" href="/mcp/framework-guides/google-adk" />
</CardGroup>

***

## App Guides

<CardGroup>
  <Card title="Claude Desktop" icon="https://mintcdn.com/stackone-60/WsmKpuoeBZmio9QO/images/mcp/logos/claude.svg?fit=max&auto=format&n=WsmKpuoeBZmio9QO&q=85&s=404b448b2b3013a55ecf71943aec656f" href="/mcp/app-guides/claude-desktop" />

  <Card title="Goose" icon="https://mintcdn.com/stackone-60/3C44zDmMwMrJMHXV/images/mcp/logos/goose.png?fit=max&auto=format&n=3C44zDmMwMrJMHXV&q=85&s=09f6d6d96f9aae06c5841d23908946a8" href="/mcp/app-guides/goose" />

  <Card title="n8n" icon="https://mintcdn.com/stackone-60/3C44zDmMwMrJMHXV/images/mcp/logos/n8n.png?fit=max&auto=format&n=3C44zDmMwMrJMHXV&q=85&s=9364b633ee3073731b7a7b3d569a2b8a" href="/mcp/app-guides/n8n" />

  <Card title="Postman" icon="https://mintcdn.com/stackone-60/ukzqjoO9pVfH9ilh/images/mcp/logos/postman.svg?fit=max&auto=format&n=ukzqjoO9pVfH9ilh&q=85&s=b5d9867a85829951d3e50f703021c8a8" href="/mcp/app-guides/postman" />
</CardGroup>

***

## Manual Testing (cURL)

<AccordionGroup>
  <Accordion title="Initialize connection">
    ```bash theme={null}
    curl -X POST https://api.stackone.com/mcp \
      -H 'Authorization: Basic <BASE64_APIKEY_COLON>' \
      -H 'x-account-id: <ACCOUNT_ID>' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json, text/event-stream' \
      -d '{
        "jsonrpc": "2.0",
        "id": "init-1",
        "method": "initialize",
        "params": {
          "clientInfo": { "name": "my-client", "version": "1.0.0" },
          "protocolVersion": "2025-06-18",
          "capabilities": {}
        }
      }'
    ```
  </Accordion>

  <Accordion title="List available tools">
    ```bash theme={null}
    curl -X POST https://api.stackone.com/mcp \
      -H 'Authorization: Basic <BASE64_APIKEY_COLON>' \
      -H 'x-account-id: <ACCOUNT_ID>' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json, text/event-stream' \
      -d '{
        "jsonrpc": "2.0",
        "id": "tools-1",
        "method": "tools/list"
      }'
    ```
  </Accordion>

  <Accordion title="Call a tool">
    ```bash theme={null}
    curl -X POST https://api.stackone.com/mcp \
      -H 'Authorization: Basic <BASE64_APIKEY_COLON>' \
      -H 'x-account-id: <ACCOUNT_ID>' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json, text/event-stream' \
      -d '{
        "jsonrpc": "2.0",
        "id": "call-1",
        "method": "tools/call",
        "params": {
          "name": "bamboohr_list_employees",
          "arguments": { "limit": 10 }
        }
      }'
    ```
  </Accordion>
</AccordionGroup>

***

## Tool Modes

The MCP endpoint supports a `tool-mode` query parameter that controls how tools are registered.

| Mode                   | Tools registered          | When to use                                |
| ---------------------- | ------------------------- | ------------------------------------------ |
| `individual` (default) | One tool per action       | Small action sets, full tool visibility    |
| `search_execute`       | 2 tools: search + execute | Large catalogs, context window constraints |

**Search & execute mode** is useful when an integration exposes many actions. Instead of registering hundreds of individual tools, the server exposes just two:

* `{provider}_search_actions` — search for actions by natural language query
* `{provider}_execute_action` — execute an action by its `action_id`

The agent calls `search_actions` first to discover available action IDs, then calls `execute_action` to run the chosen action.

Enable it by appending `?tool-mode=search_execute` to the MCP URL:

```
https://api.stackone.com/mcp?tool-mode=search_execute
```

See [Tool Modes](/mcp/tool-modes) for full details, parameter reference, and setup examples for Claude Desktop and Claude Code.

***

## Key Features

* **Account Specific**: Each linked account gets its own MCP server endpoint
* **Streamable HTTP Transport**: Uses modern HTTP-based MCP transport (not SSE)
* **Complete Platform Access**: All StackOne actions available as MCP tools
* **Action Selection Control**: Only enabled actions from your integration config are returned
* **Production Ready**: Authentication, rate limiting, and security built-in

***

## Troubleshooting

| Error            | Solution                                                                   |
| ---------------- | -------------------------------------------------------------------------- |
| `401/403`        | Check API key encoding and that `x-account-id` belongs to the same project |
| `405`            | Ensure you're using POST and `Content-Type: application/json`              |
| Empty tools list | Verify account is active and actions are enabled in integration config     |

For more, see [Troubleshooting Guide](/mcp/troubleshooting) and [Authentication & Security](/mcp/auth-security).


# Tool Modes
Source: https://docs.stackone.com/mcp/tool-modes

Control how StackOne MCP registers tools — individual actions or search-and-execute for reduced context footprint.

## Overview

The StackOne MCP endpoint supports two tool registration modes controlled by the `tool-mode` query parameter:

| Mode                   | Tools registered          | Best for                                                |
| ---------------------- | ------------------------- | ------------------------------------------------------- |
| `individual` (default) | One tool per action       | Agents with a small action set, or full tool visibility |
| `search_execute`       | 2 tools: search + execute | Large catalogs, context window constraints              |

***

## Individual Mode (Default)

When `tool-mode` is omitted or set to `individual`, StackOne registers each enabled action as its own MCP tool (e.g., `bamboohr_list_employees`, `ashby_list_jobs`).

This is the right choice when:

* Your integration config has a small, focused action set
* You want the LLM to see every available tool upfront
* Your MCP client supports large tool lists without performance degradation

***

## Search & Execute Mode

```
https://api.stackone.com/mcp?tool-mode=search_execute&x-account-id=<ACCOUNT_ID>
```

Instead of registering one tool per action, `search_execute` mode exposes exactly **two tools**:

| Tool                        | Description                                                                                                                  |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `{provider}_search_actions` | Takes a natural language query and returns ranked matching actions with their `action_id`, description, and similarity score |
| `{provider}_execute_action` | Executes any action by its `action_id`                                                                                       |

For example, for a BambooHR account the tools would be `bamboohr_search_actions` and `bamboohr_execute_action`.

### Why use this mode?

A typical integration exposes hundreds of actions. Sending every tool definition to the LLM on every request:

* Consumes significant context window tokens
* Can slow down tool listing in the client
* May exceed context limits for models with smaller windows

Search & execute mode keeps the token footprint constant (two tools) regardless of how many actions the integration supports. The agent first calls `search_actions` with a natural language description of what it wants to do, then calls `execute_action` with the returned `action_id`.

### How the agent flow works

```
1. Agent calls {provider}_search_actions(query="list all employees with their departments")
   → Returns: [{ action_id: "list_employees", description: "...", score: 0.94 }, ...]

2. Agent calls {provider}_execute_action(action_id="list_employees", query={ include: "department" })
   → Returns: employee records from the provider
```

The search tool accepts:

* `query` (required) — natural language description of the task
* `top_k` (optional, default 10, max 50) — number of results to return

The execute tool accepts:

* `action_id` (required) — the `action_id` returned by the search tool
* `path` (optional) — path parameters (e.g. `{ "id": "emp_123" }` for a get-by-id action)
* `query` (optional) — query parameters (filters, pagination, etc.)
* `body` (optional) — request body for create/update actions
* `headers` (optional) — additional HTTP headers

<Warning>
  The agent **must** call `search_actions` first to discover valid `action_id` values before calling `execute_action`. Do not assume or hardcode action IDs — they are discovered at runtime based on what is enabled for your account.
</Warning>

### Example: Enable in Claude Desktop

Add `?tool-mode=search_execute` to the MCP URL in your client config:

```json theme={null}
{
  "mcpServers": {
    "stackone-bamboohr": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://api.stackone.com/mcp?tool-mode=search_execute",
        "--header",
        "Authorization: Basic <BASE64_APIKEY_COLON>",
        "--header",
        "x-account-id: <ACCOUNT_ID>"
      ]
    }
  }
}
```

### Example: Enable in Claude Code

```bash theme={null}
BASE64_KEY=$(echo -n 'YOUR_STACKONE_API_KEY:' | base64 | tr -d '\n')

claude mcp add stackone-bamboohr -- npx -y mcp-remote@latest \
  "https://api.stackone.com/mcp?tool-mode=search_execute" \
  --header "Authorization: Basic $BASE64_KEY" \
  --header "x-account-id: YOUR_ACCOUNT_ID"
```

### Example: Enable via direct HTTP

```bash theme={null}
curl -X POST "https://api.stackone.com/mcp?tool-mode=search_execute" \
  -H "Authorization: Basic <BASE64_APIKEY_COLON>" \
  -H "x-account-id: <ACCOUNT_ID>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":"tools-1","method":"tools/list"}'
```

***

## Combining with Param Style

`tool-mode` can be combined with the `param-style` query parameter to control how tool input schemas are structured:

| `param-style` value | Schema structure                                                    |
| ------------------- | ------------------------------------------------------------------- |
| `nested` (default)  | Parameters grouped into `path`, `query`, `body`, `headers` objects  |
| `flat_smart`        | All parameters at the top level; conflicts resolved automatically   |
| `flat_root`         | All parameters at the top level; any conflicting names are prefixed |

```
https://api.stackone.com/mcp?tool-mode=search_execute&param-style=flat_smart
```

Both parameters are independent — you can use either, both, or neither.

***

## Choosing the Right Mode

| Scenario                                                           | Recommended mode                          |
| ------------------------------------------------------------------ | ----------------------------------------- |
| Small action set (\< 50 tools)                                     | `individual`                              |
| Large integration with many actions                                | `search_execute`                          |
| Model with limited context window                                  | `search_execute`                          |
| Agent needs to see all tools explicitly                            | `individual`                              |
| Multi-account management via the [Management MCP](/mcp/quickstart) | `individual` (management tools are fixed) |

<Tip>
  Search & execute mode uses semantic search over your enabled actions. For best results, write queries that describe the business task rather than the technical operation — e.g., "find employees hired this year" rather than "list employees filtered by start date".
</Tip>


# Troubleshooting
Source: https://docs.stackone.com/mcp/troubleshooting

Common issues, error messages, and solutions for StackOne MCP integration across different clients and frameworks.

## Common Issues

### Connection Problems

<AccordionGroup>
  <Accordion title="Authentication Error">
    **Symptoms:**

    ```json theme={null}
    {
      "error": "Invalid authentication token"
    }
    ```

    **Likely Causes:**

    * Incorrect API key
    * Wrong base64 encoding
    * Expired or disabled API key

    **Solutions:**

    1. **Verify API key encoding (include colon!):**
       ```bash theme={null}
       echo -n "<stackone_api_key>" | base64
       ```

    2. **Test with cURL:**
       ```bash theme={null}
       curl -X POST https://api.stackone.com/mcp \
         -H 'Authorization: Basic <BASE64_TOKEN>' \
         -H 'x-account-id: <ACCOUNT_ID>' \
         -H 'Content-Type: application/json' \
         -H 'Accept: application/json,text/event-stream' \
         -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"clientInfo":{"name":"test","version":"1.0.0"},"protocolVersion":"2025-06-18","capabilities":{}}}'
       ```

    3. **Check account ID format:**
       * Numeric string (e.g., `47187425466113776871`)
       * Or short alphanumeric ID (nano ID)
       * Must have been initially created in the Stackone Dashboard

    4. **Verify API key permissions:**
       * Ensure key has access to required scopes
  </Accordion>

  <Accordion title="Wrong HTTP Method">
    **Symptoms:**

    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "error": {
        "code": -32000,
        "message": "Only POST is supported for stateless MCP."
      },
      "id": null
    }
    ```

    **Likely Causes:**

    * Using GET instead of POST
    * Incorrect HTTP method

    **Solutions:**

    1. **Always use POST method:**
       ```javascript theme={null}
       fetch('https://api.stackone.com/mcp', {
         method: 'POST',  // Always POST
         headers: { /* ... */ },
         body: JSON.stringify({ /* ... */ })
       })
       ```

    2. **Check endpoint URL:**
       * Must be exactly `https://api.stackone.com/mcp`
       * No trailing slashes or additional paths

    3. **Include required headers:**
       ```http theme={null}
       Content-Type: application/json
       Accept: application/json,text/event-stream
       ```
  </Accordion>

  <Accordion title="Missing x-account-id Header">
    **Symptoms:**

    ```json theme={null}
    {
      "statusCode": 400,
      "message": "Missing x-account-id header in request",
      "timestamp": "2025-10-27T23:20:13.335Z"
    }
    ```

    **Likely Causes:**

    * Client doesn't support custom headers
    * Header not configured correctly
    * MCP client limitations
  </Accordion>
</AccordionGroup>

### Tool Execution Issues

<AccordionGroup>
  <Accordion title="Tools List Empty">
    **Symptoms:**

    * `tools/list` returns empty array
    * MCP server connects but no tools available
    * Client shows "No tools found"

    **Likely Causes:**

    * Account's integration configuration is incorrect or does not have any actions enabled
    * Account configuration issues

    **Solutions:**

    1. **Check integrations in StackOne dashboard:**
       * Verify the account ID is correct and is active
       * Ensure the associated integrations configuration has at least 1 action enabled

    2. **Verify list of accounts:**
       ```bash theme={null}
       curl https://api.stackone.com/accounts \
         -u "$STACKONE_API_KEY:"
       ```

    3. **Test specific operations:**
       ```bash theme={null}
       curl https://api.stackone.com/unified/hris/employees \
         -u "$STACKONE_API_KEY:" \
         -H 'x-account-id: <ACCOUNT_ID>'
       ```
  </Accordion>

  <Accordion title="Tool Execution Fails">
    **Symptoms:**

    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "error": {
        "code": -32603,
        "message": "Tool execution failed"
      }
    }
    ```

    **Likely Causes:**

    * Invalid tool parameters
    * Provider connection issues
    * Rate limiting
    * Provider-specific errors

    **Solutions:**

    1. **Validate parameters:**

    2. **Check rate limits:**
       * Monitor X-RateLimit headers in responses
       * Implement exponential backoff
       * Reduce request frequency

    3. **Test provider connection:**
       ```bash theme={null}
       # Test underlying API action via RPC
       curl -X POST https://api.stackone.com/actions/rpc \
         -u "$STACKONE_API_KEY:" \
         -H 'x-account-id: <ACCOUNT_ID>' \
         -H 'Content-Type: application/json' \
         -d '{
           "action": "<provider_action_name>",
           "query": {}
         }'
       ```
  </Accordion>
</AccordionGroup>

## Error Code Reference

### MCP Protocol Errors

| Code   | Message          | Cause             | Solution                     |
| ------ | ---------------- | ----------------- | ---------------------------- |
| -32700 | Parse error      | Invalid JSON      | Check JSON syntax            |
| -32600 | Invalid Request  | Malformed request | Verify request structure     |
| -32601 | Method not found | Unknown method    | Check method name spelling   |
| -32602 | Invalid params   | Wrong parameters  | Validate parameter schema    |
| -32603 | Internal error   | Server error      | Check StackOne status, retry |

### StackOne API Errors

For comprehensive error code information, see our [Unified API Error Codes and Troubleshooting Guide](/guides/unified-api-error-codes-and-troubleshooting-guide).

### Network Diagnostics

```bash theme={null}
# Test connectivity
curl -I https://api.stackone.com/mcp

# Check DNS resolution
nslookup api.stackone.com

# Test authentication
curl https://api.stackone.com/accounts \
  -u "$STACKONE_API_KEY:"
```

## Next Steps

<CardGroup>
  <Card title="Status Page" icon="signal" href="https://status.stackone.com">
    Check system status and incidents
  </Card>

  <Card title="FAQ" icon="question" href="/mcp/faq">
    Find answers to common questions
  </Card>

  <Card title="Go Back to Guides" icon="arrow-left" href="/mcp/">
    Return to MCP documentation
  </Card>
</CardGroup>


# Check Permissions
Source: https://docs.stackone.com/permissions-check/api-reference/check-permissions

Check whether a user can access a specific resource and, optionally, whether a specific action is allowed.

```
POST /unified/check_permissions
```

Checks a user's permissions on a specific resource. Returns the permissions they hold and, if you specify an `action`, whether that action is allowed.

## Authentication

Requires `Authorization: Basic {base64_encoded_api_key}` and `x-account-id: {account_id}`. See [authentication](/iam/common-guide/basic-authentication-with-stackone-api).

## Request Body

| Field         | Type   | Required    | Description                                                                                                                  |
| ------------- | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `user_id`     | string | Conditional | Provider user ID. At least one of `user_id` or `email` is required. When both are provided, `user_id` takes priority.        |
| `email`       | string | Conditional | User's email address. If `user_id` is absent, the connector resolves the email to a user ID internally.                      |
| `resource_id` | string | **Yes**     | The resource to check. Accepts a StackOne composite ID (starts with `c28xIQ`) or a plain provider-native ID.                 |
| `action`      | string | No          | The action to check. One of: `read`, `write`, `comment`, `delete`, `export`. When provided, the response includes `allowed`. |

<Note>
  At least one of user\_id or email must be present. Omitting both returns a 400 error.
</Note>

### Resource ID formats

The `resource_id` field accepts two formats:

**Composite ID** (starts with `c28xIQ`): A StackOne-encoded ID that embeds the provider resource ID and optional resource type. The service decodes it automatically.

**Plain provider ID**: Any other string is treated as a native provider resource ID and passed through as-is. The connector uses its default resource type for the check. Use [List Resource Types](/permissions-check/api-reference/list-resource-types) to discover valid types.

## Response

| Field              | Type      | Present                        | Description                                                                                                                                   |
| ------------------ | --------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `user.id`          | string    | Always                         | The resolved provider user ID                                                                                                                 |
| `user.permissions` | string\[] | Always                         | Permissions the user holds on this resource: subset of `read`, `write`, `comment`, `delete`, `export`. Empty array if the user has no access. |
| `resource.type`    | string    | Always                         | The resolved resource type                                                                                                                    |
| `resource.id`      | string    | Always                         | The decoded provider resource ID                                                                                                              |
| `action`           | string    | Only if requested              | Echoes back the `action` from the request                                                                                                     |
| `allowed`          | boolean   | Only if `action` was requested | `true` if the requested action is in `user.permissions`                                                                                       |

## Examples

<Tabs>
  <Tab title="Read check">
    ```bash theme={null}
    curl --request POST \
      --url 'https://api.stackone.com/unified/check_permissions' \
      --header 'authorization: Basic {base64_encoded_api_key}' \
      --header 'content-type: application/json' \
      --header 'x-account-id: {account_id}' \
      --data '{
        "user_id": "U08FW4R4N6S",
        "resource_id": "c28xIQcnQ6Y2hhbm5lbCxpZDpDMDhHNlFCOTBMVQ==",
        "action": "read"
      }'
    ```

    ```json theme={null}
    {
      "user": { "id": "U08FW4R4N6S", "permissions": ["read", "write", "comment"] },
      "resource": { "type": "channel", "id": "C08G6QB90LU" },
      "action": "read",
      "allowed": true
    }
    ```
  </Tab>

  <Tab title="Permission summary (no action)">
    ```bash theme={null}
    curl --request POST \
      --url 'https://api.stackone.com/unified/check_permissions' \
      --header 'authorization: Basic {base64_encoded_api_key}' \
      --header 'content-type: application/json' \
      --header 'x-account-id: {account_id}' \
      --data '{
        "email": "alice@company.com",
        "resource_id": "c28xIQaWQ6MWRhYjN..."
      }'
    ```

    ```json theme={null}
    {
      "user": { "id": "U08FW4R4N6S", "permissions": ["read"] },
      "resource": { "type": "folder", "id": "1dab3..." }
    }
    ```

    No `action` sent — no `allowed` field in response.
  </Tab>

  <Tab title="No access">
    ```json theme={null}
    {
      "user": { "id": "U08FW4R4N6S", "permissions": [] },
      "resource": { "type": "channel", "id": "C08G6QB90LU" },
      "action": "write",
      "allowed": false
    }
    ```

    A `200` response with empty permissions — not an error.
  </Tab>
</Tabs>

## Permission types

<Note>
  These action values differ from the IamPermissionTypeEnum used in the IAM entity model. The IAM enum also includes create and edit, which are not applicable for resource-level permission checks.
</Note>

The unified permission model normalizes provider-native roles to five action types:

| Type      | Description                             |
| --------- | --------------------------------------- |
| `read`    | View the resource and its content       |
| `write`   | Modify the resource                     |
| `comment` | Add comments or annotations             |
| `delete`  | Remove the resource                     |
| `export`  | Download or export the resource content |

Which permissions are granted for a given provider role depends on the integration. See the connector's integration guide for how this provider's roles map to these types.

## Error codes

| Status | Condition                                                                                 |
| ------ | ----------------------------------------------------------------------------------------- |
| 400    | Missing `resource_id`, missing both `user_id` and `email`, or invalid `action` enum value |
| 401    | Invalid API key                                                                           |
| 404    | User not found (email resolution failed) or resource not found                            |
| 422    | The connected provider does not support `check_permissions`                               |
| 429    | Provider rate limit reached — retry with backoff                                          |
| 502    | Provider API error                                                                        |

## Edge cases

| Situation                           | Behavior                                                                              |
| ----------------------------------- | ------------------------------------------------------------------------------------- |
| User has no access to the resource  | `200` with `user.permissions: []` and, when an `action` is provided, `allowed: false` |
| Deactivated or suspended user       | `200` with `user.permissions: []` — provider semantics preserved                      |
| Resource not found                  | `404` with `"resource not found"`                                                     |
| User not found (email resolution)   | `404` with `"user not found"`                                                         |
| Both `user_id` and `email` provided | `user_id` is used; `email` is ignored                                                 |
| `action` is not in the enum         | `400` validation error                                                                |


# List Resource Types
Source: https://docs.stackone.com/permissions-check/api-reference/list-resource-types

Returns the resource types supported by the connected provider for permission checks.

```
GET /unified/list_resource_types
```

Returns a list of resource type identifiers that the connected provider supports for [Check Permissions](/permissions-check/api-reference/check-permissions) calls. Use these values as the `resource_type` component when constructing resource IDs, or to understand what types of resources you can check permissions for.

<Note>
  This endpoint is distinct from `GET /unified/iam/resource_types` in the [IAM section](/iam/api-reference/resource-types/list-resource-types). That endpoint returns types for IAM resource-scoped user queries; this one returns types for permission checks. The valid values may overlap but serve different purposes.
</Note>

No provider API call is made — the response is a static list declared by the connector.

## Authentication

Requires `Authorization: Basic {base64_encoded_api_key}` and `x-account-id: {account_id}`. See [authentication](/iam/common-guide/basic-authentication-with-stackone-api).

## Response

Returns an object with a `data: string[]` field containing resource type identifiers. Pass the values in `data` as the `resource_type` component in a composite resource ID, or use them to understand which types can be checked.

Common values: `file`, `folder`, `drive`, `channel`, `workspace`, `message`, `page`.

## Example

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl --request GET \
      --url 'https://api.stackone.com/unified/list_resource_types' \
      --header 'accept: application/json' \
      --header 'authorization: Basic {base64_encoded_api_key}' \
      --header 'x-account-id: {account_id}'
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { StackOne } from "@stackone/stackone-client-ts";

    const client = new StackOne({ apiKey: "v1.eu1.xxxxx" });

    const response = await client.listResourceTypes({
      xAccountId: "your-account-id",
    });

    console.log(response.resourceTypes);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from stackone_client import StackOne

    client = StackOne(api_key="v1.eu1.xxxxx")

    response = client.list_resource_types(
        x_account_id="your-account-id"
    )

    print(response.resource_types)
    ```
  </Tab>
</Tabs>

### Example Response

```json theme={null}
{
  "data": ["file", "folder", "drive"]
}
```

The exact values depend on the connected provider. See the connector's integration guide for the full list.

## Errors

| Status | Meaning                                   |
| ------ | ----------------------------------------- |
| 401    | Unauthorized — invalid or missing API key |
| 422    | Provider does not support this endpoint   |


# Making your first request
Source: https://docs.stackone.com/permissions-check/first-request

Make your first check_permissions call to verify a user can access a resource.

## Prerequisites

1. [**API Key created in StackOne Dashboard**](/guides/api-keys) and copied to a secure location

2. [**Basic Authentication Setup**](/basic-authentication-with-stackone-api) - Learn how to properly authenticate with StackOne API using your API key

3. Required provider integration enabled

4. Account linked successfully

5. (Optional) Use an [SDK or Postman](/guides/stackone-api-sdks)

## Getting Account ID

<Note>
  **Authentication**: When using `curl -u "$API_KEY:"`, encoding is handled automatically. When setting the `Authorization` header manually, you must base64 encode your API key first. See the [Basic Authentication Guide](/basic-authentication-with-stackone-api) for details.
</Note>

1. List your linked accounts to find the account ID:

```bash theme={null}
curl --request GET \
     --url https://api.stackone.com/accounts \
     --header 'accept: application/json' \
     --header 'authorization: Basic {base64_encoded_api_key}'
```

2. From the response, copy the `id` value for your desired provider account.

<Tip>
  Filter by provider using the `providers` query parameter:

  ```bash theme={null}
  curl --request GET \
       --url 'https://api.stackone.com/accounts?providers={provider_name}' \
       --header 'accept: application/json' \
       --header 'authorization: Basic {base64_encoded_api_key}'
  ```
</Tip>

## Making your first request

Check whether a user can read a specific resource. Replace the placeholder values with your own account ID, user identifier, and resource ID.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl --request POST \
      --url 'https://api.stackone.com/unified/check_permissions' \
      --header 'accept: application/json' \
      --header 'authorization: Basic {base64_encoded_api_key}' \
      --header 'content-type: application/json' \
      --header 'x-account-id: {account_id}' \
      --data '{
        "user_id": "{provider_user_id}",
        "resource_id": "{resource_id}",
        "action": "read"
      }'
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { StackOne } from "@stackone/stackone-client-ts";

    const client = new StackOne({ apiKey: "v1.eu1.xxxxx" });

    const response = await client.checkPermissions({
      xAccountId: "your-account-id",
      userId: "provider-user-id",
      resourceId: "resource-id",
      action: "read",
    });

    console.log(response.allowed); // true or false
    console.log(response.user.permissions); // ["read", "write", ...]
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from stackone_client import StackOne

    client = StackOne(api_key="v1.eu1.xxxxx")

    response = client.check_permissions(
        x_account_id="your-account-id",
        user_id="provider-user-id",
        resource_id="resource-id",
        action="read"
    )

    print(response.allowed)
    print(response.user.permissions)
    ```
  </Tab>
</Tabs>

### Example response

```json theme={null}
{
  "user": {
    "id": "U08FW4R4N6S",
    "permissions": ["read", "write", "comment"]
  },
  "resource": {
    "type": "file",
    "id": "1xF7abc123"
  },
  "action": "read",
  "allowed": true
}
```

## Reading the response

* **`user.permissions`** — the full set of permissions this user holds on the resource. Always present.
* **`allowed`** — only present when you sent an `action`. `true` if the action is in `user.permissions`.
* **`resource.type`** — the resolved resource type used for the check.

## When `allowed` is false

When the user doesn't have access, the response returns `200` with an empty `user.permissions` array and `allowed: false`:

```json theme={null}
{
  "user": {
    "id": "U08FW4R4N6S",
    "permissions": []
  },
  "resource": {
    "type": "channel",
    "id": "C08G6QB90LU"
  },
  "action": "read",
  "allowed": false
}
```

This is not an error — it's a valid response indicating the user does not have the requested access.

## Next steps

<CardGroup>
  <Card title="Check Permissions reference" icon="code" href="/permissions-check/api-reference/check-permissions">
    Full request/response schema, resource ID formats, and error codes
  </Card>

  <Card title="List Resource Types" icon="tags" href="/permissions-check/api-reference/list-resource-types">
    Discover which resource types the connected provider supports
  </Card>
</CardGroup>


# Permissions Check
Source: https://docs.stackone.com/permissions-check/introduction

Check whether a specific user can access a specific resource and what permissions they hold — across all connected integration providers.

The Permissions Check service answers a single question: **can this user access this resource?**

Given a user identifier and a resource ID, it returns the permissions that user holds on that resource. If you also specify an action (`read`, `write`, `comment`, `delete`, `export`), it tells you whether that action is allowed.

## Why it exists

AI agents using RAG retrieve content chunks from indexed organizational data. Each chunk traces back to a source resource. Before including a chunk in a response, the agent needs to verify: can this user actually see this?

Without a unified check, agents either skip permission verification (a security risk) or build bespoke logic per provider (costly and fragile). The Permissions Check service handles this with a single API call regardless of which provider the resource comes from.

## Use cases

<AccordionGroup>
  <Accordion title="RAG chunk gating">
    Before including a retrieved content chunk in an agent response, call `POST /unified/check_permissions` with the chunk's source resource ID and `action: "read"`. Only include the chunk if `allowed: true`.
  </Accordion>

  <Accordion title="Pre-mutation guard">
    Before an agent performs a write operation on behalf of a user — commenting on a document, posting to a channel — verify the user holds the required permission first.
  </Accordion>

  <Accordion title="Permission summary">
    Omit the `action` field to get a full list of what the user can do on a resource, without checking a specific action.
  </Accordion>

  <Accordion title="Messaging channel membership check">
    Before sending a message or notification to a channel on behalf of a user, verify they are a member and hold the required permission.
  </Accordion>
</AccordionGroup>

## How it works

```mermaid theme={null}
sequenceDiagram
    participant Agent
    participant StackOne
    participant Provider

    Agent->>StackOne: POST /unified/check_permissions<br/>{ user_id, resource_id, action: "read" }
    StackOne->>Provider: Fetch user permissions for resource
    Provider-->>StackOne: Native role/permission data
    StackOne-->>Agent: { user.permissions: ["read"], allowed: true }
```

The service resolves the user (by ID or email), fetches their permissions for the resource from the integration provider, maps provider-native roles to the unified permission types, and returns the result.

## Relationship to IAM

The Permissions Check service complements the IAM [List Resource Users](/iam/api-reference/resource-users/list-resource-users) endpoint:

|              | Permissions Check                    | List Resource Users                   |
| ------------ | ------------------------------------ | ------------------------------------- |
| **Question** | Can this user do X on this resource? | Who has access to this resource?      |
| **Input**    | User + resource + optional action    | Resource type + resource ID           |
| **Output**   | Single user's permissions + yes/no   | All users with access, roles expanded |
| **Best for** | Fast per-user gate checks            | Full access audits                    |

When resolving permissions, the service accounts for the full IAM graph — direct permissions on the user, permissions inherited through [role assignments](/iam/api-reference/roles/list-roles), and permissions granted via [group membership](/iam/api-reference/groups/list-groups). The returned `user.permissions` reflect the union of all of these.

## Calling the service

The service is available via three interfaces:

* **HTTP** — [POST /unified/check\_permissions](/permissions-check/api-reference/check-permissions) with standard StackOne auth headers
* **StackOne CLI** — `stackone actions rpc unified_check_permissions` ([CLI reference](/guides/connector-engine/cli-reference))
* **Actions RPC** — [POST /actions/rpc](/platform/api-reference/actions/make-an-rpc-call-to-an-action) with `actionId: "unified_check_permissions"`


# Delete Account
Source: https://docs.stackone.com/platform/api-reference/accounts/delete-account

delete /accounts/{id}



# Get Account
Source: https://docs.stackone.com/platform/api-reference/accounts/get-account

get /accounts/{id}



# List Accounts
Source: https://docs.stackone.com/platform/api-reference/accounts/list-accounts

get /accounts



# Update Account
Source: https://docs.stackone.com/platform/api-reference/accounts/update-account

patch /accounts/{id}



# Make an RPC call to an action
Source: https://docs.stackone.com/platform/api-reference/actions/make-an-rpc-call-to-an-action

post /actions/rpc
Makes a remote procedure call to the specified action



# List Auth Configs
Source: https://docs.stackone.com/platform/api-reference/auth-configs/list-auth-configs

get /auth_configs
List the auth configs available to the project. Deprecated: use `GET /connector_profiles` instead.



# Authenticate Connect Session
Source: https://docs.stackone.com/platform/api-reference/connect-sessions/authenticate-connect-session

post /connect_sessions/authenticate



# Create Connect Session
Source: https://docs.stackone.com/platform/api-reference/connect-sessions/create-connect-session

post /connect_sessions



# Delete Connector Profile Pinned Version
Source: https://docs.stackone.com/platform/api-reference/connector-profiles/delete-connector-profile-pinned-version

delete /connector_profiles/{connectorProfileId}/pinned_version
Remove the pinned connector version for the given connector profile.



# Get Connector Profile Pinned Version
Source: https://docs.stackone.com/platform/api-reference/connector-profiles/get-connector-profile-pinned-version

get /connector_profiles/{connectorProfileId}/pinned_version
Get the pinned connector version for the given connector profile.



# List Connector Profile Versions
Source: https://docs.stackone.com/platform/api-reference/connector-profiles/list-connector-profile-versions

get /connector_profiles/{connectorProfileId}/versions
List the connector versions available for the given connector profile, indicating which one is currently pinned.



# List Connector Profiles
Source: https://docs.stackone.com/platform/api-reference/connector-profiles/list-connector-profiles

get /connector_profiles
List the connector profiles available to the project.



# Upsert Connector Profile Pinned Version
Source: https://docs.stackone.com/platform/api-reference/connector-profiles/upsert-connector-profile-pinned-version

put /connector_profiles/{connectorProfileId}/pinned_version
Create or update the pinned connector version for the given connector profile.



# Delete MCP session
Source: https://docs.stackone.com/platform/api-reference/mcp/delete-mcp-session

delete /mcp
Close an existing MCP session for the provided session id



# Open MCP SSE stream
Source: https://docs.stackone.com/platform/api-reference/mcp/open-mcp-sse-stream

get /mcp
Open a dedicated Server-Sent Events stream for MCP notifications



# Send MCP JSON-RPC message
Source: https://docs.stackone.com/platform/api-reference/mcp/send-mcp-json-rpc-message

post /mcp
Send JSON-RPC request to the MCP server over HTTP streaming transport



# Get Log
Source: https://docs.stackone.com/platform/api-reference/request-logs/get-log

get /requests/logs/{id}



# List Logs
Source: https://docs.stackone.com/platform/api-reference/request-logs/list-logs

get /requests/logs



# List Platform Logs
Source: https://docs.stackone.com/platform/api-reference/request-logs/list-platform-logs

get /requests/platform-logs



# List Step Logs
Source: https://docs.stackone.com/platform/api-reference/request-logs/list-step-logs

get /requests/logs/steps



# API SDKs
Source: https://docs.stackone.com/platform/common-guide/stackone-api-sdks

Language-native libraries for StackOne Unified APIs

## Postman

StackOne maintains a Postman collection to more easily test & interact with the StackOne internal API and unified APIs:  [***Run in Postman***](https://god.gw.postman.com/run-collection/25987823-c68540f2-7aba-475e-89d2-77625c6a6424?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D25987823-c68540f2-7aba-475e-89d2-77625c6a6424%26entityType%3Dcollection%26workspaceId%3Df291b2e0-d0cb-4dc2-93c4-c2d4f581da3f)

* You can also directly Download / import the Postman collection [via our github repository](https://github.com/StackOneHQ/stackone-client-postman)

## Unified API SDKs

StackOne maintains and publishes the following SDKs:

* **Ruby** ([RubyGems](https://rubygems.org/gems/stackone_client), [GitHub](https://github.com/StackOneHQ/stackone-client-ruby))
* **Typescript** ([npm](https://www.npmjs.com/package/@stackone/stackone-client-ts), [GitHub](https://github.com/StackOneHQ/stackone-client-typescript))
* **PHP** ([Packagist](https://packagist.org/packages/stackone/client-sdk), [GitHub](https://github.com/stackoneHQ/stackone-client-php)) - Beta
* **Java** ([Maven](https://mvnrepository.com/artifact/com.stackone/stackone-client-java), [GitHub](https://github.com/StackOneHQ/stackone-client-java)) - Beta
* **C#** ([nuget](https://www.nuget.org/packages/StackOneHQ.Client), [GitHub](https://github.com/StackOneHQ/stackone-client-csharp)) - Beta

Additionally, our API Reference provides code snippets in multiple languages (JavaScript, Python, PHP, Go, Java, Ruby), making it easy to copy and test our endpoints.

## AI Tools

StackOne makes it easy for AI agents to interact with any connected SaaS via its AI Toolset:

* **Node/Typescript** ([GitHub](https://github.com/StackOneHQ/stackone-ai-node))
  * [Basic Usage](/agents/typescript/basic-usage)
* **Python** ([GitHub](https://github.com/stackoneHQ/stackone-ai-python))

Reach out to our team via your dedicated Slack channel or at [support@stackone.com](mailto:support@stackone.com) to request access to any other SDK.


# Using Postman with the Platform API
Source: https://docs.stackone.com/platform/common-guide/using-postman

Test and explore the StackOne Platform API using the pre-configured Postman collection.

## Get the collection

The StackOne Platform API collection covers account management, connect sessions, actions, and more — auto-synced daily from the live OpenAPI spec.

<a href="https://www.postman.com/stackonehq/stackone-public/collection/4952c776-0324-491c-b597-3b6a4f78e2cb">
  <img alt="Run in Postman" />
</a>

The collection has Basic Auth pre-configured with `{{apiKey}}` as the username. Most endpoints also require the `x-account-id` header, set via `{{accountId}}`.

## Set up your environment

<Steps>
  <Step title="Create an environment">
    In Postman, click the **Environments** icon in the left sidebar, then **+** to create a new environment.
  </Step>

  <Step title="Add your credentials">
    | Variable    | Value                                                                                                        |
    | ----------- | ------------------------------------------------------------------------------------------------------------ |
    | `apiKey`    | Your StackOne API key — find it in the [dashboard](https://app.stackone.com) under **Settings → API Keys**   |
    | `accountId` | The linked account ID you want to target — visible in the [Accounts page](https://app.stackone.com/accounts) |
    | `baseUrl`   | `https://api.stackone.com` — change only if you're running a self-hosted StackOne region                     |
  </Step>

  <Step title="Select the environment">
    Select your environment from the dropdown in the top-right corner before sending any request.
  </Step>
</Steps>

## Explore the API

The collection is organised into folders by resource:

| Folder               | What it covers                                     |
| -------------------- | -------------------------------------------------- |
| **Accounts**         | List, retrieve, and manage linked accounts         |
| **Actions**          | Execute and list available actions via RPC         |
| **Connect Sessions** | Create connect session tokens for linking accounts |
| **Connectors**       | List enabled connectors and their metadata         |
| **MCP**              | MCP server configuration endpoints                 |
| **Proxy**            | Passthrough proxy requests                         |
| **Request Logs**     | Retrieve API request history                       |

<Tip>
  Start with **GET /accounts** to verify your API key, then use the returned account IDs as your `accountId` variable when exploring other endpoints.
</Tip>

## Also in the public workspace

<CardGroup>
  <Card title="StackOne Legacy APIs" icon="rectangle-history" href="https://www.postman.com/stackonehq/stackone-public/collection/8d04033a-b6b1-4c91-8235-729f5c46123a">
    Unified vertical APIs (HRIS, ATS, CRM, etc.)
  </Card>

  <Card title="StackOne MCP" icon="plug" href="https://www.postman.com/stackonehq/stackone-public/collection/68ca4160009b6f9cc908f435">
    MCP server endpoints
  </Card>
</CardGroup>


# Connect your Backend with StackOne
Source: https://docs.stackone.com/platform/connect-your-backend-with-stackone

Generate connect session tokens from your backend to securely link customer accounts through the Integration Hub

Connect sessions are short-lived tokens your backend generates to open the Integration Hub for a specific end user. Because they're generated server-side using your API key, your key is never exposed to the frontend.

You'll need a StackOne API key to call the [Connect Sessions endpoint](/platform/api-reference/connect-sessions/).

## Required fields

| Field               | Description                                                                        |
| ------------------- | ---------------------------------------------------------------------------------- |
| `origin_owner_id`   | The ID of the organization in your system (e.g. your customer's org ID)            |
| `origin_owner_name` | A human-readable name for the organization, stored against the account in StackOne |

These two fields combined with `provider` determine whether a new account is created or an existing one is updated. If the same combination has been used before, the existing account opens in edit mode. If not, a new account is created.

<Warning>
  Always set `origin_owner_id` server-side. Never pass it through from a client-side request.
</Warning>

## Optional fields

| Field                  | Description                                                                                                                                                                                                                                                                  |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `origin_username`      | Identifier for the user initiating the connection (e.g. `jane@company.com`)                                                                                                                                                                                                  |
| `provider`             | Opens the Hub directly at the credential entry step for this provider. Without it, the Hub shows the full provider selection screen.                                                                                                                                         |
| `categories`           | Array of category keys to open the Hub at the category selection step (e.g. `["hris", "ats"]`). Use when you want the user to pick a provider themselves.                                                                                                                    |
| `account_id`           | If an existing account ID is passed, the Hub opens in edit mode for that account so credentials can be updated.                                                                                                                                                              |
| `connector_profile_id` | Routes the session to a specific [connector profile](/guides/connector-profiles). Use this to target a non-default connector profile, for example after a connector major version upgrade. `integration_id` is deprecated but still accepted as an alias for the same value. |
| `label`                | Arbitrary string stored against the account.                                                                                                                                                                                                                                 |
| `multiple`             | Set to `true` to create a new account even when an existing one with the same `origin_owner_id` and `origin_owner_name` exists for this provider.                                                                                                                            |

<Note>
  If no `connector_profile_id` is passed, the connect session is created against the default connector profile for the given provider. You can set the default connector profile from the [Connector Profiles page](https://app.stackone.com/connector_profiles).
</Note>

<Warning>
  `provider_version` is deprecated. Passing it no longer selects a connector version and can cause session creation to fail. Remove it from your requests. To target a specific connector profile, use `connector_profile_id` instead.
</Warning>

## Basic implementation

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { StackOne } from "@stackone/stackone-client-ts";

  const stackOne = new StackOne({
    security: {
      username: process.env.STACKONE_API_KEY,
      password: "",
    },
  });

  app.post('/stackone_connect_sessions', async (req, res) => {
    const { originUsername, provider } = req.body;

    try {
      const result = await stackOne.connectSessions.createConnectSession({
        originOwnerId: "customer-123",
        originOwnerName: "Acme Inc",
        originUsername: originUsername,
        provider,
      });

      res.send({ token: result.connectSessionTokenAuthLink?.token });
    } catch (e) {
      res.status(500).send('error when trying to fetch session');
    }
  });
  ```

  ```python Python theme={null}
  from flask import Flask, request, jsonify
  import requests
  import base64

  app = Flask(__name__)

  @app.route('/stackone_connect_sessions', methods=['POST'])
  def stackone_connect_sessions():
      STACKONE_API_KEY = 'YOUR_STACKONE_API_KEY'
      headers = {
          'Authorization': 'Basic ' + base64.b64encode(f"{STACKONE_API_KEY}:".encode()).decode(),
          'Content-Type': 'application/json',
      }
      req_data = request.json

      payload = {
          'origin_owner_id': 'customer-123',
          'origin_owner_name': 'Acme Inc',
          'origin_username': req_data.get('originUsername'),
          'provider': req_data.get('provider'),
      }

      try:
          response = requests.post(
              'https://api.stackone.com/connect_sessions',
              headers=headers,
              json=payload
          )
          token = response.json().get('token')
          return jsonify({'token': token})
      except Exception as e:
          return ('error when trying to fetch session', 500)
  ```

  ```csharp C# theme={null}
  using Newtonsoft.Json;
  using Microsoft.AspNetCore.Mvc;
  using System;
  using System.Net.Http;
  using System.Text;
  using System.Threading.Tasks;

  [ApiController]
  [Route("[controller]")]
  public class StackOneConnectSessionsController : ControllerBase
  {
      [HttpPost]
      public async Task<IActionResult> Post([FromBody] dynamic reqBody)
      {
          string STACKONE_API_KEY = "YOUR_STACKONE_API_KEY";
          string authHeader = Convert.ToBase64String(Encoding.ASCII.GetBytes($"{STACKONE_API_KEY}:"));

          HttpClient client = new HttpClient();
          client.DefaultRequestHeaders.Add("Authorization", $"Basic {authHeader}");

          dynamic payload = new
          {
              origin_owner_id = "customer-123",
              origin_owner_name = "Acme Inc",
              origin_username = reqBody.originUsername,
              provider = reqBody.provider,
          };

          try
          {
              var response = await client.PostAsync(
                  "https://api.stackone.com/connect_sessions",
                  new StringContent(JsonConvert.SerializeObject(payload), Encoding.UTF8, "application/json")
              );
              dynamic data = JsonConvert.DeserializeObject(await response.Content.ReadAsStringAsync());
              return Ok(new { token = data.token });
          }
          catch (Exception)
          {
              return StatusCode(500, "error when trying to fetch session");
          }
      }
  }
  ```
</CodeGroup>

## Account behavior

| `origin_owner_id` + `origin_owner_name` + `provider` seen before? | Result                                          |
| ----------------------------------------------------------------- | ----------------------------------------------- |
| No                                                                | New account created                             |
| Yes                                                               | Existing account opened in edit mode            |
| — with `account_id`                                               | That specific account opened in edit mode       |
| — with `multiple: true` (no `account_id`)                         | New account created regardless of existing ones |

## Multiple accounts for the same provider

By default, creating a connect session with an `origin_owner_id` and `origin_owner_name` combination that already exists for a given provider will open that existing account in edit mode rather than create a new one.

If you need multiple linked accounts for the same provider under the same `origin_owner_id` — for example if a single customer connects several separate instances of the same tool — pass `multiple: true`. This creates a new account each time regardless of any existing ones with matching details.

<Note>
  `multiple` has no effect when `account_id` is set. When `account_id` is present the session always opens that specific account in edit mode.
</Note>

## Targeting a specific connector profile

Passing `provider` alone creates a session using the project's default connector profile for that provider. This is the right choice for most cases — if you only have one profile per provider, or want users going through the standard flow, you don't need anything else.

Each connector profile has a version pin controlling which connector version its linked accounts use. When you issue a connect session, the linked account that results from it is tied to the profile the session was created against — and inherits that profile's version pin. This is how connector version migration works in practice: you create a new connector profile pinned to the new version, then issue connect sessions with that profile's `connector_profile_id` so users authenticate against the new profile. When they reconnect, their account moves to the new version.

To route a session to a specific connector profile — for example when you have multiple profiles for the same provider, or you're migrating end users to a new connector version — pass its `connector_profile_id`.

Get the ID by calling [`GET /connector_profiles`](/platform/api-reference/connector-profiles/list-connector-profiles) and using the `id` field from the connector profile you want to target:

```bash theme={null}
curl https://api.stackone.com/connector_profiles \
  -H "Authorization: Basic <base64(api_key:)>"
```

Then pass it in the session request:

```bash theme={null}
curl -X POST https://api.stackone.com/connect_sessions \
  -H "Authorization: Basic <base64(api_key:)>" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_owner_id": "customer-123",
    "origin_owner_name": "Acme Inc",
    "provider": "bamboohr",
    "connector_profile_id": "01JHMM0V..."
  }'
```

This is most commonly used when migrating end users to a new connector major version that requires reauthentication. See [Connector Version Management](/guides/connector-versioning) for the full migration flow.

### Customizing the Hub Behavior

<Snippet />