Skip to main content

Manage Builder Portal Access

Tasks

Procedures for signing in to the Builder Portal and managing your access tokens, connected accounts, sessions, and policy exceptions.

Accessing the portal​

  1. Go to your workspace URL.
  2. Sign in with your developer credentials. The Builder Portal opens by default — no admin role is required.
note

Admins also have access to the Builder Portal from the same workspace.

Password-login tokens are no longer saved in browser local storage. Admin portal sessions resume through the server's HttpOnly cookie. Builder password-login tokens stay in memory, so reloading that page may require signing in again. Existing local-storage tokens are removed when the UI next checks login state.

Signing in to the Builder Portal, with a password, an email verification code or SSO, doesn't start or end an AI session. Sessions already running in your AI tools keep going. A password or email-code sign-in lasts up to the configured UI session length (ui.sessionTTLHours, 8 hours by default); an SSO sign-in lasts up to 8 hours.

Sign in with SSO​

  1. Open your workspace's Builder Portal at /ui/dev/login.
  2. Select Sign in with SSO.
  3. Authenticate with your organization's identity provider using the email in your invitation.

If your administrator has already created your account, sign-in uses that account and preserves its assigned team. Otherwise, your first successful SSO sign-in creates a Builder account. Its teams come from your identity provider groups, as described in Place new builders in teams from identity provider groups. When none of your groups is bound to a team, the account follows the no-match setting described there; by default it lands in the Default team.

Place new builders in teams from identity provider groups​

When someone signs in with SSO for the first time, AIControls reads the groups claim from the validated token and matches each value against your team group bindings (Settings → Teams). Matching is exact: AIControls compares the value your identity provider emits with the bound value, character for character. It does not look up display names.

  1. In your identity provider, put the intended developers in a group and configure the sign-in application to emit group memberships in the token. On Microsoft Entra ID, emitted groups are object IDs (GUIDs), not display names. Copy the group's Object ID from Entra ID → Groups.
  2. Under Setup → Settings → SSO / OIDC, set Groups Claim to the claim that carries the groups (for example groups). This setting only selects which token field to read. It does not create the group, fill its membership, or map it to a team.
  3. Under Settings → Teams, bind the emitted value (the object ID, on Entra) to the team that owns the model access, budgets, and policies those developers need.

For a new account:

  • One or more groups match. The account is created in every matching team. The primary team, which is the team AIControls attributes activity to, is the team you picked on the team selection page if you picked one that matched. Otherwise it is the matching team whose ID sorts first in byte order (plain code-point comparison, not locale or human alphabetical order). Uppercase letters sort before lowercase, so Zeta is chosen over alpha, and team-10 over team-2. The order of values in the token never changes the result.
  • No group matches, or the token carries no groups. The no-match setting (autoProvisionFallback, see OIDC provider fields) decides: default places the account in the Default team (the behavior when the setting is empty), none creates the account with no team, and deny refuses the sign-in. With deny, no session, token, or access token is issued and the sign-in page tells the person to ask an administrator to bind one of their groups to a team. Use deny for a controlled rollout so a binding mistake is visible immediately.
  • Seat limit. A new account still needs a free seat. When none is free, sign-in is refused with a seat limit message.
  • Role. Team membership never grants console access. New accounts are Builders, and the optional identity provider role mapping still decides the final role.

Only the first sign-in places an account. An account that already exists, whether created by an administrator or by an earlier sign-in, keeps its teams and primary team on every later sign-in, including accounts an earlier sign-in placed in the Default team. Reassign those from the user's page.

Groups missing from the token

Microsoft Entra omits the group list when a user belongs to too many groups (a group overage) and emits a pointer to the Graph API instead. AIControls does not call Graph and does not read that pointer, so such a token looks like a token with no groups and follows the no-match setting. Restrict the groups the application emits, for example to groups assigned to the application, so the token carries the full list.

Invite a builder with SSO​

Before you invite users, configure browser sign-in under Setup → Settings → SSO / OIDC. Your identity provider must allow the invited user's email. Set ui.publicURL in your deployment configuration to the externally accessible UI base URL (for example, https://aicontrols.example.com). Invitations require this address; the SSO callback can use a different proxy port and cannot determine the portal address.

  1. Open Setup → Settings → Users and select Add User.
  2. Enter the user's email and display name, select the Builder role, and assign a team.
  3. Select SSO under Authentication. When Builder SSO is configured, this is the default.
  4. Select Create. The invitation contains a sign-in link without a temporary password. You can copy the invitation message if email delivery is unavailable.

Select Local password instead to create an account with a temporary password.

These invitation and conversion actions require locally managed users. If the Users page reports that accounts are managed externally (including deployments using admin console SSO), manage those accounts through your identity provider. AIControls does not create or convert local accounts in that mode.

Convert a local account to SSO only​

  1. Confirm that the user can sign in with SSO using the same email address as their existing account.
  2. Open Setup → Settings → Users and edit the user.
  3. Select Convert to SSO only and confirm.

The user's password stops working, and password reset cannot enable password sign-in again. The account, team, history, existing sessions, and access tokens are preserved. This action does not sign out existing sessions or revoke tokens.

The Source column identifies how an account was provisioned, or shows SSO after conversion. The Authentication column shows the available sign-in methods. A local account can use both password and SSO when SSO is configured. An SSO-only account shows SSO unavailable if SSO is later disabled for its role; restore the SSO configuration to allow new sign-ins.

Last Login records password and SSO sign-ins. Not recorded means no timestamp is stored; SSO sign-ins from older versions might not have been recorded. A Local source label does not mean the user signs in with a password. Check gateway request activity separately when verifying that an AI tool is connected.

Changing an SSO-only account's role requires SSO to be configured for the destination role and email.

Self-registration​

If your organization allows self-registration for your email domain, you can create your own account without an admin invite:

  1. Go to your workspace URL and choose Sign up.
  2. Enter your work email. If it's on an allowed domain, you'll receive a 6-digit verification code by email.
  3. Enter the code along with a password (at least 8 characters) to finish creating your account.
note

Verification codes expire after 10 minutes and allow a limited number of attempts. If you enter the wrong code too many times, wait for the code to expire and request a new one — repeated attempts don't unlock it early.

Access tokens​

Create a token​

  1. Go to Access Tokens and click Create New Token.
  2. Give the token a name that identifies the tool or machine (e.g. claude-code-macbook).
  3. Select an expiry: 30, 60, 90, 180, or 365 days.
  4. Click Create. The token is shown once — copy it immediately. It cannot be retrieved again.
warning

The token value is only shown at creation time. If you lose it, revoke and create a new one.

To revoke a token, click Revoke next to it in the Access Tokens list. On the AIControls replica that handles the revoke, the token stops working immediately. Each replica caches a validated token for up to 30 seconds, so with more than one replica, other replicas can accept it for up to 30 seconds more. A change to a token's allowed models follows the same timing. A newly created token works at once on every replica. The aicontrols_pat_cache_hits_total and aicontrols_pat_cache_misses_total Prometheus counters show how often the cache answered.

Connect your AI tool​

The Builder Portal Setup wizard and the Access Tokens tab offer the same client setup instructions.

  1. In the setup wizard, continue to Connect your AI tool. If you already completed or skipped the wizard, create a token on the Access Tokens tab.
  2. Choose Claude / Anthropic, Codex / OpenAI, GitHub Copilot, or Azure OpenAI.
  3. When both authentication methods are available for your product, choose the organization credential or your own provider credential. The organization credential is selected by default.
  4. Follow the instructions for your product: Claude settings or shell variables, Codex authentication and configuration files, the AIControls VS Code extension for Copilot, or Azure shell variables.
  5. For Claude, the wizard offers an optional Install Skills step. For other products, click Open my portal after configuring your tool.

If neither connection method is configured, ask your administrator to configure an LLM upstream or enable passthrough mode. Setup instructions appear once a connection method is available.

See the Claude Code, Cursor, Codex, or GitHub Copilot pages for tool-specific details.

Sessions and projects​

Sessions and Projects are described in Builder Portal. The one action available here: open a session's detail drawer to end an active or degraded session.

Connected accounts​

Manage a stored credential​

  1. Go to Connected Accounts.
  2. Find the datasource under Stored credentials.
  3. Click Connect (if not yet connected) or Update (to refresh an expired or existing credential).

Configure a client-side credential​

  1. Go to Connected Accounts and find the datasource under Client-configured credentials.
  2. Click View Config to generate the client configuration snippet for that datasource.
  3. Add the header shown to your AI tool's configuration. AIControls does not store these credentials.

Policy exceptions​

  1. Go to My Requests to see the status of every model-access, exception, and session-resume request you've submitted, and every policy exception currently granted to you — each with its expiry date.
  2. To request a new exception, use the Request Exception → link next to the relevant finding on your Overview tab. Fill in the policy and a justification and submit — you cannot create the exception yourself; an admin still has to approve it.

Some requests need more than one approver to sign off before they take effect — see Single- vs multi-approver co-sign. While that's pending, your request shows as Under Review on My Requests; you'll be notified as soon as it's fully approved or if any approver denies it.

See also​

Email delivery validation​

Notification and sign-in emails require each recipient to be a single email address. Direct sends reject empty recipient lists, and any invalid address causes delivery to fail before contacting the mail server. Notification integrations intentionally skip delivery when no static or event recipient resolves. User-provided values and product names are displayed as text, including ampersands and angle brackets. ASCII control characters are removed from email subjects before header encoding.

Dashboard, review, setup, and footer links use the same URL validation. Complete action links may include queries and fragments; executable schemes, embedded credentials, invalid ports, and control characters are rejected.

Configured public URL bases must be absolute HTTP/HTTPS URLs without queries or fragments, and must name an address other machines can reach: a base that names this machine (such as localhost, 127.0.0.1, ::1, or 0.0.0.0) is treated as unset. Email renderers use local application paths when the base is invalid, but this does not guarantee scheduled delivery: weekly, daily, and monthly developer digests skip sending, and coaching-tip email delivery is disabled, until a valid public URL is configured. Valid URL paths retain their ampersands.

Email integrations require a valid sender. An integration with its own SMTP host can inherit the shared sender address and port without inheriting shared SMTP credentials. An explicitly configured integration port takes precedence. The integration test endpoint applies the same shared SMTP defaults as normal registration. Missing or invalid senders are reported when the integration is constructed, rather than on every delivery. OTP emails preserve a configured sender display name; a bare sender address uses the product name instead.

Welcome and setup emails use the operator-configured ui.publicURL and identity.developerAuth.proxyURL. They do not derive destinations from request host headers. If no public URL is configured, the welcome email omits its sign-in link; use your workspace URL directly or ask the operator to configure it.

Last updated on