Service Authentication

Alien Agent ID supports two authentication models: Alien Agent ID tokens for Alien-aware services, and vault credentials for external services like GitHub, AWS, and Slack.

Alien-Aware Services

Services that integrate with Alien Agent ID verify agents using Ed25519 token assertions. The token is self-contained — no pre-registration, no shared secrets, no database lookup.

Generating Auth Tokens


# JSON output (for programmatic use)
node cli.mjs auth-header
 
# Raw header (for curl)
node cli.mjs auth-header --raw

Using Tokens in HTTP Requests


# Direct with curl
curl -H "$(node cli.mjs auth-header --raw)" https://service.example.com/api/whoami
 
# Or extract the token
TOKEN=$(node cli.mjs auth-header | jq -r .token)
curl -H "Authorization: AgentID $TOKEN" https://service.example.com/api/data

Token Anatomy

The token is a base64url-encoded JSON payload signed with Ed25519:


{
  "v": 1,
  "fingerprint": "f5d9fac4...",
  "publicKeyPem": "-----BEGIN PUBLIC KEY-----\n...",
  "owner": "00000003010000000000539c741e0df8",
  "timestamp": 1774531517000,
  "nonce": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "sig": "<Ed25519-base64url-signature>"
}

Field	Description
`v`	Token version (always `1`)
`fingerprint`	SHA-256 hash of the agent’s public key (64 hex chars)
`publicKeyPem`	Agent’s Ed25519 public key in SPKI PEM format
`owner`	AlienID address of the human owner (or `null` if unbound)
`timestamp`	Unix timestamp in milliseconds
`nonce`	Random 128-bit hex string for replay resistance
`sig`	Ed25519 signature over canonical JSON of all other fields

Token Properties

5-minute validity — timestamp-based expiry prevents long-lived tokens
Self-contained — services verify the signature against the embedded public key
Replay-resistant — random nonce + short validity window
No shared secrets — Ed25519 asymmetric signatures, not HMAC

External Services

External services (GitHub, AWS, Slack) don’t know about Alien Agent ID tokens. The agent authenticates using credentials stored in the Credential Vault.

Retrieve and Use Credentials


# Retrieve stored credential
TOKEN=$(node cli.mjs vault-get --service github | jq -r .credential)
 
# Use it for API calls
curl -H "Authorization: Bearer $TOKEN" https://api.github.com/user/repos

If the credential doesn’t exist in the vault, ask the user to provide it using the secure storage flow.

Next Steps

Service Integration — Add Alien Agent ID verification to your own service
Credential Vault — Store and manage credentials securely
CLI Reference — Full auth-header command reference