Skip to main content

​
User Authorization (Tenant Registration)

The purpose of user authorization set up in the backend is for Upsolve AI to provide appropriate data access based on your user permissioning set up. In your product’s authentication flow, you will need to call the /register-tenant endpoint to authorize users/register tenants. This endpoint allows you to tell Upsolve AI who the authorized user is and what data permission they have via a payload. The endpoint is a “refresh” endpoint that consumes the payload and issues an one-hour short-lived JWT. This endpoint should be hit every time you re-authorize the user in your app. This JWT is then used to provide your authorized users the appropriate access to the agent and underlying data. Please refer to the documentation for the /register-tenant endpoint. You will need to call this endpoint in your auth flow.
To generate your API Key for the /register-tenant endpoint please go to the deploy page
Here is an example of doing this using Clerk middleware:
middleware.ts
// This example protects all routes including api/trpc routes
// Please edit this to allow other routes to be public as needed.
// See https://clerk.com/docs/references/nextjs/auth-middleware for more information about configuring your Middleware
export default authMiddleware({
async afterAuth(auth, req, evt) {
  console.log("Starting login");

  // Handle users who aren't authenticated
  ...

  // Register users to Upsolve
  if (auth.userId && auth.orgId) { // Use this if you need user and org id in your tenant
    console.log("Starting tenant registration");

    // Add Upsolve tenant registration
    const upsolvePayload = {
      displayName: auth.orgSlug, // The public display name for this tenant. Can be user's name, their org, or anything else
      key: auth.orgId, // Private tenant identifier. Could be user id, org id, or anything else
      prefilters: { // Column names to pre-filter raw data on
        store_id: Math.random() > 0.5 ? "1" : "2",
        organization_id: auth.orgSlug,
      },
      apiKey: "up_embed_3...bL9", // Make sure this begind with up_embed_
    };

    // Hit the endpoint
    const upsolveToken = await fetch(
      `https://api.upsolve.ai/v1/api/tenant/register-tenant`,
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        body: JSON.stringify(upsolvePayload),
      }
    ).then((res) => res.json())
     .then((data) => data?.["data"]?.["token"]); // Extract the JWT from the response

    // Save the JWT to the user's public metadata, to be used client side!
    await clerkClient.users.updateUser(auth.userId, {
      publicMetadata: { upsolveToken },
    });
    console.log(`Upsolve registration done`);
  }

  // If the user is logged in and trying to access a protected route, allow them to access route
  ...

  // Allow users visiting public routes to access them
  ...
},
});
When embedding an Application Space (via the https://ai-hub.upsolve.ai/share/application/:applicationId iFrame), you need a project user token rather than the standard tenant JWT. This token identifies a specific user within a project organisation and is used by the embed to load their personalised Space. This is the preferred authentication method for new integrations.

​
Endpoint

POST https://api.upsolve.ai/v1/api/projects/user-token

​
Request

FieldTypeRequiredDescription
userIdstring (UUID)YesThe project user’s ID (found in your project’s user list)
organizationIdstring (UUID)YesThe organisation ID the user belongs to
apiKeystringNoYour Upsolve embed API key (if not passed via Authorization header)
expirationnumberNoToken lifetime in seconds (default: 3600)

​
Response

{
  "data": {
    "token": "<short-lived JWT>"
  }
}

​
Example

const response = await fetch("https://api.upsolve.ai/v1/api/projects/user-token", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer up_embed_...", // Your embed API key
  },
  body: JSON.stringify({
    userId: "user-uuid-here",
    organizationId: "org-uuid-here",
  }),
});

const { data } = await response.json();
const projectUserToken = data.token;
Pass projectUserToken as the jwt query parameter in the Application iFrame src. See Frontend Setup for the full embed example.
Project user tokens expire after 1 hour by default. Refresh them server-side before they expire and update the iFrame src to avoid session interruptions.
The legacy /register-tenant endpoint still works. For organizations that have been migrated to hub2.5, it automatically returns project user tokens. New integrations should use POST /v1/api/projects/user-token directly.

​
Setup Inspection

You could inspect whether the user authorization is setup successfully. Navigate to the Deploy application using the side navigation bar. upsolve-deploy If the endpoint is successfully called, you should see your new tenants in the Deploy application: tenants