DEV Community

Cover image for Ten Minutes to Your First Machine Identity
Nnaa
Nnaa

Posted on • Originally published at truthlocks.com

Ten Minutes to Your First Machine Identity

#tutorial #sdk #machineidentity #quickstart

Originally published on Truthlocks Blog

This is a hands on guide. By the end of it, you will have registered an AI agent with a cryptographic identity, created a bounded session, and verified the identity programmatically. The whole thing takes about ten minutes.

Prerequisites

You need a Truthlocks account (free tier works), an API key from the console, and Node.js 18 or later. If you prefer Python, the same steps work with the Python SDK. I will show both.

Step 1: Install the SDK

JavaScript:

npm install @truthlocks/sdk

Python:

pip install truthlocks

Step 2: Register Your Agent

Every agent needs an identity before it can operate. Registration creates a DID, generates a key pair, and records the agent in the trust registry.

JavaScript:

import { TruthlockClient } from '@truthlocks/sdk';

const client = new TruthlockClient({
  apiKey: process.env.TRUTHLOCK_API_KEY,
});

const agent = await client.agents.register({
  name: 'onboarding-assistant',
  description: 'Handles customer onboarding workflow',
  scopes: ['customers:read', 'customers:write', 'email:send'],
});

console.log('Agent ID:', agent.agentId);
console.log('Agent DID:', agent.did);
Enter fullscreen mode Exit fullscreen mode

Python:

from truthlocks import TruthlockClient

client = TruthlockClient(api_key="your-api-key")

agent = client.agents.register(
    name="onboarding-assistant",
    description="Handles customer onboarding workflow",
    scopes=["customers:read", "customers:write", "email:send"],
)

print(f"Agent ID: {agent.agent_id}")
print(f"Agent DID: {agent.did}")
Enter fullscreen mode Exit fullscreen mode

The response includes the agent's unique identifier, its DID (something like did:truthlock:agent:a1b2c3d4), and the public key that other systems can use to verify the agent's identity.

Step 3: Create a Session

Sessions are bounded execution contexts. They define when the agent can operate, what scopes it has for this specific run, and when the session expires.

JavaScript:

const session = await client.sessions.create({
  agentId: agent.agentId,
  scopes: ['customers:read', 'email:send'],
  durationMinutes: 60,
});

console.log('Session token:', session.token);
console.log('Expires at:', session.expiresAt);
Enter fullscreen mode Exit fullscreen mode

Python:

session = client.sessions.create(
    agent_id=agent.agent_id,
    scopes=["customers:read", "email:send"],
    duration_minutes=60,
)

print(f"Session token: {session.token}")
print(f"Expires at: {session.expires_at}")
Enter fullscreen mode Exit fullscreen mode

Notice that the session scopes are a subset of the agent's registered scopes. The session requests only customers:read and email:send, even though the agent is also authorized for customers:write. This is the principle of least privilege applied at the session level: the agent requests only what it needs for this specific execution context.

Step 4: Verify the Identity

When your agent calls another service, that service needs to verify the agent's identity. The receiving service takes the session token from the request header and validates it:

JavaScript:

const verification = await client.sessions.validate(session.token);

console.log('Valid:', verification.valid);
console.log('Agent:', verification.agentName);
console.log('Trust score:', verification.trustScore);
console.log('Scopes:', verification.scopes);
Enter fullscreen mode Exit fullscreen mode

Python:

verification = client.sessions.validate(session.token)

print(f"Valid: {verification.valid}")
print(f"Agent: {verification.agent_name}")
print(f"Trust score: {verification.trust_score}")
print(f"Scopes: {verification.scopes}")
Enter fullscreen mode Exit fullscreen mode

The validation checks the cryptographic signature, confirms the session has not expired, verifies the agent's identity against the trust registry, and returns the current trust score and authorized scopes. All of this happens in a single API call.

Step 5: Check the Trust Score

Your agent now has a trust score that reflects its behavioral history. As the agent operates cleanly over time, the score rises. You can check it anytime:

const score = await client.agents.getTrustScore(agent.agentId);

console.log('Trust score:', score.score);
console.log('Trend:', score.trend);
console.log('Factors:', score.factors);
Enter fullscreen mode Exit fullscreen mode

A brand new agent starts with a baseline score. The score adjusts based on the five trust factors: behavioral compliance, scope adherence, anomaly detection, peer attestations, and session hygiene.

What Just Happened

In about ten minutes, you gave an AI agent a cryptographic identity that can be independently verified by any system, scoped authorization that enforces what the agent can and cannot do, a bounded session that limits when and how long the agent operates, a trust score that tracks the agent's reliability over time, and an audit trail in the transparency log recording every step.

This is the foundation that everything else builds on: anti fraud detection, compliance reporting, cross tenant delegation, automated kill switches. It all starts with giving the agent an identity.

Explore the full API reference for advanced features, or visit the console to see your agent in the dashboard.

Truthlocks provides machine identity infrastructure for AI agents. Register, verify, and manage non-human identities with trust scoring and instant revocation.

Top comments (0)