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

# Authentication & 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. You authenticate with your StackOne API key and account ID, sent as headers.

### 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" target="_blank">**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" target="_blank">**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

The `Authorization` header carries your StackOne API key as a Basic auth token. For the full StackOne API authentication reference, see [Authentication](/api/authentication).

<Accordion title="How to create the Basic auth token" icon="key">
  **Steps:**

  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>
</Accordion>

### 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`)

## Multiple accounts in one request

A single request can span multiple connected accounts. Pass more than one account ID in the `x-account-id` header, either comma-separated or as repeated headers. The agent fans out across the accounts in parallel and routes each action back to its originating account. If one account is unavailable, the remaining accounts are still served.

To validate your credentials and see the account-specific skills, call `https://a2a.stackone.com/agent/authenticatedExtendedCard` with your `Authorization` and `x-account-id` headers. The `/.well-known/agent-card.json` discovery card is public and does not confirm authentication.

<CodeGroup>
  ```bash Comma-separated theme={null}
  x-account-id: <account_id_1>,<account_id_2>
  ```

  ```bash Repeated headers theme={null}
  x-account-id: <account_id_1>
  x-account-id: <account_id_2>
  ```
</CodeGroup>

## 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 credentials by fetching your authenticated extended card. That endpoint requires valid headers, so a successful response confirms your authentication. The public `/.well-known/agent-card.json` card requires no auth, so it cannot confirm credentials.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://a2a.stackone.com/agent/authenticatedExtendedCard \
    -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 cols={2}>
  <Card title="Quickstart" icon="rocket" href="/a2a/quickstart">
    Get started with the A2A UI and cURL
  </Card>

  <Card title="A2A SDK" icon="code" href="/a2a/a2a-sdk">
    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>