Authenticate a TypeScript client

Use this procedure to authenticate the current TypeScript client against NAMS. You need an installed SDK and a credential for the intended workspace. Use the authentication reference for service scopes, expiry and identity-provider policy; they are separate from SDK versions.

1. Configure a credential and check access

Get a credential from NAMS and set MEMORY_API_KEY without committing it to your repository. The default client reads that variable when process.env is available.

import { MemoryClient } from "@neo4j-labs/agent-memory";

const client = new MemoryClient({
  apiKey: process.env.MEMORY_API_KEY,
  workspaceId: process.env.MEMORY_WORKSPACE_ID,
});
try {
  const conversations = await client.shortTerm.listConversations({ limit: 1 });
  console.log(`Authenticated; returned ${conversations.length} conversation(s).`);
} finally { await client.close(); }

An empty successful list verifies the request too. A 401/403 becomes AuthenticationError; inspect its optional requestId and check the credential’s workspace/scope. Never print a key just to check whether it is present.

On Cloudflare Workers, pass env.MEMORY_API_KEY from the handler explicitly. workspaceId sends X-Workspace-Id where the deployment needs it; an explicit entry in headers overrides that value. A conversation’s userId is a separate identifier and does not choose a workspace.

2. Supply an application-managed refresh callback when needed

For OAuth, the application obtains and securely stores tokens using the service’s flow. tokenProvider overrides apiKey and is called while building request headers. It must return a usable access token; the SDK does not automatically schedule refresh or retry a request after a 401.

import { MemoryClient } from "@neo4j-labs/agent-memory";

// Inject your application's token store; implement expiry/refresh coordination there.
function clientWithTokens(getFreshAccessToken: () => Promise<string>) {
  return new MemoryClient({ tokenProvider: getFreshAccessToken });
}

client.auth.refreshAccessToken(refreshToken) returns an AccessTokenPair (accessToken, refreshToken, expiresIn). Save the returned refresh token as part of the application’s token-store update. Do not log token contents.

3. Manage keys only with appropriate workspace permissions

The current source exposes auth.listApiKeys(workspaceId), createApiKey({ label, scopes, workspaceId }), rotateApiKey(keyId), revokeApiKey(keyId) and revealApiKey(keyId, workspaceId). The service authorizes these operations; an ordinary data-plane key may not have administrative access. Inspect the returned optional expiresAt/key fields rather than assuming every response contains plaintext.

Rotation and revocation change credentials used by applications. Coordinate the replacement with those applications and store any returned plaintext in their secret store. Consult the API reference for method types and error handling for failed requests. Other language clients have their own configuration names and should use their corresponding SDK guides.

For OAuth discovery endpoints and token flows, use the authentication reference. The SDK refresh callback consumes an access token; your application configures discovery and refresh coordination.