> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sideshift.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Agency subaccount access

> Use one scoped Platform key or OAuth connection for explicitly delegated direct subaccounts.

An agency can use one credential for its parent company and selected **direct subaccounts**.
Both scoped Platform API keys and human OAuth/MCP connections support delegation. Delegation
is optional and starts off. It does not give access to unrelated companies or grandchildren.

## Choose the credential

| Use case                              | Setup                                                                                                       |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Your agency's script or backend       | Create a Platform API key in the parent agency and select subaccount access                                 |
| An app connecting another agency      | Run OAuth authorization code with PKCE; the person chooses the parent and delegates children during consent |
| An AI assistant                       | Connect MCP through OAuth, choose the parent, and delegate children during consent                          |
| OAuth `client_credentials` automation | Company-bound; use a delegated Platform key or human OAuth grant when you need child access                 |

## Select access

For a key, select the parent agency in SideShift, open **Settings → Platform API & MCP → API
keys**, and click **Create key**. Choose scopes and turn on **Allow access to sub-accounts**.
For OAuth/MCP, the same choice appears on the parent agency's consent screen.

* **Off:** only the connected company.
* **Only these sub-accounts:** choose at least one current child. Future children are excluded.
* **All sub-accounts:** includes current children and children created later, subject to live
  membership and permission checks. Use a selected list when the workload needs a fixed boundary.

Choose `campaigns:read` to list campaigns. Add `settings:read` if the integration also needs
`GET /companies` to discover permitted company IDs. A valid ID alone never grants access.

## Make a request for one child

Use the saved key from the [API key quickstart](/self-use). Set the ID of a delegated child:

```bash theme={"system"}
export SIDESHIFT_SUBACCOUNT_ID="YOUR_CHILD_COMPANY_ID"

curl -sS "https://app.sideshift.app/api/oauth/v1/campaigns?limit=25" \
  -H "x-api-key: $SIDESHIFT_API_KEY" \
  -H "X-Act-As-Company: $SIDESHIFT_SUBACCOUNT_ID"
```

For OAuth, replace the `x-api-key` header with `Authorization: Bearer $SIDESHIFT_ACCESS_TOKEN`.
Send only one authentication header. Omit `X-Act-As-Company` to call the parent. Each request
selects one company; this header does not change the saved connection or dashboard selection.

In MCP, call `whoami` to inspect the connection and `list_companies` to find permitted IDs
(`settings:read` required). Pass `act_as_subaccount_id` to the business tool for one delegated
call. The [MCP guide](/mcp-server#agency-sub-account-delegation) covers the tool flow.

## Checks on every delegated request

The credential must still authorize the operation on the parent. The server then verifies that
the target is still a direct child, was delegated, and is accessible to the authorizing person.
The person's **direct child membership takes precedence** over inherited agency membership.
Canonical company and parent owners retain ownership authority.

For example, a non-owner agency member with Campaigns Read/Write on the parent but only
Campaigns Read in a direct child membership can read that child's campaigns and cannot edit
them. Selecting “All sub-accounts” does not override that restriction.

Protected child operations also require the child's subscription eligibility. Removing a child
from the agency or removing the person's access prevents later delegated requests. Supported
aggregate reports filter children through the same delegation and live access limits; do not
assume an agency credential exposes every company in a portfolio.

## Change access or troubleshoot

| Result                                                  | Next step                                                                                                                                       |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `403 forbidden`, reason `subaccount_access_not_granted` | Create a replacement key with delegation, or reconnect OAuth/MCP and enable subaccount access                                                   |
| `404 not_found`                                         | Check that the ID is a delegated direct child and the authorizing person still has access; inaccessible and nonexistent IDs share this response |
| `403 insufficient_scope`                                | Check the credential's scopes and the person's current permissions in both parent and child                                                     |
| `402 subscription_required`                             | Check subscription eligibility for the parent and requested child                                                                               |

Key scopes and delegation cannot be edited: create a replacement, verify it, switch the
workload, then revoke the old key. For a narrower OAuth/MCP connection, disconnect and
reconnect with the intended company, scopes, and children. Keep separate credentials when
workloads need independent revocation or different subaccount boundaries.