---
title: Access Scopes - API Reference
description: Complete API reference for Access Scopes endpoints. Create, list, get, update, and delete scopes. List actors assigned to a scope.
---

# Access Scopes - API Reference

Complete reference for all Access Scope REST API endpoints.

All endpoints use the base path:\
`https://api.nolag.app/v1/scopes`

Authentication is required via `Authorization: Bearer <api-key>` header. Use a project-scoped API key (`nlg_live_...`). The project context is determined by the API key.

## Create Scope

`POST /v1/scopes`

### Request Body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | Yes | URL-safe identifier. Used in topic namespacing. Immutable after creation. |
| `name` | string | No | Human-readable display name. |

### Response: 201 Created

```typescript [TypeScript]
const response = await fetch(
  `https://api.nolag.app/v1/scopes`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      slug: "client-acme",
      name: "Acme Corporation",
    }),
  }
);

// Response: 201 Created
// {
//   "accessScopeId": "01HZ...",
//   "slug": "client-acme",
//   "name": "Acme Corporation",
//   "createdAt": "2026-05-20T10:00:00.000Z",
//   "updatedAt": "2026-05-20T10:00:00.000Z"
// }
```

## List Scopes

`GET /v1/scopes`

### Query Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `page` | number | 1 | Page number for pagination. |
| `limit` | number | 10 | Number of results per page (max 100). |
| `orderBy` | string | createdAt:DESC | Sort order. Example: `slug:ASC` |

### Response: 200 OK

```typescript [TypeScript]
const response = await fetch(
  `https://api.nolag.app/v1/scopes?page=1&limit=10`,
  {
    headers: {
      "Authorization": `Bearer ${apiKey}`,
    },
  }
);

// Response: 200 OK
// {
//   "data": [
//     { "accessScopeId": "01HZ...", "slug": "client-acme", "name": "Acme Corporation", ... },
//     { "accessScopeId": "01HZ...", "slug": "client-beta", "name": "Beta Corp", ... }
//   ],
//   "meta": { "page": 1, "limit": 10, "total": 2, "totalPages": 1 }
// }
```

## Get Scope

`GET /v1/scopes/:scopeId`

### Path Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `scopeId` | UUID | The Access Scope ID. |

### Response: 200 OK

```typescript [TypeScript]
const response = await fetch(
  `https://api.nolag.app/v1/scopes/${scopeId}`,
  {
    headers: {
      "Authorization": `Bearer ${apiKey}`,
    },
  }
);

// Response: 200 OK
// {
//   "accessScopeId": "01HZ...",
//   "slug": "client-acme",
//   "name": "Acme Corporation",
//   "createdAt": "2026-05-20T10:00:00.000Z",
//   "updatedAt": "2026-05-20T10:00:00.000Z"
// }
```

## Update Scope

`PATCH /v1/scopes/:scopeId`

### Request Body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | No | Updated display name. The `slug` field cannot be updated. |

### Response: 200 OK

```typescript [TypeScript]
const response = await fetch(
  `https://api.nolag.app/v1/scopes/${scopeId}`,
  {
    method: "PATCH",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Acme Corp (Renamed)",
      // Note: slug CANNOT be updated after creation
    }),
  }
);

// Response: 200 OK
// {
//   "accessScopeId": "01HZ...",
//   "slug": "client-acme",
//   "name": "Acme Corp (Renamed)",
//   "createdAt": "2026-05-20T10:00:00.000Z",
//   "updatedAt": "2026-05-20T12:00:00.000Z"
// }
```

## Delete Scope

`DELETE /v1/scopes/:scopeId`

Deleting a scope will remove the scope assignment from all actors currently assigned to it. Those actors will become unscoped and revert to the default topic namespace.

### Response: 204 No Content

```typescript [TypeScript]
const response = await fetch(
  `https://api.nolag.app/v1/scopes/${scopeId}`,
  {
    method: "DELETE",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
    },
  }
);

// Response: 204 No Content
// All actors previously assigned to this scope will have their
// accessScopeId set to null (unscoped).
```

## List Actors in Scope

`GET /v1/scopes/:scopeId/actors`

Returns all actors currently assigned to this scope. Supports pagination.

### Query Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `page` | number | 1 | Page number for pagination. |
| `limit` | number | 10 | Number of results per page (max 100). |

### Response: 200 OK

```typescript [TypeScript]
const response = await fetch(
  `https://api.nolag.app/v1/scopes/${scopeId}/actors?page=1&limit=10`,
  {
    headers: {
      "Authorization": `Bearer ${apiKey}`,
    },
  }
);

// Response: 200 OK
// {
//   "data": [
//     { "actorId": "01HZ...", "name": "user-alice", "accessScopeId": "01HZ...", ... },
//     { "actorId": "01HZ...", "name": "user-bob", "accessScopeId": "01HZ...", ... }
//   ],
//   "meta": { "page": 1, "limit": 10, "total": 2, "totalPages": 1 }
// }
```

## Response Schemas

### AccessScope

| Field | Type | Description |
| --- | --- | --- |
| `accessScopeId` | UUID | Unique identifier for the scope. |
| `slug` | string | URL-safe identifier used in topic namespacing. Immutable. |
| `name` | string \| null | Human-readable display name. |
| `createdAt` | ISO 8601 | Timestamp when the scope was created. |
| `updatedAt` | ISO 8601 | Timestamp of the last update. |

### Error Responses

| Status | Description |
| --- | --- |
| `400` | Invalid request body or parameters (e.g., missing slug, invalid UUID). |
| `401` | Missing or invalid authentication. |
| `404` | Scope, project, or organization not found. |
| `409` | Slug already exists within this project. |

## Next Steps

- [Getting Started](/docs/scopes/getting-started) - create your first scope
- [Concepts](/docs/scopes/concepts) - understand how scopes work under the hood
- [Multi-Tenancy Patterns](/docs/scopes/multi-tenancy) - real-world usage patterns