# CanActivate

**Kind:** Interface

**Source:** [`packages/common/interfaces/features/can-activate.interface.ts`](https://github.com/nestjs/nest/blob/master/packages/common/interfaces/features/can-activate.interface.ts#L14)

**Part of:** [Common](subsystem-packages-common)

Interface defining the `canActivate()` function that must be implemented
by a guard.  Return value indicates whether or not the current request is
allowed to proceed.  Return can be either synchronous (`boolean`)
or asynchronous (`Promise` or `Observable`).

`CanActivate` defines the contract for guards that determine whether an incoming request may continue to a route handler. Implementations inspect the current `ExecutionContext` and return `true` or `false`, either synchronously or through a `Promise` or `Observable`.

## Diagram

```mermaid
graph LR
  Request[Incoming Request] --> Guard[CanActivate Guard]
  Guard --> Context[ExecutionContext]
  Context --> Guard
  Guard --> Decision{canActivate() result}
  Decision -->|true| Handler[Route Handler]
  Decision -->|false| Denied[Request Denied]
```

## Usage

```ts
import {
  CanActivate,
  ExecutionContext,
  Injectable,
} from '@nestjs/common';

@Injectable()
export class ApiKeyGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const request = context.switchToHttp().getRequest();
    const apiKey = request.headers['x-api-key'];

    return apiKey === process.env.API_KEY;
  }
}

// Apply the guard to a controller or route:
// @UseGuards(ApiKeyGuard)
```

## AI Coding Instructions

- Implement `canActivate(context: ExecutionContext)` on every guard that uses this interface.
- Return a `boolean`, `Promise<boolean>`, or `Observable<boolean>`; do not return response objects or throw for ordinary authorization failures.
- Use `ExecutionContext` to access the correct transport context, such as `switchToHttp()`, `switchToWs()`, or `switchToRpc()`.
- Return `false` to deny access; Nest handles the resulting forbidden response unless custom exception behavior is required.
- Register guards with `@UseGuards()` or configure them as global guards through the application provider setup.

## Used by

22 references from 22 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.

### Imported by (22)

- `ParamProperties` — `packages/core/router/router-execution-context.ts`:50
- `AuthGuard` — `integration/graphql-code-first/src/common/guards/auth.guard.ts`:9
- `CatsGuard` — `integration/graphql-schema-first/src/cats/cats.guard.ts`:4
- `Guard` — `integration/inspector/src/circular-hello/guards/request-scoped.guard.ts`:9
- `RolesGuard` — `integration/inspector/src/common/guards/roles.guard.ts`:4
- `Guard` — `integration/scopes/src/circular-hello/guards/request-scoped.guard.ts`:9
- `Guard` — `integration/scopes/src/circular-transient/guards/request-scoped.guard.ts`:9
- `DurableGuard` — `integration/scopes/src/durable/durable.guard.ts`:9

…and 14 more.