@centrali-io/centrali-sdk 2.5.0 → 2.5.1

package/dist/index.js

@@ -1582,6 +1582,84 @@ class CentraliSDK {
             return this.request('GET', path, null, queryParams);
         });
     }
+    // ------------------ Authorization API Methods (BYOT) ------------------
+    /**
+     * Check if an action is authorized for an external token.
+     *
+     * Use this method when you want to authorize access using tokens from your
+     * own identity provider (Clerk, Auth0, Okta, etc.) instead of Centrali's
+     * built-in authentication.
+     *
+     * **Use Cases:**
+     * 1. **AuthZ-as-a-Service**: Define custom resources (orders, invoices) in Centrali
+     *    and use it purely for authorization decisions.
+     * 2. **External IdP for Centrali resources**: Access Centrali data (records, files)
+     *    using your corporate IdP tokens.
+     *
+     * **Prerequisites:**
+     * - Configure an External Auth Provider in Centrali Console (Settings → External Auth)
+     * - Define claim mappings to extract attributes from your JWT
+     * - Create policies that reference the extracted attributes (prefixed with `ext_`)
+     *
+     * @example
+     * // Simple authorization check
+     * const result = await client.checkAuthorization({
+     *   token: clerkJWT,
+     *   resource: 'orders',
+     *   action: 'read'
+     * });
+     *
+     * if (result.data.allowed) {
+     *   // Proceed with the action
+     * }
+     *
+     * @example
+     * // Authorization with context for policy evaluation
+     * const result = await client.checkAuthorization({
+     *   token: clerkJWT,
+     *   resource: 'orders',
+     *   action: 'approve',
+     *   context: {
+     *     orderId: 'order-123',
+     *     orderAmount: 50000,
+     *     department: 'sales'
+     *   }
+     * });
+     *
+     * // Policy can check: ext_role == 'manager' AND request_metadata.orderAmount > 10000
+     *
+     * @param options - Authorization check options
+     * @returns Promise resolving to the authorization result
+     */
+    checkAuthorization(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { token, resource, action, resourceCategory = 'custom', context } = options;
+            const path = `/workspace/${this.options.workspaceId}/api/v1/access/evaluate`;
+            const body = {
+                action,
+                resource_name: resource,
+                resource_category: resourceCategory,
+                request_data: context ? { request_metadata: context } : undefined
+            };
+            // Make request with the external token
+            const response = yield this.axios.request({
+                method: 'POST',
+                url: path,
+                data: body,
+                headers: {
+                    'Authorization': `Bearer ${token}`,
+                    'Content-Type': 'application/json'
+                }
+            });
+            return {
+                data: {
+                    allowed: response.data.response === 'allow',
+                    decision: response.data.response,
+                    message: response.data.message
+                }
+            };
+        });
+    }
 }
 exports.CentraliSDK = CentraliSDK;
 /**
@@ -1675,5 +1753,34 @@ exports.CentraliSDK = CentraliSDK;
  *   structures: ['users', 'orders'],
  *   limit: 50
  * });
+ *
+ * // ---- Authorization (BYOT - Bring Your Own Token) ----
+ *
+ * // Simple authorization check with external IdP token:
+ * const authResult = await client.checkAuthorization({
+ *   token: clerkJWT, // Token from Clerk, Auth0, Okta, etc.
+ *   resource: 'orders',
+ *   action: 'read'
+ * });
+ *
+ * if (authResult.data.allowed) {
+ *   console.log('Access granted');
+ * } else {
+ *   console.log('Access denied:', authResult.data.message);
+ * }
+ *
+ * // Authorization with context for policy evaluation:
+ * const approveResult = await client.checkAuthorization({
+ *   token: clerkJWT,
+ *   resource: 'orders',
+ *   action: 'approve',
+ *   context: {
+ *     orderId: 'order-123',
+ *     orderAmount: 50000,
+ *     department: 'sales'
+ *   }
+ * });
+ * // Policy can reference: ext_role, ext_department (from JWT claims)
+ * // and request_metadata.orderId, request_metadata.orderAmount (from context)
  *```
  */

package/index.ts

@@ -412,6 +412,90 @@ export interface ApiResponse<T> {
     updatedAt?: string;
 }
 
+// =====================================================
+// Authorization Types (BYOT - Bring Your Own Token)
+// =====================================================
+
+/**
+ * Resource category for authorization.
+ * - 'workspace': Workspace-level resources (e.g., settings, members)
+ * - 'structure': Structure-level resources (e.g., specific records)
+ * - 'custom': Custom resources defined by the user for AuthZ-as-a-Service
+ */
+export type ResourceCategory = 'workspace' | 'structure' | 'custom';
+
+/**
+ * Options for authorization check.
+ * Use this when authorizing access using an external IdP token (BYOT).
+ */
+export interface CheckAuthorizationOptions {
+    /**
+     * The JWT token from your external identity provider (e.g., Clerk, Auth0, Okta).
+     * The token will be validated against the configured external auth provider.
+     */
+    token: string;
+
+    /**
+     * The resource being accessed.
+     * Can be a Centrali system resource (e.g., 'records', 'files') or a custom
+     * resource you've defined for AuthZ-as-a-Service (e.g., 'orders', 'invoices').
+     */
+    resource: string;
+
+    /**
+     * The action being performed on the resource.
+     * Common actions: 'create', 'read', 'update', 'delete', 'admin'
+     * You can also define custom actions (e.g., 'approve', 'publish').
+     */
+    action: string;
+
+    /**
+     * Resource category for authorization evaluation.
+     * - 'workspace': Workspace-level resources
+     * - 'structure': Structure-level resources
+     * - 'custom': Custom resources for AuthZ-as-a-Service
+     * @default 'custom'
+     */
+    resourceCategory?: ResourceCategory;
+
+    /**
+     * Optional context data for policy evaluation.
+     * This data becomes available as `request_metadata` in policies.
+     *
+     * @example
+     * // Policy can reference: request_metadata.orderId, request_metadata.amount
+     * context: {
+     *   orderId: 'order-123',
+     *   amount: 50000,
+     *   department: 'sales'
+     * }
+     */
+    context?: Record<string, unknown>;
+}
+
+/**
+ * Result of an authorization check.
+ */
+export interface AuthorizationResult {
+    /**
+     * Whether the action is allowed.
+     */
+    allowed: boolean;
+
+    /**
+     * The decision from the policy evaluator.
+     * - 'allow': Access granted
+     * - 'deny': Access denied
+     * - 'not_applicable': No matching policy found
+     */
+    decision: 'allow' | 'deny' | 'not_applicable';
+
+    /**
+     * Human-readable message explaining the decision.
+     */
+    message?: string;
+}
+
 // =====================================================
 // Trigger Types
 // =====================================================
@@ -2713,6 +2797,94 @@ export class CentraliSDK {
         return this.request<SearchResponse>('GET', path, null, queryParams);
     }
 
+    // ------------------ Authorization API Methods (BYOT) ------------------
+
+    /**
+     * Check if an action is authorized for an external token.
+     *
+     * Use this method when you want to authorize access using tokens from your
+     * own identity provider (Clerk, Auth0, Okta, etc.) instead of Centrali's
+     * built-in authentication.
+     *
+     * **Use Cases:**
+     * 1. **AuthZ-as-a-Service**: Define custom resources (orders, invoices) in Centrali
+     *    and use it purely for authorization decisions.
+     * 2. **External IdP for Centrali resources**: Access Centrali data (records, files)
+     *    using your corporate IdP tokens.
+     *
+     * **Prerequisites:**
+     * - Configure an External Auth Provider in Centrali Console (Settings → External Auth)
+     * - Define claim mappings to extract attributes from your JWT
+     * - Create policies that reference the extracted attributes (prefixed with `ext_`)
+     *
+     * @example
+     * // Simple authorization check
+     * const result = await client.checkAuthorization({
+     *   token: clerkJWT,
+     *   resource: 'orders',
+     *   action: 'read'
+     * });
+     *
+     * if (result.data.allowed) {
+     *   // Proceed with the action
+     * }
+     *
+     * @example
+     * // Authorization with context for policy evaluation
+     * const result = await client.checkAuthorization({
+     *   token: clerkJWT,
+     *   resource: 'orders',
+     *   action: 'approve',
+     *   context: {
+     *     orderId: 'order-123',
+     *     orderAmount: 50000,
+     *     department: 'sales'
+     *   }
+     * });
+     *
+     * // Policy can check: ext_role == 'manager' AND request_metadata.orderAmount > 10000
+     *
+     * @param options - Authorization check options
+     * @returns Promise resolving to the authorization result
+     */
+    public async checkAuthorization(
+        options: CheckAuthorizationOptions
+    ): Promise<ApiResponse<AuthorizationResult>> {
+        const { token, resource, action, resourceCategory = 'custom', context } = options;
+
+        const path = `/workspace/${this.options.workspaceId}/api/v1/access/evaluate`;
+
+        const body = {
+            action,
+            resource_name: resource,
+            resource_category: resourceCategory,
+            request_data: context ? { request_metadata: context } : undefined
+        };
+
+        // Make request with the external token
+        const response = await this.axios.request<{
+            status: string;
+            response: 'allow' | 'deny' | 'not_applicable';
+            message?: string;
+        }>({
+            method: 'POST',
+            url: path,
+            data: body,
+            headers: {
+                'Authorization': `Bearer ${token}`,
+                'Content-Type': 'application/json'
+            }
+        });
+
+        return {
+            data: {
+                allowed: response.data.response === 'allow',
+                decision: response.data.response,
+                message: response.data.message
+            }
+        };
+    }
+
 }
 
 /**
@@ -2806,5 +2978,34 @@ export class CentraliSDK {
  *   structures: ['users', 'orders'],
  *   limit: 50
  * });
+ *
+ * // ---- Authorization (BYOT - Bring Your Own Token) ----
+ *
+ * // Simple authorization check with external IdP token:
+ * const authResult = await client.checkAuthorization({
+ *   token: clerkJWT, // Token from Clerk, Auth0, Okta, etc.
+ *   resource: 'orders',
+ *   action: 'read'
+ * });
+ *
+ * if (authResult.data.allowed) {
+ *   console.log('Access granted');
+ * } else {
+ *   console.log('Access denied:', authResult.data.message);
+ * }
+ *
+ * // Authorization with context for policy evaluation:
+ * const approveResult = await client.checkAuthorization({
+ *   token: clerkJWT,
+ *   resource: 'orders',
+ *   action: 'approve',
+ *   context: {
+ *     orderId: 'order-123',
+ *     orderAmount: 50000,
+ *     department: 'sales'
+ *   }
+ * });
+ * // Policy can reference: ext_role, ext_department (from JWT claims)
+ * // and request_metadata.orderId, request_metadata.orderAmount (from context)
  *```
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centrali-io/centrali-sdk",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "description": "Centrali Node SDK",
   "main": "dist/index.js",
   "type": "commonjs",