Authentication

All MCP Tools & Servers API requests require authentication. This page covers the supported authentication methods, organization scoping, and authorization model for the MCP Tools & Servers API.

Service Key Authentication

The primary authentication method is a Nexla service key passed as a Bearer token in the Authorization header. Service keys are org-scoped and do not expire unless revoked.

Authorization: Bearer <NEXLA_SERVICE_KEY>

See Service Keys for instructions on generating and managing service keys.

Example request:

curl -X GET https://api-genai.nexla.io/v1/tools \
  -H "Authorization: Bearer nxl_sk_abc123..."

A successful authenticated request returns the expected resource. If the service key is missing or invalid, the API returns a 401 Unauthorized response.

Organization Scoping

All resources are scoped to the authenticated user's organization. The org_id is extracted from the JWT claims of the resolved session token. Users can only access tools, toolsets, and servers that belong to their organization.

This means:

• A GET /v1/tools request returns only the tools within the caller's org.
• Creating a tool associates it with the caller's org automatically.
• Cross-org access is not supported through the API.

Token Exchange

Behind the scenes, service keys are exchanged for session tokens via the Nexla API. The service handles this exchange automatically — callers do not need to perform the exchange manually.

Session tokens are cached for performance, so repeated API calls within the token's validity window do not trigger additional round-trips to the Nexla auth service.

OAuth Authentication (MCP Endpoints)

MCP server endpoints support OAuth for user-facing AI agents. This is the recommended authentication method when an end-user's identity must flow through to the MCP server.

Google OAuth

MCP URL pattern:

/mcp/oauth/google/{server_key}

Requires Google OAuth app credentials configured on the MCP server. The server handles the full OAuth 2.0 authorization code flow, including token refresh.

Azure OAuth

MCP URL pattern:

/mcp/oauth/azure/{server_key}

Requires an Azure AD app registration with the appropriate redirect URIs configured on the MCP server.

OAuth Discovery

MCP endpoints expose standard OAuth discovery documents for automated client configuration:

Method	Path	Description
GET	/.well-known/oauth-authorization-server/{path}	OAuth authorization server metadata
GET	/.well-known/oauth-protected-resource/{path}	OAuth protected resource metadata

These endpoints allow MCP-compatible clients to automatically discover authorization endpoints, token endpoints, and supported grant types.

Authorization

Within an organization, access to individual resources follows Nexla's role-based access model. Tool operations require the appropriate Nexset role:

Role	Permitted Operations
Collaborator	Create tools from Nexsets
Operator	Execute tools, activate, pause
Admin	Update tool metadata, delete tools

Higher roles inherit the permissions of lower roles. An Admin can perform all Operator and Collaborator operations.

Error Responses

Authentication and authorization failures return standard error responses:

HTTP Status	Error Code	Meaning
401 Unauthorized	UNAUTHORIZED	Missing, invalid, or expired authentication token
403 Forbidden	FORBIDDEN	Valid token but insufficient access to the resource

Example 401 response:

{
  "error_code": "UNAUTHORIZED",
  "message": "Invalid or expired authentication token",
  "details": {}
}

Example 403 response:

{
  "error_code": "FORBIDDEN",
  "message": "Insufficient permissions to execute tool 42",
  "details": {}
}