> ## Documentation Index
> Fetch the complete documentation index at: https://portkey-docs-feat-rerank-documentation.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Authorization
> Control what users can access at the MCP server and tool level.
Authorization determines what authenticated users can access. While [authentication](/product/mcp-gateway/authentication) verifies *who* a user is, authorization controls *what* they can do.
## Authorization Layers
MCP Gateway provides authorization at multiple levels:
| Level | What it controls | Status |
| -------------- | ------------------------------------------ | ----------- |
| **Workspace** | Which teams can access which MCP servers | Available |
| **MCP Server** | Access to specific servers based on claims | Available |
| **Tool** | Access to specific tools within a server | Coming soon |
***
## Server-Level Claim-Based Authorization
Control access to MCP servers based on JWT claims. This is configured through [JWT Validation](/product/mcp-gateway/authentication/jwt) using `requiredClaims` and `claimValues`.
### Require Specific Claims
Ensure tokens include specific claims before allowing access:
```json theme={"system"}
{
"jwt_validation": {
"jwksUri": "https://your-idp.com/.well-known/jwks.json",
"requiredClaims": ["sub", "email", "groups"]
}
}
```
If a token is missing any required claim, access is denied.
### Validate Claim Values
Authorize based on claim values—group membership, roles, or other attributes:
```json theme={"system"}
{
"jwt_validation": {
"jwksUri": "https://your-idp.com/.well-known/jwks.json",
"claimValues": {
"groups": {
"values": ["engineering", "platform"],
"matchType": "contains"
},
"iss": {
"values": "https://your-idp.com",
"matchType": "exact"
}
}
}
}
```
Users whose tokens don't match the required claim values receive an authorization error.
### Match Types
| Type | Description | Example |
| ------------- | ------------------------------------------ | ----------------------------------------------------- |
| `exact` | Claim value must match exactly | `iss` must equal `"https://your-idp.com"` |
| `contains` | Claim must include at least one value (OR) | User must be in `engineering` OR `platform` group |
| `containsAll` | Claim must include all values (AND) | User must have both `mcp:read` AND `mcp:write` scopes |
| `regex` | Match against a regular expression | Email must match `@yourcompany\.com$` |
### Example: Restrict to Engineering Team
Only allow users in the engineering group:
```json theme={"system"}
{
"jwt_validation": {
"jwksUri": "https://your-idp.com/.well-known/jwks.json",
"requiredClaims": ["sub", "groups"],
"claimValues": {
"groups": {
"values": ["engineering"],
"matchType": "contains"
}
}
}
}
```
### Example: Require Admin Role
Only allow users with admin role:
```json theme={"system"}
{
"jwt_validation": {
"jwksUri": "https://your-idp.com/.well-known/jwks.json",
"claimValues": {
"role": {
"values": "admin",
"matchType": "exact"
}
}
}
}
```
### Example: Restrict by Email Domain
Only allow users from your company domain:
```json theme={"system"}
{
"jwt_validation": {
"jwksUri": "https://your-idp.com/.well-known/jwks.json",
"claimValues": {
"email": {
"values": "@yourcompany\\.com$",
"matchType": "regex"
}
}
}
}
```
See [JWT Validation](/product/mcp-gateway/authentication/jwt) for complete configuration options.
***
## Tool-Level Authorization
Tool-level claim-based authorization is coming in a future release.
Fine-grained authorization at the tool level based on JWT claims. Control tool access by user attributes:
```json theme={"system"}
{
"tool_authorization": {
"delete_issue": {
"required_claims": {
"role": {
"values": ["admin", "maintainer"],
"matchType": "contains"
}
}
}
}
}
```
Enables scenarios like:
* Allow read tools for all users, write tools for specific roles
* Restrict dangerous operations to admins
* Enable different tool sets for different teams
***
## Webhooks for Authorization
Webhook-based authorization is coming in a future release.
Call your custom authorization service before each MCP request. Implement dynamic, context-aware access decisions.
```json theme={"system"}
{
"authorization_webhook": {
"url": "https://your-service.com/authorize",
"timeout_ms": 1000,
"on_error": "deny"
}
}
```
Your webhook will receive:
* User identity and claims
* Target MCP server
* Tool being called
* Request parameters
Return `allow` or `deny` with an optional reason.
Enables:
* Dynamic authorization based on external systems
* Context-aware decisions (time of day, request patterns)
* Integration with existing authorization infrastructure
* Custom business logic for access control
***
## Combining with Team Provisioning
Authorization works alongside [Team Provisioning](/product/mcp-gateway/access-control):
1. **Team Provisioning** controls which workspaces see which servers
2. **JWT Validation** adds claim-based rules on top
A user must pass both checks to access an MCP server.
```
User Request
│
▼
┌─────────────────────────────┐
│ Team Provisioning Check │ Is server provisioned to user's workspace?
└─────────────────────────────┘
│ ✓
▼
┌─────────────────────────────┐
│ JWT Claim Validation │ Does token have required claims/values?
└─────────────────────────────┘
│ ✓
▼
Access Granted
```
***
## Next Steps
Configure claim validation for authorization.
Control workspace access to MCP servers.
Pass user identity to MCP servers for downstream authorization.
Enable or disable specific tools.