Skip to main content

AI Integration Guide

Overview​

The AI integration allows your NINA workflows to connect with leading AI providers for intelligent text generation, conversation, and analysis capabilities. This integration enables you to leverage powerful language models from OpenAI, Anthropic, Google Gemini, and Microsoft 365 Copilot directly from your workflows for tasks such as content generation, summarization, code analysis, data extraction, and enterprise knowledge retrieval.

Status​

The integration currently supports comprehensive AI operations across four major providers:

  • OpenAI: Access to GPT-4o, GPT-4 Turbo, GPT-3.5, and o-series reasoning models for advanced text generation
  • Anthropic: Claude 3.5 Sonnet, Claude 3 Opus/Sonnet/Haiku models for nuanced conversation and code generation
  • Google Gemini: Gemini 1.5 Pro/Flash, Gemini 2.0 Flash, and Gemini 2.5 Pro for multimodal capabilities and advanced reasoning
  • Microsoft 365 Copilot: Enterprise AI with Microsoft Graph integration for accessing organizational data (emails, documents, meetings, chats)

Advanced features:

  • Multiple Authentication Methods: API key authentication for OpenAI/Anthropic/Gemini, OAuth2 for Microsoft 365 Copilot
  • Context Grounding: Additional context, file references, and web search for Copilot
  • Automatic Token Refresh: Seamless OAuth token management for long-running workflows
  • Conversation Management: Stateless operation with optional conversation reuse for multi-turn dialogues
  • Error Handling: Comprehensive error detection including token limit tracking for reasoning models

Credential Configuration​

The AI integration supports two authentication methods depending on the provider:

Authentication Methods​

1. API Key Authentication​

Used for OpenAI, Anthropic, and Google Gemini:

FieldDescriptionExample
API KeyProvider API keysk-proj-abc123... (OpenAI)
sk-ant-api03-xyz789... (Anthropic)
AIzaSyD... (Gemini)
ProviderAI provider selectionopenai, anthropic, or gemini
Auth TypeAuthentication typeapiKey

2. OAuth2 Authentication​

Used for Microsoft 365 Copilot:

FieldDescriptionExample
Client IDAzure AD application client ID12345678-1234-1234-1234-123456789abc
Client SecretAzure AD application client secretabc~123...
Tenant IDAzure AD tenant ID87654321-4321-4321-4321-cba987654321
ScopeOAuth2 scopes (must include offline_access)openid offline_access User.Read...
Auth URLAuthorization endpointhttps://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize
Access Token URLToken endpointhttps://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
ProviderAI providercopilot
Auth TypeAuthentication typeoauth2

Provider-Specific Setup​

OpenAI Configuration​

How to Get Your API Key:

  1. Go to OpenAI Platform
  2. Sign in or create an account
  3. Navigate to API keys section
  4. Click Create new secret key
  5. Name your key and copy it immediately (you won't see it again)
  6. Add billing information to enable API access

Supported Models:

  • gpt-4o - Latest GPT-4 Optimized model
  • gpt-4-turbo - GPT-4 Turbo with 128k context window
  • gpt-4 - Standard GPT-4 model
  • gpt-3.5-turbo - Fast and cost-effective
  • o1-preview, o1-mini - Reasoning models (beta)
  • o3-mini - Latest reasoning model (beta)

Creating an OpenAI Credential:

  1. Navigate to the Credentials section in NINA
  2. Click Add New Credential
  3. Fill in:
    • Integration Service: "AI"
    • Auth Type: "API Key"
    • Provider: "openai"
    • API Key: Your OpenAI API key
  4. Click Test Connection to verify
  5. Click Save

Anthropic Configuration​

How to Get Your API Key:

  1. Go to Anthropic Console
  2. Sign in or create an account
  3. Navigate to API Keys section
  4. Click Create Key
  5. Name your key and copy it
  6. Set up billing to enable API access

Supported Models:

  • claude-3-5-sonnet-20241022 - Latest Claude 3.5 Sonnet (recommended)
  • claude-3-5-sonnet-20240620 - Previous Claude 3.5 Sonnet
  • claude-3-opus-20240229 - Most capable Claude 3 model
  • claude-3-sonnet-20240229 - Balanced performance
  • claude-3-haiku-20240307 - Fast and compact

Creating an Anthropic Credential:

  1. Navigate to the Credentials section in NINA
  2. Click Add New Credential
  3. Fill in:
    • Integration Service: "AI"
    • Auth Type: "API Key"
    • Provider: "anthropic"
    • API Key: Your Anthropic API key (starts with sk-ant-api03-)
  4. Click Test Connection to verify
  5. Click Save

Google Gemini Configuration​

How to Get Your API Key:

  1. Go to Google AI Studio
  2. Sign in with your Google account
  3. Click Create API Key
  4. Select or create a Google Cloud project
  5. Copy your API key

Supported Models:

  • gemini-2.5-pro - Latest reasoning model (requires 8000-16000 max_tokens)
  • gemini-2.0-flash - Fast multimodal model
  • gemini-1.5-pro - Advanced understanding with 2M context window
  • gemini-1.5-flash - Fast and efficient
  • gemini-1.5-flash-8b - Ultra-fast, smaller model

Creating a Gemini Credential:

  1. Navigate to the Credentials section in NINA
  2. Click Add New Credential
  3. Fill in:
    • Integration Service: "AI"
    • Auth Type: "API Key"
    • Provider: "gemini"
    • API Key: Your Google AI API key
  4. Click Test Connection to verify
  5. Click Save

⚠️ Important Note for Gemini 2.5 Pro:

  • This model uses internal reasoning ("thinking") which consumes tokens
  • Always use max_tokens of 8000 or higher (recommended: 8000-16000)
  • Lower values will result in "MAX_TOKENS limit reached" errors

Microsoft 365 Copilot Configuration​

Microsoft 365 Copilot requires OAuth2 authentication and specific Azure AD application setup.

Prerequisites​

  1. Microsoft 365 Copilot License

    • Users must have an active Microsoft 365 Copilot add-on license ($30/user/month)
    • Enterprise license (E3/E5 or equivalent) required as base subscription
    • The Chat API is included at no additional cost for licensed users
    • Verify license assignment with your Microsoft 365 administrator

  2. Azure AD Application

    • Access to Azure Active Directory
    • Permission to create app registrations
    • Admin consent capability for delegated permissions

Setting Up Azure AD App Registration​

Step 1: Create App Registration

  1. Go to Azure Portal
  2. Navigate to Azure Active Directory → App registrations
  3. Click + New registration
  4. Configure:
    • Name: "NINA Copilot Integration" (or your preferred name)
    • Supported account types: "Accounts in this organizational directory only"
    • Redirect URI: Add your NINA callback URL
      • Platform: Web
      • URL:
        • For POC environment: https://poc.zynap.com/api/v1/oauth2/callback
        • For Production environment: https://platform.zynap.com/api/v1/oauth2/callback
  5. Click Register
  6. From the Overview page, note the following values:
    • Application (client) ID
    • Directory (tenant) ID

Step 2: Create Client Secret

  1. In your app registration, navigate to Certificates & secrets
  2. Click + New client secret
  3. Add:
    • Description: "NINA API Access"
    • Expiration: 24 months (recommended)
  4. Click Add
  5. IMPORTANT: Copy the secret value immediately (you will not see it again)

Step 3: Configure API Permissions

Navigate to API permissions and add these Microsoft Graph Delegated permissions:

PermissionDescriptionAdmin Consent Required
openidSign in and read user profileNo
offline_accessMaintain access to data (refresh tokens)No
User.ReadSign in and read user profileNo
Sites.Read.AllRead items in all site collectionsNo
Mail.ReadRead user mailNo
People.Read.AllRead all users' relevant people listsYes
OnlineMeetingTranscript.Read.AllRead all transcripts of online meetingsYes
Chat.ReadRead user chat messagesNo
ChannelMessage.Read.AllRead user channel messagesYes
ExternalItem.Read.AllRead items in external datasetsYes

To Add Permissions:

  1. Click + Add a permission → Microsoft Graph → Delegated permissions
  2. Search for and select each permission listed above
  3. Click Add permissions

⚠️ Critical: The offline_access permission is mandatory for automatic token refresh functionality. Without it, the integration will fail after the initial access token expires.

Step 4: Grant Admin Consent

  1. In API permissions, click Grant admin consent for [Your Organization]
  2. Confirm the consent dialog
  3. Verify all permissions show "Granted" status with green checkmarks

Step 5: Configure Authentication

  1. Navigate to Authentication
  2. Under Implicit grant and hybrid flows, ensure:
    • ✅ ID tokens is checked
  3. Under Advanced settings:
    • Allow public client flows: Set to No
  4. Click Save

Creating a Microsoft 365 Copilot Credential​

  1. Navigate to the Credentials section in NINA

  2. Click Add New Credential

  3. Fill in the credential details:

    • Integration Service: "AI"
    • Auth Type: "OAuth2"
    • Provider: "copilot"
    • Client ID: Your Azure AD Application (client) ID
    • Client Secret: Your client secret value
    • Tenant ID: Your Azure AD Directory (tenant) ID
    • Scope: Use the default value: 
      openid offline_access User.Read ChannelMessage.Read.All Chat.Read ExternalItem.Read.All Mail.Read OnlineMeetingTranscript.Read.All People.Read.All Sites.Read.All
    • Auth URL: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize
    • Access Token URL: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token

  4. Click Authorize to start OAuth flow

  5. Sign in with your Microsoft 365 account

  6. Review and accept the permissions consent screen

  7. You'll be redirected back to NINA

  8. Click Save to store the credential

Troubleshooting OAuth Setup:

  • If token refresh fails, delete the credential and recreate it ensuring offline_access is in the scope
  • Clear browser cache/cookies before re-authorizing if you encounter consent issues
  • Verify the user account has an active Microsoft 365 Copilot license assigned
  • Confirm admin consent has been granted for all permissions requiring it

Supported Resources and Operations​

Answer (All Providers)​

Generate intelligent responses using AI language models.

Operation: Generate Answer

OpenAI, Anthropic, and Gemini Parameters​

ParameterTypeRequiredDescription
promptstringYesInput question or text for the AI model
modelstringYesModel identifier (e.g., gpt-4o, claude-3-5-sonnet-20241022, gemini-2.0-flash)
temperaturenumberNoRandomness of output (0.0-2.0, default: 0.7)
max_tokensnumberNoMaximum output length (default: 1000, use 8000+ for Gemini 2.5 Pro)
system_messagestringNoSystem instructions (OpenAI, Anthropic only)
timeoutnumberNoRequest timeout in seconds (default: 90)

Microsoft 365 Copilot Parameters​

ParameterTypeRequiredDescription
promptstringYesInput question or text
conversation_idstringNoReuse existing conversation ID for multi-turn dialogue
additional_contextarrayNoAdditional text context (array of strings)
web_search_enabledbooleanNoEnable web search grounding (default: true)
contextual_filesarrayNoSharePoint/OneDrive file URIs (array of strings)
timezonestringNoUser timezone in IANA format (default: America/New_York)
timeoutnumberNoRequest timeout in seconds (default: 90)

Conversation (Microsoft 365 Copilot Only)​

Manage conversation sessions for multi-turn dialogues.

Operation: Create Conversation

ParameterTypeRequiredDescription
timeoutnumberNoRequest timeout in seconds (default: 90)

Parameter Merging​

The AI integration takes full advantage of NINA's parameter merging capabilities:

Parameter Sources (in order of precedence)​

  1. Node Parameters: Parameters configured directly in the AI Integration Node
  2. Extracted Parameters: Parameters automatically extracted from the input data
  3. Input Data: The complete input data from upstream nodes

When an AI Integration Node executes:

  • It combines parameters from all sources
  • Node parameters take precedence over extracted parameters
  • Template variables within parameters are processed (using {{variable_name}} syntax)
  • The combined parameters are used to execute the AI operation

Examples​

Example 1: Generate Text with OpenAI​

{
  "integration_service": "ai",
  "resource": "answer",
  "operation": "generate",
  "parameters": {
    "prompt": "Summarize the key security vulnerabilities found in our latest penetration test",
    "model": "gpt-4o",
    "temperature": 0.3,
    "max_tokens": 500,
    "system_message": "You are a cybersecurity expert. Provide concise, actionable summaries."
  }
}

Example 2: Code Analysis with Anthropic​

{
  "integration_service": "ai",
  "resource": "answer",
  "operation": "generate",
  "parameters": {
    "prompt": "Review this Python code for security issues:\n\n{{previous_node.code}}",
    "model": "claude-3-5-sonnet-20241022",
    "temperature": 0.2,
    "max_tokens": 2000,
    "system_message": "You are an expert code reviewer focusing on security vulnerabilities, performance issues, and best practices."
  }
}

Example 3: Data Analysis with Gemini​

{
  "integration_service": "ai",
  "resource": "answer",
  "operation": "generate",
  "parameters": {
    "prompt": "Analyze this incident data and identify patterns:\n\n{{incident_data}}",
    "model": "gemini-2.0-flash",
    "temperature": 0.5,
    "max_tokens": 2000
  }
}

Example 4: Advanced Reasoning with Gemini 2.5 Pro​

{
  "integration_service": "ai",
  "resource": "answer",
  "operation": "generate",
  "parameters": {
    "prompt": "Develop a comprehensive security architecture for a cloud-native application handling sensitive financial data",
    "model": "gemini-2.5-pro",
    "temperature": 0.4,
    "max_tokens": 12000
  }
}

Note: Gemini 2.5 Pro requires higher max_tokens (8000-16000) due to internal reasoning capabilities.

Example 5: Microsoft 365 Copilot - Meeting Information​

{
  "integration_service": "ai",
  "resource": "answer",
  "operation": "generate",
  "parameters": {
    "prompt": "What meetings do I have scheduled for tomorrow? Include attendees and topics.",
    "timezone": "America/New_York",
    "web_search_enabled": false
  }
}

Example 6: Microsoft 365 Copilot - Document Analysis​

{
  "integration_service": "ai",
  "resource": "answer",
  "operation": "generate",
  "parameters": {
    "prompt": "Analyze the Q4 financial report and summarize key findings and risks",
    "contextual_files": [
      "https://contoso.sharepoint.com/sites/Finance/Shared%20Documents/Q4_Report.xlsx"
    ],
    "timezone": "Europe/London",
    "web_search_enabled": false
  }
}

Example 7: Microsoft 365 Copilot - With Additional Context​

{
  "integration_service": "ai",
  "resource": "answer",
  "operation": "generate",
  "parameters": {
    "prompt": "Based on recent security incidents and our current policies, recommend improvements to our incident response plan",
    "additional_context": [
      "Last security incident occurred on January 15, 2025",
      "Response time was 4 hours",
      "Affected systems: Production web servers"
    ],
    "web_search_enabled": true,
    "timezone": "America/Los_Angeles"
  }
}

Example 8: Microsoft 365 Copilot - Multi-turn Conversation​

First Request:

{
  "integration_service": "ai",
  "resource": "answer",
  "operation": "generate",
  "parameters": {
    "prompt": "What were the main topics discussed in last week's security team meeting?",
    "timezone": "America/New_York"
  }
}

Follow-up Request (using conversation_id from previous response):

{
  "integration_service": "ai",
  "resource": "answer",
  "operation": "generate",
  "parameters": {
    "prompt": "Who was assigned to address the firewall upgrade?",
    "conversation_id": "AAQkADAwATMwMAItM...",
    "timezone": "America/New_York"
  }
}

Example 9: Create Copilot Conversation Manually​

{
  "integration_service": "ai",
  "resource": "conversation",
  "operation": "create",
  "parameters": {
    "timeout": 60
  }
}

Response:

{
  "conversation_id": "AAQkADAwATMwMAItM...",
  "created_at": "2025-01-29T10:30:00Z",
  "status": "active",
  "provider": "copilot"
}

Best Practices​

Model Selection​

  • GPT-4o (OpenAI): Best for complex reasoning, multi-step tasks, and general-purpose applications
  • GPT-3.5-turbo (OpenAI): Fast and cost-effective for simple tasks, summarization, and high-volume operations
  • Claude 3.5 Sonnet (Anthropic): Excellent for code generation, analysis, and nuanced conversation
  • Claude 3 Haiku (Anthropic): Fast responses for high-volume use cases with shorter outputs
  • Gemini 2.0 Flash (Google): Fast multimodal capabilities, good balance of speed and quality
  • Gemini 2.5 Pro (Google): Advanced reasoning for complex analytical tasks (requires higher token limits)
  • Microsoft 365 Copilot: Enterprise scenarios requiring access to organizational data (emails, documents, meetings)

Temperature Guidelines​

TemperatureUse CaseExamples
0.0-0.3Deterministic, factualCode generation, data extraction, factual Q&A
0.4-0.7BalancedGeneral conversation, summarization, analysis
0.8-1.0CreativeContent writing, brainstorming, idea generation
1.0+Highly creativeExperimental outputs, diverse alternatives

Token Management​

  1. Start Conservative: Begin with lower max_tokens values and increase as needed
  2. Monitor Usage: Track token consumption for cost optimization
  3. Gemini 2.5 Pro Exception: Always use 8000+ max_tokens due to internal reasoning overhead
  4. System Messages: Use system messages to constrain output format and length
  5. Prompt Engineering: Clear, concise prompts often yield better results with fewer tokens

Security​

  1. Never Hardcode API Keys: Always use the credentials system
  2. Rotate Keys Regularly: Implement periodic API key rotation
  3. Separate Environments: Use different credentials for development, staging, and production
  4. Microsoft 365 Copilot:
    • Ensure proper Azure AD app permissions and admin consent
    • Verify users have required Copilot licenses
    • Review and audit access to organizational data
  5. Monitor Usage: Implement audit logging for all AI operations

Performance​

  1. Caching: Implement response caching for frequently asked questions
  2. Timeouts: Set appropriate timeout values based on expected response time (default: 90 seconds)
  3. Retry Logic: Implement exponential backoff for transient errors
  4. Microsoft 365 Copilot: Reuse conversation IDs for multi-turn dialogues to maintain context

Microsoft 365 Copilot Specifics​

  1. Licensing: Always verify users have active Microsoft 365 Copilot licenses before deployment
  2. Permissions: Grant admin consent during initial setup to avoid runtime authorization issues
  3. Scope: Always include offline_access in the scope for automatic token refresh
  4. Timezone: Use proper IANA format timezones (e.g., America/New_York, Europe/London, not UTC)
  5. Context Grounding: Leverage additional_context and contextual_files for domain-specific responses
  6. Conversations: Create conversation once with createConversation, then reuse the ID for related queries

Troubleshooting​

IssueProviderResolution
invalid_api_keyOpenAIRegenerate API key in OpenAI dashboard; verify key format
insufficient_quotaOpenAIAdd billing information or upgrade plan
rate_limit_exceededOpenAI, AnthropicImplement rate limiting; add retry logic with exponential backoff
context_length_exceededOpenAI, AnthropicReduce prompt length or use model with larger context window
authentication_errorAnthropicVerify API key starts with sk-ant-api03-
overloaded_errorAnthropicRetry with exponential backoff; service temporarily overloaded
no text content found in responseGeminiModel hit token limit; increase max_tokens (8000+ for 2.5-pro)
MAX_TOKENS limit reachedGeminiIncrease max_tokens parameter; recommended 8000-16000 for Gemini 2.5 Pro
API key not validGeminiRegenerate key in Google AI Studio
Resource has been exhaustedGeminiCheck quota limits in Google Cloud Console
invalid access token and no refresh token availableCopilotMissing offline_access scope; delete and recreate credential with correct scope
you don't have a valid licenseCopilotUser missing Microsoft 365 Copilot license; contact Microsoft 365 admin
timeZone field is not in correct IANA formatCopilotUse IANA format (e.g., America/New_York, not UTC or GMT)
access forbiddenCopilotMissing or not consented Microsoft Graph permissions; grant admin consent
401 UnauthorizedCopilotToken expired; will auto-refresh if offline_access is in scope

Debugging Microsoft 365 Copilot Token Refresh​

If you encounter token refresh issues:

  1. Verify Scope:

    • Delete the credential
    • Create a new credential
    • Ensure scope field includes: openid offline_access ...
    • Complete OAuth flow again

  2. Clear Browser Cache:

    • Microsoft caches consent decisions
    • Use incognito/private browsing mode for testing
    • Clear all Microsoft/Azure-related cookies

  3. Verify in Azure AD:

    • Go to Enterprise Applications in Azure Portal
    • Find your application
    • Check User consent tab
    • Confirm offline_access is listed as granted

  4. Check Credential Storage:

    • Verify the database contains both accessToken and refreshToken
    • If refreshToken is missing, the OAuth flow did not include offline_access

Security Considerations​

API Key-Based Providers (OpenAI, Anthropic, Gemini)​

  1. Key Protection: Store API keys securely using NINA's encrypted credentials system
  2. Key Rotation: Implement regular API key rotation (recommended: every 90 days)
  3. Least Privilege: Use separate API keys for different environments and purposes
  4. Rate Limiting: Implement application-level rate limiting to prevent abuse
  5. Usage Monitoring: Monitor API usage for anomalies and unexpected spikes
  6. Audit Logging: Log all AI operations including prompts and responses for compliance

OAuth2-Based Providers (Microsoft 365 Copilot)​

  1. Protect Client Secrets: Store Azure client secrets securely; rotate before expiration
  2. Least Privilege: Request only minimum required Microsoft Graph API permissions
  3. Admin Consent: Ensure proper admin consent for organizational permissions
  4. Audit Access: Monitor Microsoft 365 audit logs for integration activities
  5. Conditional Access: Consider Azure AD Conditional Access policies for additional security
  6. Data Sensitivity: Be aware that Copilot can access organizational data based on granted permissions
  7. Tenant Isolation: Verify tenant ID to ensure proper organizational isolation
  8. License Verification: Confirm users have appropriate licenses before granting access

Additional Resources​

Official Documentation​

Pricing Information​