> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# IFGAProvider

The `IFGAProvider` interface defines a fine-grained authorization (FGA) provider. Mastra calls it to decide whether a user or a system actor may perform a permission on a specific resource. Implement it to connect Mastra to an FGA backend, such as WorkOS Authorization.

For concepts, configuration, and the lifecycle points where Mastra enforces FGA, see [Fine-grained authorization](https://mastra.ai/docs/auth/fga).

## Usage example

The following example implements a minimal provider. `require` throws to deny, and `check` returns a boolean.

```typescript
import { FGADeniedError } from '@mastra/core/auth/ee'
import type { FGACheckParams, IFGAProvider, MastraFGAPermissionInput } from '@mastra/core/auth/ee'

class MyFGAProvider implements IFGAProvider {
  async check(user: any, params: FGACheckParams): Promise<boolean> {
    // Your authorization logic.
    return true
  }

  async require(user: any, params: FGACheckParams): Promise<void> {
    if (!(await this.check(user, params))) {
      throw new FGADeniedError(user, params.resource, params.permission)
    }
  }

  async filterAccessible<T extends { id: string }>(
    user: any,
    resources: T[],
    resourceType: string,
    permission: MastraFGAPermissionInput,
  ): Promise<T[]> {
    return resources
  }
}
```

## Methods

### `check(user, params)`

Returns whether `user` has the permission on the resource. Use it for non-throwing checks, such as filtering or conditional UI.

Returns: `Promise<boolean>`

### `require(user, params)`

Throws `FGADeniedError` when `user` lacks the permission. Mastra calls this at its [enforcement points](https://mastra.ai/docs/auth/fga).

Returns: `Promise<void>`

### `filterAccessible(user, resources, resourceType, permission)`

Returns the subset of `resources` that `user` can access with `permission`.

Returns: `Promise<T[]>`

### `requireActor(actor, params)`

Authorizes a non-user system actor, such as an autonomous or scheduled agent. Optional.

System actors skip the user-centric `require()` path, so implement `requireActor` to enforce per-agent least privilege for them. Throw `FGADeniedError` to deny. When a provider doesn't implement `requireActor`, Mastra preserves the trusted-actor bypass (allow after the tenant-scope check), so adding the method remains backward compatible.

Treat `actor.permissions` as an untrusted claim. Resolve the agent's authoritative grants from a trusted source keyed by `actor.agentId`, rather than trusting the inline values. See [System actors](https://mastra.ai/docs/auth/fga).

```typescript
import { FGADeniedError } from '@mastra/core/auth/ee'
import type { ActorSignal, FGACheckParams, IFGAProvider } from '@mastra/core/auth/ee'

class MyFGAProvider implements IFGAProvider {
  // ...check, require, filterAccessible...

  async requireActor(actor: ActorSignal, params: FGACheckParams): Promise<void> {
    const agentId = actor === true ? undefined : actor.agentId
    // Resolve the agent's authoritative grants from a trusted source keyed by agentId.
    const granted = await this.grantsForAgent(agentId)
    const required = Array.isArray(params.permission) ? params.permission : [params.permission]
    if (!required.some(permission => granted.includes(permission))) {
      throw new FGADeniedError(null, params.resource, params.permission)
    }
  }
}
```

Returns: `Promise<void>`

## Configuration properties

Optional properties control route coverage and startup validation.

**requireForProtectedRoutes** (`boolean`): When true, protected routes without route-level FGA metadata or resolver output are denied instead of allowed through. (Default: `false`)

**auditProtectedRoutes** (`boolean | 'warn' | 'error'`): Audits protected routes that lack built-in FGA metadata. Use true or 'warn' to log a startup warning, 'error' to fail startup, or false to disable. (Default: `false`)

**resolveRouteFGA** (`FGARouteResolver`): Derives resource type, resource ID, and permission from the route, parsed params, and request context.

**validatePermissions** (`(permissions: MastraFGAPermissionInput[]) => void | Promise<void>`): Startup validation for provider-specific permission mappings. Throw when a permission Mastra may emit is not mapped.

## Parameters

The `params` argument passed to `check`, `require`, and `requireActor`.

**resource** (`{ type: string; id: string }`): The resource being accessed.

**permission** (`MastraFGAPermissionInput | MastraFGAPermissionInput[]`): The permission(s) being checked. When an array is provided, the actor needs any one of the listed permissions.

**context** (`FGACheckContext`): Provider-specific context for resource resolution, including the owning resourceId, the request context, and action metadata.

## `ActorSignal`

Identifies a call made by a trusted non-user actor rather than an authenticated end user. It's either `true` (the anonymous system shorthand) or an object that names the acting agent and carries the grants a provider can enforce.

**actorKind** (`'system'`): Marks the object form of the signal.

**agentId** (`string`): Identity of the acting system agent. Unlike the check resource (the target), this names the actor itself, so a provider can enforce per-agent least privilege.

**permissions** (`MastraFGAPermissionInput[]`): Permission grants claimed for this actor. This is an untrusted, self-asserted hint; a provider enforcing real least privilege resolves the agent's authoritative grants from a trusted source keyed by agentId rather than trusting these values.

**scope** (`Record<string, string>`): Additional provider-specific scope for the actor, for example tenant or environment.

**sourceWorkflow** (`string`): Name of the workflow that started the actor run, when applicable.

**propagate** (`boolean`): Forwards this actor into the agent and tool calls the framework makes for the run's declarative .then(agent) and .then(tool) steps. Custom step execute functions aren't covered and must pass actor explicitly. Ignored by authorization itself. (Default: `false`)

## `FGADeniedError`

Thrown when an authorization check is denied. `require` and `requireActor` throw it to deny, and Mastra surfaces it as an HTTP `403`.

```typescript
import { FGADeniedError } from '@mastra/core/auth/ee'

throw new FGADeniedError(user, { type: 'agent', id: 'reporter' }, 'agents:execute')
// Optional fourth argument: a reason string included in the error message.
```

## Related

- [Fine-grained authorization](https://mastra.ai/docs/auth/fga)
- [System actors](https://mastra.ai/docs/auth/fga)
- [WorkOS authentication](https://mastra.ai/reference/auth/workos)