--- title: "Nutrient API management guide" canonical_url: "https://www.nutrient.io/guides/workflow-automation/admin-guide/development-resources/api-information/" md_url: "https://www.nutrient.io/guides/workflow-automation/admin-guide/development-resources/api-information.md" last_updated: "2026-06-11T00:00:00.000Z" description: "Learn to use the Nutrient API effectively for managing tasks, generating API keys, and utilizing advanced features for automation." --- # Workflow Automation API for automation tasks The Nutrient Workflow Automation API has a large collection of functions that enable you to manage processes, requests, tasks, reports, and users within a Workflow Automation instance. There are also many new functions in the new API, including extended functions for the management of file attachments. ## Generating an API key Choose the **API Keys** icon in the **Settings** menu (the gear icon in the upper-right corner). To create a new key, add an expiration date and a description, both of which are optional, and then click **Create API Key**. A new value will appear in the **Private Key** field. Press **Copy** on the far right to store the key securely and safely. If you don’t copy this value, it won’t be displayed again anywhere in the system, and you’ll need to generate a replacement key. ## Managing API key security and usage API keys use the role-based permission model, so administrators can grant access to individual keys by role instead of tying access implicitly to system administration. Use the **API Keys** admin interface to review existing keys, manage ownership and access, and create new keys. Existing API keys are migrated into this security model automatically. After migration, administrators can manage each key using the same role-based approach used for other secured items in Workflow Automation. Use the **API Keys** usage report to audit where keys are used and review API key ownership and access. This helps administrators maintain fine-grained, auditable control over API key usage. When reports are executed through API key authentication, report audit logs record a non-sensitive API key identifier instead of the underlying user SID. The raw API key is never stored in the audit log. Only grant API key access to roles that need it, and review usage regularly to ensure keys remain appropriate for active integrations. Legacy API information can be found at [developer.integrify.com/rest/docs](https://developer.integrify.com/rest/docs). New functions have been added to this version, all of which are documented within the application itself. Refer to the screenshot below for the link to the API documentation.![generate an API key](@/assets/guides/workflow-automation/files/1109/create-api-key.png) ## Using the Workflow Automation API This section will walk you through how to use the Nutrient Workflow Automation API step by step, including how to: 1. Identify your host and tenant name 2. Access the API documentation 3. Authenticate and get your access token ### Identify the host and tenant The host header value can be found on the main screen under **Settings** > **System Settings** in the upper right-hand corner of the screen. On the **System Settings** page, copy and save the following items: - **ID** — yourtenant - **HostHeader** — baseurl.integrify.com![](@/assets/guides/workflow-automation/files/1109/hostheader-id.725x0-is.png) ### Access the API documentation API documentation is now hosted under the **System** / **APIs** section and has sections as shown in the screenshot below. To access a particular topic, click the box with the arrow pointing up and to the right.![](@/assets/guides/workflow-automation/files/1109/api-docu-links.780x680-cropx9y63-is.700x0-is.png) The section you access will look something like what’s shown below.![swagger api](@/assets/guides/workflow-automation/files/1109/swagger.png) Each colored button represents a method you can access in the Workflow Automation API. In this example, the area is specific to authentication. You can expand each function by clicking on each function’s listing. Use the in-app API documentation as the source of truth for supported endpoints. Avoid building integrations against internal, unused, or undocumented endpoints, as those routes may change or be removed without notice. Supported endpoints follow the platform’s authorization model and are the appropriate surface for production integrations. Click **Try it out** to test the function directly on the page. You may need to provide one or more parameter values to help the function complete successfully. When the function completes, you’ll receive a success or failure message and any appropriate return values. ### Authenticate the system To complete most tasks within the Workflow Automation API, you’ll need to pass a JSON Web Token (JWT) token value in the header of the method call you’re using. IntegrifyEnv (“Env”) tokens are used by system functions only and cannot be used by external systems to authenticate to Workflow Automation. Some internal platform routes and central integration functions rely on tenant and environment context in addition to authentication. When that context is unavailable, those system-managed routes are designed to fail safely rather than exposing unintended behavior. For external integrations, you can retrieve a JWT token using an API key that you created in the system settings area.![jwt token](@/assets/guides/workflow-automation/files/1109/jwt-token.png) ### Using the JWT token The JWT token you retrieve should be placed in the header of each method call you make. The way to use this token is as a bearer authentication token, where the token is passed as proof of privileges to the Workflow Automation system. ## User-based API key authentication As of version 8.11.0, a new API endpoint enables the acquisition of access tokens using user-based API keys. This authentication method provides a secure way for integrated services to access the API with user-specific permissions. ### How user-based API keys work User-based API key authentication functions similarly to the impersonation endpoint, but with the identity fixed to the user associated with the API key: - Each API key is tied to a specific user account. - The access token granted reflects that user’s permissions and roles. - API calls made with this token execute with the same privileges as the associated user. This ensures proper authorization and audit trails for API operations. ### Use cases for user-based API keys This authentication method is particularly useful for: - **Service integrations** — When external services need to perform actions on behalf of specific users. - **Automated workflows** — For scheduled tasks that should execute with specific user permissions. - **Third-party applications** — When integrating applications that require user-specific API access. - **Audit compliance** — Maintaining clear attribution of API actions to specific user accounts. ### Obtaining an access token with a user-based API key To authenticate using a user-based API key: 1. Generate a user-based API key through the API Keys settings (the process is the same as generating standard API keys). 2. Use the dedicated user-based authentication endpoint to obtain an access token. 3. Include the access token in subsequent API requests as a bearer authentication token. The endpoint returns an access token that represents the user associated with the API key, enabling secure, user-specific API authentication for your integrated services. > User-based API keys grant access with the full permissions of the associated user account. Ensure API keys are stored securely and only used by authorized applications. ## Permission-scoped API results Some API endpoints support permission-scoped results based on the authenticated user. For example, process search endpoints can filter results based on the requested permission scope, which helps ensure users only retrieve processes they are authorized to access. ## createInstanceWithTaskData response behavior When using `createInstanceWithTaskData`, instance tasks in the response are returned in a consistent order. This enables more reliable integration logic when task sequencing matters. --- ## Related pages - [508 compliance and accessibility](/guides/workflow-automation/admin-guide/development-resources/508-compliance.md) - [Nutrient Workflow Automation architecture](/guides/workflow-automation/admin-guide/development-resources/architecture.md) - [Secure AWS private cloud infrastructure for enterprises](/guides/workflow-automation/admin-guide/development-resources/aws-private-cloud-infrastructure.md) - [Explore Nutrient's development resources and APIs](/guides/workflow-automation/admin-guide/development-resources.md) - [JavaScript help](/guides/workflow-automation/admin-guide/development-resources/javascript-help.md) - [Ensuring FDA compliance with electronic records](/guides/workflow-automation/admin-guide/development-resources/title-21-cfr-part-11-fda-regulated-compliance.md) - [Secure workflow automation and compliance solutions](/guides/workflow-automation/admin-guide/development-resources/security-overview.md)