Scopes & Permissions

The Scopes resource lets you query API key permissions and understand the full permission model.

Get Allowed Scopes

Returns the scopes/permissions granted to the currently authenticated API key.

Endpoint: GET /api/sdk/v1/scopes-allowed

Response (AllowedScopesResponse)

Field	Type	Description
keyPrefix	string	The API key prefix (e.g., 'sk_live')
name	string	Human-readable name of the API key
scopes	string[]	Array of granted scope strings

const { keyPrefix, name, scopes } = await sdk.scopes.getAllowed();

console.log(`API Key: ${name} (${keyPrefix})`);
console.log('Granted scopes:');
scopes.forEach(s => console.log(`  - ${s}`));

// Check specific permission
if (scopes.includes('documents:signed:read')) {
  console.log('Can read signed documents');
}

---

Get All Available Scopes

Returns every scope available in the Sonar system, organized hierarchically by category and type.

Endpoint: GET /api/sdk/v1/scopes-allowed/all

Response Hierarchy

ScopeCategory[]
  └── id: string         (e.g., "documents")
  └── label: string      (e.g., "Documents")
  └── types: ScopeType[]
        └── id: string       (e.g., "signed")
        └── label: string    (e.g., "Signed")
        └── scopes: ScopeEntry[]
              └── value: string   (e.g., "documents:signed:read")
              └── label: string   (e.g., "Read")

const categories = await sdk.scopes.getAll();

for (const category of categories) {
  console.log(`\n${category.label} (${category.id}):`);
  for (const type of category.types) {
    console.log(`  ${type.label}:`);
    for (const scope of type.scopes) {
      console.log(`    - ${scope.label}: ${scope.value}`);
    }
  }
}

---

Scope Constants

The SDK exports a Scope object with all known scope values as typed constants, preventing typos and enabling autocompletion.

import { Scope } from '@sonar/sdk';

Signed Document Scopes

Constant	Value
Scope.DOCUMENTS_SIGNED_READ	"documents:signed:read"
Scope.DOCUMENTS_SIGNED_UPLOAD	"documents:signed:upload"
Scope.DOCUMENTS_SIGNED_UPDATE	"documents:signed:update"
Scope.DOCUMENTS_SIGNED_EXPORT	"documents:signed:export"
Scope.DOCUMENTS_SIGNED_DELETE	"documents:signed:delete"

Generated Document Scopes

Constant	Value
Scope.DOCUMENTS_GENERATED_READ	"documents:generated:read"
Scope.DOCUMENTS_GENERATED_UPLOAD	"documents:generated:upload"
Scope.DOCUMENTS_GENERATED_UPDATE	"documents:generated:update"
Scope.DOCUMENTS_GENERATED_EXPORT	"documents:generated:export"
Scope.DOCUMENTS_GENERATED_DELETE	"documents:generated:delete"

Uploaded Document Scopes

Constant	Value
Scope.DOCUMENTS_UPLOADED_READ	"documents:uploaded:read"
Scope.DOCUMENTS_UPLOADED_UPLOAD	"documents:uploaded:upload"
Scope.DOCUMENTS_UPLOADED_UPDATE	"documents:uploaded:update"
Scope.DOCUMENTS_UPLOADED_EXPORT	"documents:uploaded:export"
Scope.DOCUMENTS_UPLOADED_DELETE	"documents:uploaded:delete"

Usage with getAllowed()

import { SonarSDK, Scope } from '@sonar/sdk';

const sdk = new SonarSDK({ apiKey: 'sk_...', instanceName: 'demo' });
const { scopes } = await sdk.scopes.getAllowed();

if (scopes.includes(Scope.DOCUMENTS_SIGNED_READ)) {
  const signedDocs = await sdk.documents.list({ classification: 'signed' });
}

---

Permission Matrix

Scope String	Constant	Category	Type	Action
documents:signed:read	Scope.DOCUMENTS_SIGNED_READ	Documents	Signed	Read
documents:signed:upload	Scope.DOCUMENTS_SIGNED_UPLOAD	Documents	Signed	Upload
documents:signed:update	Scope.DOCUMENTS_SIGNED_UPDATE	Documents	Signed	Update
documents:signed:export	Scope.DOCUMENTS_SIGNED_EXPORT	Documents	Signed	Export
documents:signed:delete	Scope.DOCUMENTS_SIGNED_DELETE	Documents	Signed	Delete
documents:generated:read	Scope.DOCUMENTS_GENERATED_READ	Documents	Generated	Read
documents:generated:upload	Scope.DOCUMENTS_GENERATED_UPLOAD	Documents	Generated	Upload
documents:generated:update	Scope.DOCUMENTS_GENERATED_UPDATE	Documents	Generated	Update
documents:generated:export	Scope.DOCUMENTS_GENERATED_EXPORT	Documents	Generated	Export
documents:generated:delete	Scope.DOCUMENTS_GENERATED_DELETE	Documents	Generated	Delete
documents:uploaded:read	Scope.DOCUMENTS_UPLOADED_READ	Documents	Uploaded	Read
documents:uploaded:upload	Scope.DOCUMENTS_UPLOADED_UPLOAD	Documents	Uploaded	Upload
documents:uploaded:update	Scope.DOCUMENTS_UPLOADED_UPDATE	Documents	Uploaded	Update
documents:uploaded:export	Scope.DOCUMENTS_UPLOADED_EXPORT	Documents	Uploaded	Export
documents:uploaded:delete	Scope.DOCUMENTS_UPLOADED_DELETE	Documents	Uploaded	Delete