Custom Authn & Authz

​

Why Custom Auth?

When building front-end applications that interact with LLMs, you face two key security challenges:

• Privilege Escalation: Ensuring the LLM can only access data the user is authorized to see/modify
• API Key Protection: Preventing exposure of sensitive API keys in client-side code

​

The Challenge

Consider this example function that updates a user’s address:

client.default.register({
  name: "updateAddress",
  input: {
    schema: z.object({
      userId: z.string(),
      address: z.string(),
    }),
  },
  func: async (input) => {
    await db.exec("UPDATE users SET address = $1 WHERE id = $2", [
      input.address,
      input.userId,
    ]);
  },
});

Without proper authentication:

• A malicious user could trick the agent into calling this function with any user ID
• The agent could be manipulated to perform unauthorized operations

​

Implementing Custom Auth

Custom auth provides a secure way to:

1. Validate user identity and permissions outside the agent’s control
2. Automatically apply auth context to all function calls in a run

​

Implementation Guide

client.default.register({
  name: "handleCustomAuth",
  func: async (input) => {
    // Validate the token and return user context
    const user = await validateUserToken(input.token);
    return {
      // Required
      userId: user.id,

      // Optional, arbitrary auth context
      role: user.role,
    };
  },
  schema: {
    input: handleCustomAuth,
  },
});

client.default.register({
  name: "getUserData",
  func: (input, context) => {
    const { userId } = context.authContext;
    // Only access data for authenticated user
    return db.getUserData(userId);
  },
});

​

Validation Flow

1. When a run is created with a custom token, handleCustomAuth is called first
2. If validation succeeds, the returned context is available to all functions
3. If validation fails, the run is rejected
4. All subsequent function calls receive the validated auth context

​

Flow Diagram

This diagram shows the flow of a run with custom auth.

​

About the handleCustomAuth function

The handleCustomAuth function is a special function that is used to validate tokens and return auth context. It is called when a run is created with a custom token.

The function must return a JSON-serializable object containing a userId property.

If the function throws an error, the run will be rejected.

Without a valid handleCustomAuth function, runs created with custom auth tokens will fail.

​

Implementing custom authorization

It is up to the developer to implement custom authorization logic. The recommended approach is to use the returned context.authContext object in your functions to validate the user’s permissions.

​

userId Property

It is the responsibility of the handleCustomAuth function to validate the provided token and return an object containing a userId property. This property will be used to identify the user associated with the token and any Runs created with it.

This identifier should represent a user and be stable between token / session refreshes.

Listing Runs using a custom auth token will be limited to Runs with the same userId.

​

Important Notes

• A Run created with a custom auth token can only be managed with a token which produces the same userId (or a cluster API key).
• Custom auth tokens are not compatible with Cluster API keys.

​

Related Pages