← Back to Documentation
Getting Started
Get up and running with AAP in 6 steps. From understanding the basics to validating your first token.
What You'll Learn
- AAP token structure and claims
- Setting up Authorization Server
- Requesting AAP tokens
- Validating tokens in Resource Server
1
Understand AAP Basics
AAP extends OAuth 2.0 with structured claims for AI agents.
- Agent identity (who is making the request)
- Capabilities with constraints (what actions are allowed)
- Task binding (purpose of the request)
- Delegation tracking (chain of authority)
- Human oversight (approval requirements)
2
Review JSON Schemas
Understand the token structure using formal schemas.
- aap-token.schema.json - Complete token structure
- aap-agent.schema.json - Agent identity
- aap-capabilities.schema.json - Actions and constraints
- aap-constraints.schema.json - Rate limits, domains, time windows
3
Set Up Authorization Server
Deploy an AS that issues AAP tokens.
Install Reference Implementation
# Clone repository
git clone https://github.com/aap-protocol/spec.git
cd spec/reference-impl
# Install dependencies
pip install -r requirements.txt
# Generate keys
bash scripts/generate_keys.sh
# Configure policies
cp policies/org-acme-corp.json policies/my-org.json
# Edit my-org.json with your capabilities
# Start AS
cd as
python server.py4
Request Your First Token
Use Client Credentials flow to get an AAP token.
Request Token
curl -X POST http://localhost:8080/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=agent-researcher-01" \
-d "client_secret=your-secret" \
-d "operator=org:acme-corp" \
-d "task_id=task-123" \
-d "task_purpose=research_articles" \
-d "capabilities=search.web,cms.draft" \
-d "audience=https://api.example.com"5
Validate Tokens in Resource Server
Implement validation logic in your API.
Python Validation Example
from aap_rs.validator import TokenValidator
validator = TokenValidator(
as_public_key=as_public_key,
rs_audience="https://api.example.com"
)
# Validate token
try:
payload = validator.validate(token, request={
"action": "search.web",
"target_url": "https://example.org/data"
})
print("Token valid:", payload["agent"]["id"])
except ValidationError as e:
print("Token invalid:", e)6
Test with Test Vectors
Validate your implementation against standard test cases.
- Valid tokens - Should pass all validation
- Invalid tokens - Should fail with specific errors
- Constraint violations - Test rate limits, domains, etc.
- Edge cases - Clock skew, delegation depth, etc.
Example AAP Token
A complete AAP token with all claims:
{
"iss": "https://as.example.com",
"sub": "spiffe://example.com/agent/researcher-01",
"aud": ["https://api.example.com"],
"exp": 1735689600,
"iat": 1735686000,
"jti": "unique-token-id",
"agent": {
"id": "agent-researcher-01",
"type": "llm-autonomous",
"operator": "org:acme-corp",
"model": "gpt-4"
},
"task": {
"id": "task-123",
"purpose": "research_articles",
"data_sensitivity": "public"
},
"capabilities": [
{
"action": "search.web",
"constraints": {
"domains_allowed": ["example.org", "wikipedia.org"],
"max_requests_per_hour": 50
}
}
],
"delegation": {
"depth": 0,
"max_depth": 2
}
}