Skip to main content

​
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: 
Authorization: Basic <BASE64_ENCODED_STACKONE_API_KEY>
x-account-id: <ACCOUNT_ID>
Content-Type: application/json
Get API Key:
  1. Log into StackOne Dashboard
  2. Navigate to your project
  3. Go to Settings → API Keys
  4. Create or copy existing API key
Get Account ID:
  1. Go to Accounts section in 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

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

​
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: 
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>'
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

SDK Guides

Use the official A2A SDKs to build your own tools

Agent Guides

Build agents in frameworks with A2A integrations