API Access

Understanding API access levels and permissions is crucial for building secure applications with 0.link. This guide covers different access levels, permission management, and how to handle access-related errors.

Access Levels Overview

0.link provides granular access control through permission-based API keys and account-level settings.

Account-Level Access

Your account determines the baseline access:

Free Tier

• ✅ Core API endpoints
• ✅ Basic asset management
• ✅ Standard integrations
• ✅ Community support
• ❌ Advanced analytics
• ❌ Premium integrations
• ❌ Custom webhooks

Pro Plan

• ✅ All Free tier features
• ✅ Advanced analytics API
• ✅ Premium integrations
• ✅ Custom webhook endpoints
• ✅ Team management API
• ❌ Enterprise-only features

Enterprise

• ✅ All Pro plan features
• ✅ Administrative APIs
• ✅ Audit logs access
• ✅ Custom rate limits
• ✅ Advanced security features

API Key Permissions

Each API key can have specific permissions:

Permission	Description	Access Level
read	View resources and data	Read-only
write	Create and update resources	Read + Write
delete	Remove resources	Read + Write + Delete
admin	Full administrative access	All operations

Read-Only Access

What You Can Do

With read-only permissions:

// ✅ Get account information
const account = await client.account.get();

// ✅ List projects
const projects = await client.projects.list();

// ✅ View assets
const assets = await client.assets.list();

// ✅ Access analytics (if plan supports)
const analytics = await client.analytics.query({
  metric: 'api_calls',
  period: 'last_7_days'
});

What You Cannot Do

// ❌ Create new projects
const project = await client.projects.create({ name: 'New Project' });
// Error: Insufficient permissions

// ❌ Upload assets
const asset = await client.assets.upload(file);
// Error: Write permission required

// ❌ Delete resources
await client.projects.delete('proj_123');
// Error: Delete permission required

Use Cases for Read-Only Access

• Monitoring dashboards: Display account statistics
• Analytics tools: Read usage data and metrics
• Reporting systems: Generate reports from existing data
• Frontend applications: Display user data without modification
• Third-party integrations: Sync data to external systems

Read-Write Access

Additional Capabilities

With write permissions, you can also:

// ✅ Create projects
const project = await client.projects.create({
  name: 'My New Project',
  description: 'A project for testing'
});

// ✅ Upload assets
const asset = await client.assets.upload({
  file: fileData,
  name: 'document.pdf',
  project_id: 'proj_123'
});

// ✅ Update resources
await client.projects.update('proj_123', {
  name: 'Updated Project Name'
});

// ✅ Create integrations
const integration = await client.integrations.create({
  type: 'webhook',
  url: 'https://your-app.com/webhook',
  events: ['asset.created']
});

Use Cases for Read-Write Access

• Content management systems: Upload and manage assets
• Data synchronization: Two-way sync with external systems
• Application backends: Full CRUD operations
• Automated workflows: Create resources based on triggers

Full Administrative Access

Admin Permissions

Administrative access includes:

// ✅ User management (Enterprise)
const users = await client.users.list();
await client.users.invite('new-user@example.com');

// ✅ Audit logs (Enterprise)
const logs = await client.audit.list({
  start_date: '2024-01-01',
  end_date: '2024-01-31'
});

// ✅ Account settings
await client.account.updateSettings({
  webhook_endpoint: 'https://your-app.com/webhooks'
});

// ✅ API key management
const keys = await client.apiKeys.list();
await client.apiKeys.create({
  name: 'New Service Key',
  permissions: ['read', 'write']
});

Use Cases for Admin Access

• Account administration: Manage team members and settings
• Security monitoring: Access audit logs and security events
• Automated key management: Programmatically manage API keys
• Enterprise integrations: Full platform control

Managing API Permissions

Setting Permissions in Dashboard

1. Navigate to API Keys in your dashboard
2. Select an existing key or create a new one
3. Choose permissions based on your needs:

{
  "permissions": ["read", "write"],
  "description": "Backend service with write access",
  "environment": "production"
}

Programmatic Permission Checks

Verify permissions before making API calls:

// Check if current key has write permissions
try {
  await client.permissions.check('write');
  // Proceed with write operation
  await client.projects.create(projectData);
} catch (error) {
  if (error.code === 'INSUFFICIENT_PERMISSIONS') {
    console.log('Key lacks write permissions');
    // Handle gracefully or request user to upgrade
  }
}

Understanding Access-Related Errors

401 Unauthorized

Cause: Invalid or missing API key

{
  "status": "error",
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "details": "Please provide a valid API key"
  }
}

Solutions:

• Check your API key is included in requests
• Verify the key hasn't been deleted or expired
• Ensure proper formatting: Bearer your_api_key

403 Forbidden

Cause: Valid key but insufficient permissions

{
  "status": "error",
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Your API key doesn't have write permissions",
    "required_permission": "write",
    "current_permissions": ["read"]
  }
}

Solutions:

• Update API key permissions in dashboard
• Use a different key with appropriate permissions
• Upgrade your account plan if needed

402 Payment Required

Cause: Feature requires a paid plan

{
  "status": "error",
  "error": {
    "code": "PLAN_UPGRADE_REQUIRED",
    "message": "This feature requires a Pro plan",
    "feature": "advanced_analytics",
    "current_plan": "free"
  }
}

Solutions:

• Upgrade your account plan
• Use alternative endpoints available on your plan
• Contact sales for enterprise features

Best Practices for Access Management

Principle of Least Privilege

Grant the minimum permissions needed:

// ✅ Good: Specific permissions for each use case
const readOnlyKey = {
  name: 'Analytics Dashboard',
  permissions: ['read'],
  description: 'For displaying account statistics'
};

const uploadKey = {
  name: 'Asset Upload Service',
  permissions: ['read', 'write'],
  description: 'For uploading user content'
};

// ❌ Avoid: Overly broad permissions
const adminKey = {
  name: 'Everything Key',
  permissions: ['read', 'write', 'delete', 'admin'],
  description: 'Just in case we need it'
};

Environment Separation

Use different access levels per environment:

Environment	Permissions	Rationale
Development	read, write, delete	Full testing capabilities
Staging	read, write	Production-like testing
Production	read, write	Minimal required access

Regular Access Reviews

Periodically review and update permissions:

1. Audit existing keys: Remove unused keys
2. Review permissions: Ensure they match current needs
3. Check usage patterns: Identify over-privileged keys
4. Update team access: Remove former team members

Monitoring Access Usage

Dashboard Analytics

Monitor API key usage in your dashboard:

• Permission utilization: Which permissions are actually used
• Endpoint access patterns: Most frequently accessed endpoints
• Error rates by permission: Failed requests due to access issues
• Team member activity: Individual usage patterns

Programmatic Monitoring

Track access patterns in your applications:

// Log permission-related errors
client.on('error', (error) => {
  if (error.code === 'INSUFFICIENT_PERMISSIONS') {
    logger.warn('Access denied', {
      endpoint: error.endpoint,
      required_permission: error.required_permission,
      api_key_id: error.api_key_id
    });
  }
});

// Monitor successful operations by permission level
client.on('request', (request) => {
  metrics.increment('api.requests', {
    permission_level: request.permission_used,
    endpoint: request.endpoint
  });
});

Access Control for Teams

Role-Based Access

Organize team members by role:

Developer Role

{
  "permissions": ["read", "write"],
  "access_level": "project_specific",
  "allowed_projects": ["proj_123", "proj_456"]
}

DevOps Role

{
  "permissions": ["read", "write", "delete"],
  "access_level": "account_wide",
  "special_permissions": ["deployment", "monitoring"]
}

Admin Role

{
  "permissions": ["read", "write", "delete", "admin"],
  "access_level": "full",
  "special_permissions": ["user_management", "billing"]
}

Project-Level Access

Control access to specific projects:

// Create project-specific API key
const projectKey = await client.apiKeys.create({
  name: 'Project Alpha Access',
  permissions: ['read', 'write'],
  scope: {
    type: 'project',
    project_ids: ['proj_alpha_123']
  }
});

// This key can only access Project Alpha resources
const assets = await projectClient.assets.list(); // ✅ Works
const allProjects = await projectClient.projects.list(); // ❌ Forbidden

Next Steps

Now that you understand API access:

1. Explore the API Reference - See all available endpoints
2. Learn About Authentication - Deep dive into security
3. Choose an Integration Guide - Build your first application
4. Select an SDK - Use our official libraries

Getting Help

Questions about API access?

• Dashboard: Manage permissions at dashboard.0link.com
• Support: Email support@0link.com for access issues
• Sales: Contact sales@0link.com for plan upgrades
• Security: Report security concerns to security@0link.com