Authentication
All requests to the Alsorn Protocol API must be authenticated with an API key. This guide covers key formats, permission levels, and security best practices.
API Keys
API keys always start with the als_ prefix followed by 64 hexadecimal characters. You can create and manage keys from the /control/keys page in the dashboard.
Pass your key in the Authorization header as a Bearer token:
Authorization: Bearer als_abc123def456789012345678901234567890123456789012345678901234abcdPermissions
Each API key is assigned one of three permission levels. When creating a key, choose the minimum permission level required for your use case.
Permission Levels
| Parameter | Type | Required | Description |
|---|---|---|---|
| read | permission | optional | Query agents, trust scores, and transaction history. Cannot modify any resources. |
| write | permission | optional | Everything in read, plus register agents, execute transactions, and update agent configurations. |
| admin | permission | optional | Full access. Everything in write, plus manage API keys, configure webhooks, and access billing settings. |
Security Best Practices
Never expose keys in client-side code
Use environment variables
Store your API key in an environment variable such as ALSORN_API_KEY and read it at runtime. Never hard-code keys into source files or commit them to version control.
Rotate keys regularly
Create a new key, update your services to use it, then revoke the old key. The Alsorn dashboard allows you to have multiple active keys simultaneously to support zero-downtime rotation.
Use the least privilege
Assign each key the minimum permission level it needs. A service that only reads trust scores should use a read key, not an admin key.
Monitor key usage
Review API key activity in the dashboard regularly. If you see unexpected usage patterns, revoke the compromised key immediately and create a replacement.