Authentication

Flynapse provides multiple authentication methods to secure API access and ensure proper authorization for different use cases.

Authentication Methods

1. JWT Bearer Token (Recommended)

JWT (JSON Web Token) authentication is the recommended method for most API interactions. It provides secure, stateless authentication with built-in expiration.

Getting a JWT Token

Login Endpoint:

POST /api/v1/auth/login

Request Body:

{
  "email": "user@example.com",
  "password": "your-password"
}

Response:

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 3600,
    "token_type": "Bearer",
    "user": {
      "id": "user_123",
      "email": "user@example.com",
      "name": "John Doe",
      "role": "engineer"
    }
  }
}

Using JWT Tokens

Include the JWT token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token Refresh

When a JWT token expires, use the refresh token to get a new one:

POST /api/v1/auth/refresh

Request Body:

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

2. API Key Authentication

API keys are suitable for server-to-server communication and automated scripts. They provide long-term access without user interaction.

Getting an API Key

From Dashboard: Generate API keys from your Flynapse dashboard
From Admin: Request API keys from your system administrator

Using API Keys

Include the API key in the X-API-Key header:

X-API-Key: fl_1234567890abcdef1234567890abcdef

3. OAuth 2.0 (Enterprise)

For enterprise customers, Flynapse supports OAuth 2.0 integration with your existing identity providers.

Supported Providers

Azure AD: Microsoft Azure Active Directory
Okta: Okta Identity Platform
Google Workspace: Google Workspace SSO
Custom: Custom OAuth 2.0 providers

OAuth Flow

Authorization Request: Redirect users to Flynapse authorization URL
User Consent: User grants permission to your application
Authorization Code: Flynapse returns an authorization code
Token Exchange: Exchange code for access token
API Access: Use access token for API requests

Authentication Headers

Required Headers

All authenticated requests must include one of the following headers:

# JWT Bearer Token
Authorization: Bearer <jwt-token>

# OR API Key
X-API-Key: <api-key>

# OR OAuth 2.0
Authorization: Bearer <oauth-access-token>

Optional Headers

# Request ID for tracking
X-Request-ID: req_123456789

# Client information
X-Client-Version: 1.0.0
X-Client-Name: my-app

User Roles and Permissions

Flynapse implements role-based access control (RBAC) with the following roles:

Available Roles

Role	Description	Permissions
`admin`	System Administrator	Full access to all features and user management
`manager`	Team Manager	Access to team data, user management within team
`engineer`	Maintenance Engineer	Document access, search, commenting, sharing
`viewer`	Read-only User	Document viewing and search only
`api_user`	API-only User	Programmatic access via API keys

Permission Matrix

Feature	Admin	Manager	Engineer	Viewer	API User
Document Search	✅	✅	✅	✅	✅
Document Viewing	✅	✅	✅	✅	✅
Document Comments	✅	✅	✅	❌	❌
Document Sharing	✅	✅	✅	❌	❌
User Management	✅	✅	❌	❌	❌
System Settings	✅	❌	❌	❌	❌
API Access	✅	✅	✅	❌	✅

Security Best Practices

1. Token Management

Store Securely: Store tokens in secure environment variables or secret management systems
Rotate Regularly: Regularly rotate API keys and refresh JWT tokens
Monitor Usage: Monitor token usage for suspicious activity
Scope Minimally: Use the minimum required permissions for each application

2. Network Security

Use HTTPS: Always use HTTPS for API communications
Validate Certificates: Verify SSL certificates to prevent man-in-the-middle attacks
Rate Limiting: Respect rate limits and implement exponential backoff

3. Error Handling

Handle 401 Errors: Implement proper token refresh logic
Log Security Events: Log authentication failures and suspicious activity
Graceful Degradation: Handle authentication failures gracefully

Error Responses

Authentication Errors

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired token",
    "details": {
      "token_type": "jwt",
      "expired_at": "2024-01-15T10:30:00Z"
    }
  }
}

Permission Errors

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions",
    "details": {
      "required_permission": "document.comment",
      "user_permissions": ["document.view", "document.search"]
    }
  }
}

Code Examples

Python SDK

from flynapse import FlynapseClient

# JWT Authentication
client = FlynapseClient(
    email="user@example.com",
    password="your-password"
)

# API Key Authentication
client = FlynapseClient(api_key="fl_1234567890abcdef")

# OAuth 2.0 Authentication
client = FlynapseClient(oauth_token="oauth_access_token")

JavaScript SDK

const { FlynapseClient } = require('@flynapse/sdk');

// JWT Authentication
const client = new FlynapseClient({
  email: 'user@example.com',
  password: 'your-password'
});

// API Key Authentication
const client = new FlynapseClient({
  apiKey: 'fl_1234567890abcdef'
});

// OAuth 2.0 Authentication
const client = new FlynapseClient({
  oauthToken: 'oauth_access_token'
});

cURL Examples

# JWT Authentication
curl -X POST "https://api.flynapse.ai/v1/search/documents" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "thrust reverser"}'

# API Key Authentication
curl -X POST "https://api.flynapse.ai/v1/search/documents" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "thrust reverser"}'

Session Management

JWT Token Lifecycle

Login: User authenticates and receives JWT token
API Requests: Token used for authenticated requests
Expiration: Token expires after configured time (default: 1 hour)
Refresh: Use refresh token to get new access token
Logout: Invalidate tokens on logout

Session Configuration

{
  "session_timeout": 3600,
  "refresh_token_expiry": 2592000,
  "max_concurrent_sessions": 5,
  "idle_timeout": 1800
}

Multi-Factor Authentication (MFA)

Enterprise customers can enable MFA for enhanced security:

MFA Methods

SMS: One-time codes sent via SMS
Email: One-time codes sent via email
TOTP: Time-based one-time passwords (Google Authenticator, Authy)
Hardware Tokens: Physical security keys (YubiKey)

MFA Flow

Login Attempt: User provides email/password
MFA Challenge: System requests second factor
Verification: User provides MFA code
Token Issuance: System issues JWT token upon successful verification

Troubleshooting

Common Issues

Issue	Cause	Solution
401 Unauthorized	Expired or invalid token	Refresh JWT token or regenerate API key
403 Forbidden	Insufficient permissions	Contact admin to update user role
429 Too Many Requests	Rate limit exceeded	Implement exponential backoff
500 Internal Server Error	Server-side issue	Contact support with request ID

Debug Information

Include debug headers for troubleshooting:

X-Debug: true
X-Request-ID: req_123456789

Support

For authentication issues:

Documentation: This authentication guide
Support Email: auth-support@flynapse.ai
Community Forum: community.flynapse.ai
Emergency Contact: security@flynapse.ai (for security incidents)

Secure your Flynapse integration with proper authentication

​Authentication

​Authentication Methods

​1. JWT Bearer Token (Recommended)

​Getting a JWT Token

​Using JWT Tokens

​Token Refresh

​2. API Key Authentication

​Getting an API Key

​Using API Keys

​3. OAuth 2.0 (Enterprise)

​Supported Providers

​OAuth Flow

​Authentication Headers

​Required Headers

​Optional Headers

​User Roles and Permissions

​Available Roles

​Permission Matrix

​Security Best Practices

​1. Token Management

​2. Network Security

​3. Error Handling

​Error Responses

​Authentication Errors

​Permission Errors

​Code Examples

​Python SDK

​JavaScript SDK

​cURL Examples

​Session Management

​JWT Token Lifecycle

​Session Configuration

​Multi-Factor Authentication (MFA)

​MFA Methods

​MFA Flow

​Troubleshooting

​Common Issues

​Debug Information

​Support