API Reference
Version: v0.4
Base URL: Current website instance
Authentication
Most endpoints require Bearer token authentication. Agent Builders can generate API tokens through the dashboard after signing up. Currently GitHub oauth is supported.
Authorization: Bearer YOUR_API_TOKEN
Registry and Issuing Entity
Registry (REG): Public endpoints for Service Providers to validate Agent Tokens and check revocation status.
Issuing Entity (IE): Authenticated endpoints for Agent Builders to issue and manage Agent Tokens (ATKs).
For Service Providers
Service Providers are publishers, SaaS platforms, API providers, and product builders who need to verify AI agent identities. The Registry provides public endpoints to validate Agent Tokens without requiring authentication.
Get Public Keys (JWKS)
Retrieve the public keys needed to verify Agent Token signatures.
What is it for? Service Providers use these keys to cryptographically verify that incoming Agent Tokens are authentic and haven't been tampered with.
GET /.well-known/jwks.json
Response:
{
"keys": [
{
"kty": "OKP",
"crv": "Ed25519",
"kid": "poc-heimdall-key-01",
"x": "base64url-encoded-public-key",
"alg": "EdDSA",
"use": "sig"
}
]
}
Usage: Cache this response and refresh periodically. Use the public key to verify JWT signatures using standard JWT libraries.
Check Token Revocation Status
Verify if a specific Agent Token has been revoked.
GET /reg/revocation-status?jti={token_id}
Parameters:
- jti
(required) - The JWT ID from the Agent Token
Response:
{
"jti": "unique-token-id",
"is_revoked": false,
"checked_at": "2025-01-15T10:30:00Z"
}
Error Codes:
- 400
- Invalid or missing JTI
- 500
- Server error during lookup
Usage: Check revocation status for high-security operations or when caching tokens for extended periods.
Service Provider SDK
Verify agent tokens with cryptographic signature validation, audience checking, and revocation status - ensuring only authorized AI agents can access your services.
Installation
pip install heimdall-sp-validator-sdk
And, follow further steps from sdk documentation
For Agent Builders
Agent Builders are developers creating AI agents that need authenticated access to external services.
Getting Authentication Token
- Sign In: Log in through GitHub OAuth using the "Sign up with GitHub" button
- Generate Token: Navigate to your dashboard and click "Generate new token"
- Secure Storage: Copy and securely store your API token - you won't see it again
Token Security: Never expose API tokens in client-side code. Store securely in environment variables or secure configuration.
Issue Agent Token (ATK)
Create a new Agent Token for your AI agent to access a specific service.
POST /api/v1/ie/issue-atk
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
Request:
{
"user_id": "end-user-123",
"audience_sp_id": "https://api.newsservice.com",
"permissions": ["read:articles_all", "summarize:text_content_short"],
"purpose": "Daily news summary for user dashboard",
"model_id": "gpt-4-turbo"
}
Parameters:
- user_id
- Identifier for the user delegating the agent
- audience_sp_id
- Target service provider's API endpoint
- permissions
- Array of specific permissions needed
- purpose
- Human-readable description of the agent's task
- model_id
- AI model being used
Response:
{
"atk": "eyJhbGciOiJFZERTQSIsImtpZCI6InBvYy1oZWltZGFsbC1rZXktMDEiLCJ0eXAiOiJKV1QifQ..."
}
Error Codes:
- 400
- Invalid parameters or unsupported model/permissions
- 401
- Missing or invalid API token
- 500
- Token generation failed
Token Lifetime: Tokens expire after 15 minutes by default. Issue new tokens as needed.
Revoke Agent Token
Immediately invalidate a previously issued Agent Token.
POST /reg/revoke-atk
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
Request:
{
"jti": "token-id-to-revoke"
}
Response:
{
"message": "Token 'token-id-to-revoke' successfully revoked"
}
Error Codes:
- 400
- Invalid JTI format
- 401
- Authentication required
- 403
- Can only revoke tokens you issued
- 500
- Revocation failed
Security: You can only revoke tokens that you originally issued. This prevents unauthorized revocation of other users' tokens.
Agent Builder SDK
Issue and manage Agent Tokens (ATKs) to enable your AI agents to authenticate securely with service providers.
Installation
pip install heimdall-agent-builder-sdk
Security Considerations
For Service Providers
Token Validation Pipeline:
1. Verify JWT signature using JWKS public keys
2. Check token expiration (exp
claim)
3. Validate audience matches your service (aud
claim)
4. For sensitive operations, check revocation status
5. Enforce permissions based on your service requirements
Implementation:
# 1. Get public keys (cache this)
curl "/.well-known/jwks.json"
# 2. Check revocation (optional, for high-security use)
curl "/reg/revocation-status?jti=token-jti"
# 3. Validate signature in your application code
For Agent Builders
API Token Security:
- Store tokens in environment variables, never in code
- Use HTTPS for all API calls
- Regenerate tokens if compromised
- Set up token rotation policies
Token Management:
- Request minimal permissions needed
- Use descriptive purposes for audit trails
- Revoke tokens when agents complete tasks
Example Secure Usage:
# Issue token
curl -X POST "/api/v1/ie/issue-atk" \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"user_id":"user-123","audience_sp_id":"https://api.service.com","permissions":["read:basic"],"purpose":"User requested summary","model_id":"gpt-4-turbo"}'
# Use the ATK with the target service
curl -X GET "https://api.service.com/data" \
-H "Authorization: Bearer $AGENT_TOKEN"
# Revoke when done
curl -X POST "/reg/revoke-atk" \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"jti":"token-jti-from-atk"}'
Supported Values
AI Models
OpenAI Models
gpt-4.1
gpt-4.1-mini
gpt-4.1-nano
gpt-4o
gpt-4o-mini
gpt-4-turbo
gpt-3.5-turbo
o3
o3-mini
o1-preview
o1-mini
Anthropic Claude Models
claude-sonnet-4-20250514
claude-opus-4
claude-3.7-sonnet
claude-3.5-sonnet-20241022
claude-3.5-haiku-20241022
claude-3-opus-20240229
claude-3-sonnet-20240229
claude-3-haiku-20240307
Google Gemini Models
gemini-2.5-pro-experimental
gemini-2.5-flash
gemini-2.0-flash
gemini-2.0-flash-lite
gemini-2.0-pro-experimental
gemini-1.5-pro-latest
gemini-1.5-flash-latest
xAI Models
grok-3
grok-2
grok-1.5
Meta Llama Models
**Llama 4 Generation:**llama-4-scout-17b
llama-4-maverick-17b
**Llama 3.3 Generation:**
llama-3.3-70b
llama-3.3-70b-instruct
**Llama 3.2 Generation:**
llama-3.2-90b-vision
llama-3.2-11b-vision
llama-3.2-3b
llama-3.2-1b
llama-3.2-3b-instruct
llama-3.2-1b-instruct
**Llama 3.1 Generation:**
llama-3.1-405b
llama-3.1-405b-instruct
llama-3.1-70b
llama-3.1-70b-instruct
llama-3.1-8b
llama-3.1-8b-instruct
**Legacy Llama:**
meta-llama/Meta-Llama-3-70B-Instruct
llama-3-70b-instruct
llama-3-8b-instruct
Mistral Models
**Latest Generation:**mistral-large-2
pixtral-large
mistral-medium-3
mistral-small-3.1
**Reasoning Models:**
magistral-medium
magistral-small-24b
**Specialized Models:**
mistral-nemo-12b
codestral-22b
codestral-mamba-7b
mathstral-7b
**Core Models:**
mistral-7b-v0.3
mistral-7b-instruct-v0.3
mixtral-8x7b-instruct-v0.1
mixtral-8x22b-instruct-v0.1
**Legacy naming:**
mistralai/Mistral-7B-Instruct-v0.2
mistralai/Mixtral-8x7B-Instruct-v0.1
Alibaba Qwen Series
qwen-2.5-max
qwen-2.5-72b-instruct
qwen-2.5-32b-instruct
qwen-2.5-14b-instruct
qwen-2.5-7b-instruct
qwen-2.5-3b-instruct
qwen-2.5-1.5b-instruct
qwen-2.5-coder-32b
qwen-2.5-math-72b
qwen-2.5-vl-72b
DeepSeek Models
deepseek-r1
deepseek-v3
deepseek-coder-v2-236b
deepseek-coder-33b-instruct
deepseek-math-7b
deepseek-chat
Other Chinese Models
yi-34b-chat
yi-6b-chat
baichuan2-13b-chat
chatglm3-6b
internlm2-20b
Cohere Models
command-r-plus
command-r
command-light
command-nightly
Microsoft Models
phi-3.5-mini-instruct
phi-3.5-moe-instruct
phi-3-medium-instruct
microsoft/phi-2
orca-2-13b
orca-2-7b
Open Source Community Models
**Large Models:**bloom-176b
falcon-180b
falcon-40b
falcon-7b
**Popular Community Models:**
starling-lm-7b-alpha
openchat-3.5-0106
zephyr-7b-beta
vicuna-13b-v1.5
vicuna-7b-v1.5
wizardlm-70b-v1.0
wizardlm-13b-v1.2
alpaca-7b
**Legacy naming:**
HuggingFaceH4/zephyr-7b-alpha
openchat/openchat-3.5-0106
**Code Specialists:**
code-llama-34b-instruct
code-llama-13b-instruct
code-llama-7b-instruct
wizardcoder-34b-v1.0
starcoder2-15b
starcoder2-7b
AI21 Models
jurassic-2-ultra
jurassic-2-mid
jurassic-2-light
Stability AI Models
stable-code-3b
stablelm-2-12b
stablelm-2-1.6b
Multimodal Specialists
llava-1.6-34b
llava-1.6-13b
llava-1.6-7b
blip2-flan-t5-xl
instructblip-7b
minigpt-4
Alternative Architectures
rwkv-4-7b
mamba-2.8b
retnet-7b
jamba-instruct
Standard Permissions
read:articles_all
- Read all articlesread:user_profile_basic
- Read basic user profilesummarize:text_content_short
- Create short summariesanalyze:sentiment_text
- Analyze text sentimentinteract:chatbot_basic
- Basic chatbot interactions
Custom permissions are supported - use descriptive, colon-separated format like action:resource_scope