API Authentication

Zudello APIs use organization API keys for authentication. This page explains how to generate and manage API keys to access Zudello's services securely.

Overview

Organization API keys provide secure access to Zudello APIs with:

• Team-based access control: Assign keys to specific teams within your organization
• Granular permissions: Configure read/write access and admin privileges per team
• Secure token management: One-time secret display with expiration tracking
• Organization-scoped access: Keys are limited to a single organization

API Key Management

Creating API Keys

API keys are managed through the Organization settings in the Zudello web interface:

1. Navigate to Organization Settings

   • Go to Organization → API Keys (located under User Groups)

2. Create New API Key

   • Click "Add API Key"
   • Enter a descriptive name
   • Click "Create API Key"

3. Token Generation Process

   Step 1: Create API key via authentication service
   Step 2: Generate secure token with expiration
   Step 3: Configure teams and permissions

API Key Properties

Each API key includes:

Field	Description	Required
Description	Human-readable name for the key	Yes
Expires	Token expiration date/time	Automatic
Teams	Teams the key has access to	Optional
Is Active	Organization-level active status	Yes
Secret	API token (shown only once)	Automatic

Security Notice

The secret token is displayed only once during creation. Store it securely as it cannot be retrieved later.

Managing API Keys

Available Actions

• View API Key: See description, teams, permissions, and expiry
• Assign/Unassign Teams: Control team access across multiple teams
• Set User Groups: Configure user groups within each team for granular permissions
• Set Permissions: Configure CRUD and Data permissions per team
• Activate/Deactivate: Control key status at organization or team level
• Delete: Permanently remove the API key

Team Assignment and Permissions

API keys can be assigned to multiple teams within an organization. For each team assignment, you can configure:

• User Groups: Specific user groups within the team that govern permissions
• CRUD Permissions: Create, Read, Update, Delete access levels
• Data Permissions: Access to specific data sets and modules
• Team Status: Active/inactive status per team

Permission Inheritance

API keys inherit the same permission model as end users. Both CRUD permissions (Create, Read, Update, Delete) and Data permissions (access to specific modules and data sets) apply to API keys based on their assigned user groups within each team.

Using API Keys

Request Headers

Required Headers

All API requests must include three critical headers to avoid 401 authentication errors:

Required Headers:

Authorization: Bearer zud_live_abc123...
x-organization: your-organization-id
x-team: your-team-id

• Authorization: Your API key token
• x-organization: The organization ID the API key belongs to
• x-team: The team ID within the organization you're accessing

Example Request

curl -X GET "https://api.zudello.com/v1/transactions" \
  -H "Authorization: Bearer zud_live_abc123..." \
  -H "x-organization: org-12345" \
  -H "x-team: team-67890" \
  -H "Content-Type: application/json"

Response Format

Successful authentication returns your requested data. Failed authentication returns:

{
  "error": "unauthorized",
  "message": "Invalid or expired API key",
  "code": 401
}

Missing Headers

If you omit the x-organization or x-team headers, you will receive a 401 Unauthorized error even with a valid API key.

Token Scopes and Permissions

Organization Level

• Access limited to a single organization
• Team-based access control
• Configurable permissions per team
• Optional organization admin privileges

Team Level

API keys can have different permissions per team:

Permission	Description
Read	View data within team scope
Write	Create and modify data
Admin	Full team administration
User Groups	Access to specific user groups
Is Organization Admin	Organization-wide administrative access

Security Best Practices

API Key Management

1. Use Descriptive Names: Choose clear, descriptive names for your API keys
2. Limit Scope: Assign minimal necessary teams and permissions
3. Regular Rotation: Plan for future token rotation capabilities
4. Secure Storage: Store tokens securely and never commit them to code
5. Monitor Usage: Track API key usage for security auditing

Token Handling

• Never expose tokens in client-side code
• Use environment variables for token storage
• Implement proper error handling for authentication failures
• Monitor for unusual API usage patterns

Team Access

• Regularly review team assignments
• Use the principle of least privilege
• Deactivate unused keys promptly
• Document key purposes for team members

Rate Limiting

API requests are subject to rate limiting based on:

• Organization tier
• API key permissions
• Team allocations
• Service endpoints

Rate limit headers are included in API responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642676400

Troubleshooting

Common Issues

Issue	Cause	Solution
401 Unauthorized	Missing x-organization or x-team headers	Include all required headers
401 Unauthorized	Invalid/expired token	Regenerate API key
403 Forbidden	Insufficient permissions	Check team assignments
403 Forbidden	API key not assigned to specified team	Verify team assignments in Organization settings
429 Too Many Requests	Rate limit exceeded	Implement backoff strategy
500 Server Error	Service unavailable	Check Zudello status page

Getting Help

For API authentication issues:

1. Check the API Reference for endpoint documentation
2. Verify your API key configuration in Organization settings
3. Contact Zudello support with your organization ID and error details

Related Documentation

• API Reference - Complete API endpoint documentation