How To Authenticate
The hosted Neo4j Agent Memory Service supports two authentication flows:
-
Static
nams_*API keys — issued via the dashboard, expire in 90 days. -
OAuth 2.0 PKCE — short-lived JWT access tokens with refresh.
Every client SDK accepts either through the same apiKey / tokenProvider
configuration knobs.
Static API keys
Set the Authorization: Bearer nams_* header on every request.
curl -H "Authorization: Bearer $MEMORY_API_KEY" \
https://memory.neo4jlabs.com/v1/entitiesIn the SDKs:
- TypeScript
-
new MemoryClient({ endpoint: "https://memory.neo4jlabs.com/v1", apiKey: process.env.MEMORY_API_KEY, }) - Python
-
MemoryClient( endpoint="https://memory.neo4jlabs.com/v1", api_key=os.environ["MEMORY_API_KEY"], ) - Go
-
memory.New( memory.WithEndpoint("https://memory.neo4jlabs.com/v1"), memory.WithAPIKey(os.Getenv("MEMORY_API_KEY")), )
Managing keys via the SDK
All five clients expose an auth (or Auth) sub-client mirroring
/v1/auth/api-keys:
// List keys for a workspace.
const keys = await client.auth.listApiKeys(workspaceId);
// Create a new key. Plaintext is returned ONCE — store it now.
const fresh = await client.auth.createApiKey({
label: "ci-runner",
scopes: ["read", "write"],
workspaceId,
});
console.log(fresh.key); // nams_...
// Revoke immediately.
await client.auth.revokeApiKey(fresh.id);OAuth refresh-token rotation
Static keys are convenient but coarse. For long-running services, prefer the OAuth flow:
-
Exchange your IdP token at
POST /v1/auth/exchangeto receive{access_token, refresh_token, expires_in}. -
Use the access token like a static key.
-
Before it expires, call
auth.refreshAccessToken(refresh_token)to rotate.
The clients support a tokenProvider callback so you can plug your refresh
logic in once and forget it:
new MemoryClient({
endpoint: "https://memory.neo4jlabs.com/v1",
tokenProvider: async () => myTokenStore.getFreshAccessToken(),
})async def get_token() -> str:
return await my_token_store.get_fresh_access_token()
MemoryClient(
endpoint="https://memory.neo4jlabs.com/v1",
token_provider=get_token,
)