Getting Started

  1. Create an AI Agent
    Go to the Nuggets Account Portal and navigate to the AI Agents page to create your first agent.

  2. Download Private Key and Save Client ID
    Once created, you will be prompted to download the private key for this client. It is important you save this file.
    This key is only available once and is needed to successfully authenticate your AI Agent.

  3. (Optional) Add Verified Information
    Within Nuggets, you can build greater trust by adding verified information—such as a validated social media account for either the AI Agent or its creator.

Authenticating The Agent

Now you have created the Agent inside the Accounts Portal, we can use the created details to authenticate the agent.

  • Using @nuggetslife/auth

  • Manual

1. Install the authentication package.

To get started, firstly install the authentication package on the agent and server.

npm install @nuggetslife/auth

Next, you’ll need to add the private key and the DID provided from the accounts portal to your agent environment:

export NUGGETS_DID=
export NUGGETS_PRIVATE_JWK=

2. Expose an authentication endpoint on the Agent.

Expose an endpoint on your agent which allows for the JWT token to be generated (via createAuthenticationToken). Under the hood, this uses your downloaded private key and assigns the DID to the payload.

Create the authentication token on the agent (express example).

// # Agent
import type { Request, Response } from "express";
import { createAuthenticationToken } from "@nuggetslife/auth/ai";

app.get("/authenticate", async (req: Request, response: Response) => {
  const token = await createAuthenticationToken();
  res.send(token);
});

3. Verify the token

Once the requesting server receives the token, you are then able to verify it using the verifyToken function. If successful, this will return the DID Document for the client. If unsuccessful, the agent is potentially a bad actor.

You can get the details from your clients DID Document by extracting the client ID from your DID and navigating to https://auth.nuggets.life/{CLIENT_ID}/.well-known/did.json

Authenticate the agents token.

import { verifyToken } from "@nuggetslife/auth/ai";

function getTokenFromAgent() {
  return fetch("AGENT_URL/authenticate").then((res) => res.json());
}

export async function authenticate() {
  try {
    const token = await getTokenFromAgent();
    const { did } = await verifyToken(token);
  } catch (error) {
    console.error("Error verifying the token");
  }
}

Verify token response

  • did
    object
    The DID Document resolved from the DID in the token.

  • services
    object
    An object of services

  • services.VerifiedInformationAPI
    string
    Returns the URL to get the verified information as JSON

  • services.VerifiedInformationHTML
    string
    See a hosted page with the details of your AI Agent

4. Additional Information

Once a successful connection is made, you’re then able to retrieve more information about the agent via the verifiedDetails call. This calls the services that are returned as part of the client’s DID Document.

You can get the verified information about your client by extracting the client ID from your DID and navigating to https://auth.nuggets.life/verified-info/{CLIENT_ID}/json

Get Verified Information

import { getVerifiedDetails } from "@nuggetslife/auth/ai";

export async function authenticate() {
  try {
    const token = await getTokenFromAgent();
    const { did } = await verifyToken(token);
    const verifiedDetails = await getVerifiedDetails(did);
  } catch (error) {
    console.error("Error verifying the token");
  }
}

1. Add your environment variables

export NUGGETS_DID=
export NUGGETS_PRIVATE_JWK=

2. Generate Token

On your agent, start by creating an authentication endpoint that your server can call. This endpoint should return a JWT containing the DID, signed with your private key.

3. Verifying the Agent’s Identity with did:web

  1. Extract the DID from the JWT
    The JWT payload should include a sub or custom claim containing the agent’s DID:did:web:auth.nuggets.life:CLIENT_ID

  2. Resolve the DID Document
    To verify the JWT, the server must resolve the DID to retrieve the associated public key. For did:web, the DID translates to a standard HTTPS URL. Replace : with / after did:web: and append /did.json. For example:did:web:auth.nuggets.life:CLIENT_ID → https://auth.nuggets.life/CLIENT_ID/did.json

  3. Verify the JWT
    Use the public key found in the verificationMethod section of the DID Document to verify the JWT’s signature. If successful your AI Agent will be authenticated.

4. Accessing Additional Agent Information

Once you’ve successfully authenticated the agent and verified the JWT, you’ll have access to the agent’s valid DID Document. Using the service field in this document, you can retrieve additional information provided by the agent. This may include:

  • Ownership details
  • Verified social media accounts
  • Other relevant metadata

This allows your application to build a richer, more trustworthy profile of the agent.