Skip to main content

​
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: 
Authorization: Basic <BASE64_ENCODED_STACKONE_API_KEY>
x-account-id: <ACCOUNT_ID>
Content-Type: application/json
Get API Key:
  1. Go to Configuration → API Keys in the dashboard
  2. Create or copy existing API key
Get Account ID:
  1. Go to Accounts 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.See API Keys Guide for detailed instructions.
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.

​
API Key

The Authorization header carries your StackOne API key as a Basic auth token. For the full StackOne API authentication reference, see Authentication.
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
echo -n "<stackone_api_key>:" | base64

​
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. 
x-account-id: <account_id_1>,<account_id_2>

​
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. 
curl -X GET https://a2a.stackone.com/agent/authenticatedExtendedCard \
  -H 'Authorization: Basic <YOUR_BASE64_TOKEN>' \
  -H 'x-account-id: <YOUR_ACCOUNT_ID>'
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:

Quickstart

Get started with the A2A UI and cURL

A2A SDK

Use the official A2A SDKs to build your own tools

Agent Guides

Build agents in frameworks with A2A integrations