{"id":17868,"library":"permify-typescript","title":"Permify TypeScript Client","description":"permify-typescript is the official TypeScript client for Permify, an open-source authorization service designed for building fine-grained and scalable authorization systems. This package provides a programmatic interface to interact with the Permify API, covering operations for schema, relationships, permissions, and tenancy. As of version 1.6.9, the client's versioning now directly aligns with the upstream Permify API/OpenAPI version, ensuring closer synchronization with the service's capabilities. It is automatically generated by the OpenAPI Generator project, which ensures a consistent and up-to-date interface to the Permify API. The library supports Node.js environments version 18 and higher, shipping with full TypeScript type definitions for an enhanced developer experience.","status":"active","version":"1.6.9","language":"javascript","source_language":"en","source_url":"https://github.com/Permify/permify-typescript","tags":["javascript","permissions","authorization","access-control","rebac","fga","typescript"],"install":[{"cmd":"npm install permify-typescript","lang":"bash","label":"npm"},{"cmd":"yarn add permify-typescript","lang":"bash","label":"yarn"},{"cmd":"pnpm add permify-typescript","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"CommonJS `require` might work with transpilation, but this library is primarily designed for ESM with Node.js >=18, aligning with modern TypeScript best practices.","wrong":"const permify = require('permify-typescript');","symbol":"permify (all exports)","correct":"import * as permify from 'permify-typescript';"},{"note":"API client classes, configuration, and most models are exported as named exports directly from the package root.","wrong":"import Configuration from 'permify-typescript/Configuration';","symbol":"Configuration, TenancyApi, PermissionApi","correct":"import { Configuration, TenancyApi, PermissionApi } from 'permify-typescript';"},{"note":"Use `import type` for importing only type definitions in TypeScript for better bundle optimization and clarity, as `Tenant` is a type definition for an API model.","wrong":"import { Tenant } from 'permify-typescript';","symbol":"Tenant (type)","correct":"import type { Tenant } from 'permify-typescript';"}],"quickstart":{"code":"import * as permify from \"permify-typescript\";\n\n// Configure the client with your Permify API base path and authorization token.\n// It's recommended to use environment variables for sensitive data.\nconst configuration = new permify.Configuration({\n    basePath: process.env.PERMIFY_API_BASE_PATH ?? \"http://localhost:3476\",\n    headers: {\n        'Authorization': process.env.PERMIFY_API_KEY ? `Bearer ${process.env.PERMIFY_API_KEY}` : \"\"\n    }\n});\n\n// Initialize the TenancyApi to interact with tenant-related endpoints.\nconst apiInstance = new permify.TenancyApi(configuration);\n\n// Define a tenant ID, perhaps from a database or a unique identifier.\nlet tenantId = \"example_tenant_id\"; \n\n// Create a new tenant in Permify.\napiInstance.tenantsCreate({\n    body: {\n        id: tenantId,\n        name: \"Example Tenant\"\n    }\n})\n.then((data) => {\n    console.log('API called successfully. Created tenant: ' + JSON.stringify(data.tenant));\n})\n.catch((error) => {\n    console.error('Error creating tenant:', error.response?.data || error.message);\n});","lang":"typescript","description":"This quickstart demonstrates how to initialize the Permify TypeScript client, configure it with a base path and an authorization header using environment variables, and then create a new tenant using the TenancyApi client."},"warnings":[{"fix":"Consult the `permify-typescript` GitHub release notes or changelog for specific SDK-level breaking changes rather than solely relying on version number increments to determine client compatibility.","message":"Starting with v1.6.9, `permify-typescript` versions directly align with the upstream Permify API/OpenAPI version. A jump in the client's major or minor version number does not necessarily imply a breaking change in the SDK itself, but rather an update to match the Permify service's capabilities. Always refer to the package's specific release notes.","severity":"gotcha","affected_versions":">=1.6.9"},{"fix":"Upgrade your Node.js environment to version 18 or newer. Consider using a Node.js version manager like `nvm` to easily switch between versions.","message":"The `permify-typescript` package specifies Node.js version 18 or higher as a minimum requirement. Running on older Node.js versions may lead to unexpected runtime errors, dependency conflicts, or installation failures.","severity":"breaking","affected_versions":"<18.0.0"},{"fix":"Ensure the `Authorization` header is correctly set in the `Configuration` object, providing a valid Permify API key or token, preferably via environment variables (`process.env.PERMIFY_API_KEY`).","message":"API requests require proper authentication. Failure to provide a valid `Authorization` header (e.g., a Bearer token) will result in API authentication failures, typically a 401 Unauthorized response from the Permify API.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Verify that the Permify server is running and listening on the configured address and port (e.g., `http://localhost:3476`). Check firewall settings or network connectivity issues.","cause":"The Permify API server is not running or is inaccessible at the specified `basePath` in the client configuration, preventing a connection.","error":"Error: connect ECONNREFUSED 127.0.0.1:3476"},{"fix":"Double-check that your `PERMIFY_API_KEY` environment variable (or hardcoded token) is correct and that the `Authorization` header is properly formatted (e.g., `Bearer YOUR_TOKEN`).","cause":"The Permify API rejected the request due to missing, invalid, or expired authentication credentials provided in the `Authorization` header.","error":"Error: Request failed with status code 401"},{"fix":"Ensure you are using ESM `import` statements (e.g., `import { Configuration } from 'permify-typescript';` or `import * as permify from 'permify-typescript';`) and that your Node.js project is configured to run ESM (e.g., by setting `\"type\": \"module\"` in your `package.json`).","cause":"This error often occurs when attempting to use CommonJS `require` syntax or incorrect destructuring for a module that primarily uses ES Modules (ESM) and named exports.","error":"TypeError: permify.Configuration is not a constructor"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}