Access Scopes - API Reference

Reading with an LLM? Give it this page as Markdown: https://nolag.app/docs/scopes/api-reference.md

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

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

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

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

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

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

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 - create your first scope
Concepts - understand how scopes work under the hood
Multi-Tenancy Patterns - real-world usage patterns