Quickstart: Zero to Authorization in 5 Minutes

Welcome to Hessra! This quickstart guide will get you up and running with cryptographically verifiable authorization tokens in just a few minutes.

> What is Hessra?

Hessra provides two types of tokens for secure machine-to-machine communication:

• Identity Tokens: Prove WHO you are (like a passport) - no permissions, just identity
• Authorization Tokens: Grant WHAT you can do (like a ticket) - short-lived, single-action permissions

> Prerequisites

Before you begin, you'll need:

1. Hessra service access: Join the waitlist or email hello@hessra.net
2. Policy repository: Fork this template (keep it private)
3. mTLS certificates: For authenticating your services

> Installation

Choose your platform:

Rust SDK

[dependencies]
hessra-sdk = "0.10.0"

Python SDK

pip install hessra-py

TypeScript SDK (note: TypeScript SDK is API only right now)

npm install @hessra/hessra-sdk

CLI Tool

cargo install hessra

> Your First Authorization Token

Here's the simplest example - requesting and verifying an authorization token:

use hessra_sdk::Hessra;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Initialize client with mTLS
    let mut client = Hessra::builder()
        .base_url("yourco.hessra.net")
        .mtls_cert(MTLS_CERT)  // Your client certificate
        .mtls_key(MTLS_KEY)    // Your private key
        .server_ca(SERVER_CA)   // CA certificate
        .build()?;

    // 2. Setup (fetches public key for offline verification)
    client.setup().await?;

    // 3. Request an authorization token
    let token = client
        .request_token("users", "read")  // Resource and operation
        .await?;

    println!("Got token: {}...", &token[..20]);

    // 4. Verify the token (happens in your service)
    client.verify_token_local(
        &token,
        "uri:urn:service:api",  // Subject from certificate
        "users",                 // Resource
        "read"                   // Operation
    )?;

    println!("Token verified!");
    Ok(())
}

That's it! You've just:

• Authenticated using mTLS certificates
• Requested a scoped authorization token
• Verified it offline without any network calls

> What's Next?

Now that you have the basics working, choose your path:

Need Identity Tokens?

For API key replacement, AI agents, or delegation chains: → Getting Started with Identity

Need Authorization Tokens?

For fine-grained permissions, service chains, or multi-party auth: → Getting Started with Authorization

Common Patterns

> Quick Configuration Example

Your GitOps repository controls who can do what. Here's a minimal clients.toml:

# CA certificates
[cacerts]
cert_chain = '''-----BEGIN CERTIFICATE-----
...your CA cert...
-----END CERTIFICATE-----'''

# Service permissions
[[clients]]
identifier = { type = "san_uri", value = "uri:urn:service:api" }
resources = [
  { name = "users", operations = ["read", "write"] },
  { name = "orders", operations = ["read"] }
]

# Enable identity tokens (optional)
identity_token_enabled = true
identity_token_duration = 3600

See the authorization configuration guide for complete details.

> Key Concepts Summary

Token Lifetimes

• Identity tokens: Hours to days (for authentication)
• Authorization tokens: Minutes to seconds (for single actions)

Verification Methods

• Online: API call to authorization service
• Offline: Local verification with public key (preferred)

Advanced Features

• Service Chains: Cryptographic proof of request path through services
• Multi-Party Auth: Multiple organizations must approve
• Delegation: Create sub-identities without central authority

> Getting Help

• Detailed Guides: Identity | Authorization
• Code Examples: GitHub
• API Docs: SDK Reference
• Support: hello@hessra.net

> Ready to Dive Deeper?

You've seen how easy it is to add cryptographically secure authorization to your services. Now explore the full power of Hessra:

1. Identity Tokens - Replace API keys and enable delegation
2. Authorization Tokens - Fine-grained, verifiable permissions
3. Blog: Delegated Agent Identities - Real-world AI agent example

Built for machines. Secured by cryptography. Managed through GitOps.