Authentication and authorization model

Use this model to predict which identity and permission Agent Studio evaluates for a request. Authentication establishes the caller; authorization then depends on the route, resource ownership, organization membership, skill permission, or API-key scope.

Request boundary

Route protection is the first boundary. A valid API key is not a universal substitute for a Clerk session: only handlers that use API-key middleware accept it. Likewise, a valid session does not by itself grant access to every resource.

Authentication methods

Clerk sessions

Dashboard and session-protected API routes obtain a Clerk userId. If no session exists, those routes return 401 Authentication required. Session identity is then evaluated against ownership or role-based access control (RBAC).

When a handler uses the mixed authentication middleware, Agent Studio checks for an API key first and falls back to the Clerk session only when no key is supplied. Therefore, sending an invalid key alongside a valid session produces an API-key authentication failure instead of a session fallback.

API keys

Supported handlers can extract an API key from X-API-Key, an Authorization: Bearer header, or the api_key query parameter. A validated key supplies a key ID, an organization ID, and scopes to the handler.

API-key callers need the explicit required scope or the wildcard *. A missing scope returns 403. Session callers pass the middleware's scope check, but the handler can still apply resource or organization authorization.

Authorization layers

The authorization decision narrows from tenant membership to the target resource:

For a skill outside an organization, only its owner receives skill access through this model. For an organization skill, organization owners and administrators receive full skill permissions. Other members depend on their assigned skill permissions; a nonmember receives none.

Skill permissions are hierarchical. Administrator is the highest level, followed by editor, executor, and viewer. A route that calls requireSkillPermission rejects a caller whose effective set does not include the required capability.

Public exceptions

Some discovery and operational routes intentionally have no Clerk check. /api/health returns basic process liveness, and /api/a2a/manifest publishes the A2A server manifest with auth.type set to none and cross-origin GET access.

Public does not mean readiness or broad authorization. The health response contains no dependency status, and the A2A manifest describes endpoints rather than granting access to unrelated dashboard or REST routes. Evaluate each endpoint's documented contract separately.

Interpret failures

• 401 means Agent Studio could not establish an acceptable identity, such as a missing Clerk session or an invalid or expired API key.
• 403 means the identity is known but lacks access, a required role, a skill permission, or an API-key scope.
• 404 can mean that the resource does not exist; do not use it as proof of an authorization failure without the route's contract.

When access is denied, first identify whether the request used a session or an API key. Then check the organization, resource owner, required permission, and—only for API-key-aware handlers—the required scope.

Apply the model

Use Manage organizations and Manage members for tenant membership. Configure roles through Manage roles and permissions, skill-level access through Configure skill permissions, and machine credentials through Manage API keys.

For endpoint-specific authentication and error envelopes, continue to API authentication, errors, and limits. Administrators can review security-relevant changes in Review audit events.